mandocvisitor.cpp

Go to the documentation of this file.

/******************************************************************************
 *
 * Copyright (C) 1997-2020 by Dimitri van Heesch.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby
 * granted. No representations are made about the suitability of this software
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */
 
// own header
#include "mandocvisitor.h"
 
// other includes
#include "cite.h"
#include "code.h"
#include "codefragment.h"
#include "docparser.h"
#include "dot.h"
#include "doxygen.h"
#include "emoji.h"
#include "filedef.h"
#include "fileinfo.h"
#include "htmlentity.h"
#include "language.h"
#include "message.h"
#include "outputlist.h"
#include "parserintf.h"
#include "util.h"
 
ManDocVisitor::ManDocVisitor(TextStream &t,OutputCodeList &ci,
                             const DString &langExt)
  : m_t(t), m_ci(ci), m_insidePre(false), m_hide(false), m_firstCol(false),
    m_indent(0), m_langExt(langExt)
{
}
 
  //--------------------------------------
  // visitor functions for leaf nodes
  //--------------------------------------
 
void ManDocVisitor::operator()(const DocWord &w)
{
  if (m_hide) return;
  filter(w.word());
  m_firstCol=false;
}
 
void ManDocVisitor::operator()(const DocLinkedWord &w)
{
  if (m_hide) return;
  m_t << "\\fB";
  filter(w.word());
  m_t << "\\fP";
  m_firstCol=false;
}
 
void ManDocVisitor::operator()(const DocWhiteSpace &w)
{
  if (m_hide) return;
  if (m_insidePre)
  {
    m_t << w.chars();
    m_firstCol=w.chars().at(w.chars().length()-1)=='\n';
  }
  else if (!m_firstCol)
  {
    m_t << " ";
  }
  else
  {
    m_firstCol=false;
  }
}
 
void ManDocVisitor::operator()(const DocSymbol &s)
{
  if (m_hide) return;
  const char *res = HtmlEntityMapper::instance().man(s.symbol());
  if (res)
  {
    m_t << res;
  }
  else
  {
    // no error or warning to be supplied
    // err("man: non supported HTML-entity found: &{};\n",get_symbol_item(s->symbol()));
  }
  m_firstCol=false;
}
 
void ManDocVisitor::operator()(const DocEmoji &s)
{
  if (m_hide) return;
  const char *res = EmojiEntityMapper::instance().name(s.index());
  if (res)
  {
    m_t << res;
  }
  else
  {
    m_t << s.name();
  }
  m_firstCol=false;
}
 
void ManDocVisitor::operator()(const DocURL &u)
{
  if (m_hide) return;
  m_t << u.url();
  m_firstCol=false;
}
 
void ManDocVisitor::operator()(const DocLineBreak &)
{
  if (m_hide) return;
  m_t << "\n.br\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocHorRuler &)
{
  if (m_hide) return;
  if (!m_firstCol) m_t << "\n";
  m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocStyleChange &s)
{
  if (m_hide) return;
  switch (s.style())
  {
    case DocStyleChange::Bold:
      if (s.enable()) m_t << "\\fB";      else m_t << "\\fP";
      m_firstCol=false;
      break;
    case DocStyleChange::S:
    case DocStyleChange::Strike:
    case DocStyleChange::Del:
      /* not supported */
      break;
    case DocStyleChange::Underline: //underline is shown as emphasis
    case DocStyleChange::Ins:
      if (s.enable()) m_t << "\\fI";     else m_t << "\\fP";
      m_firstCol=false;
      break;
    case DocStyleChange::Italic:
      if (s.enable()) m_t << "\\fI";     else m_t << "\\fP";
      m_firstCol=false;
      break;
    case DocStyleChange::Kbd:
    case DocStyleChange::Typewriter:
    case DocStyleChange::Code:
      if (s.enable()) m_t << "\\fR";   else m_t << "\\fP";
      m_firstCol=false;
      break;
    case DocStyleChange::Subscript:
      if (s.enable()) m_t << "\\*<";    else m_t << "\\*> ";
      m_firstCol=false;
      break;
    case DocStyleChange::Superscript:
      if (s.enable()) m_t << "\\*{";    else m_t << "\\*} ";
      m_firstCol=false;
      break;
    case DocStyleChange::Center:
      /* not supported */
      break;
    case DocStyleChange::Small:
      /* not supported */
      break;
    case DocStyleChange::Cite:
      /* not supported */
      break;
    case DocStyleChange::Preformatted:
      if (s.enable())
      {
        if (!m_firstCol) m_t << "\n";
        m_t << ".PP\n";
        m_t << ".nf\n";
        m_insidePre=true;
      }
      else
      {
        m_insidePre=false;
        if (!m_firstCol) m_t << "\n";
        m_t << ".fi\n";
        m_t << ".PP\n";
        m_firstCol=true;
      }
      break;
    case DocStyleChange::Div:  /* HTML only */ break;
    case DocStyleChange::Span: /* HTML only */ break;
  }
}
 
void ManDocVisitor::operator()(const DocVerbatim &s)
{
  if (m_hide) return;
  DString lang = m_langExt;
  if (!s.language().empty()) // explicit language setting
  {
    lang = s.language();
  }
  SrcLangExt langExt = getLanguageFromCodeLang(lang);
  switch (s.type())
  {
    case DocVerbatim::Code:
      if (!m_firstCol) m_t << "\n";
      m_t << ".PP\n";
      m_t << ".nf\n";
      getCodeParser(lang).parseCode(m_ci,s.context(),s.text(),
                                    langExt,
                                    Config_getBool(STRIP_CODE_COMMENTS),
                                    CodeParserOptions().setExample(s.isExample(),s.exampleFile())
                                   );
      if (!m_firstCol) m_t << "\n";
      m_t << ".fi\n";
      m_t << ".PP\n";
      m_firstCol=true;
      break;
    case DocVerbatim::JavaDocLiteral:
      filter(s.text(),true);
      break;
    case DocVerbatim::JavaDocCode:
      m_t << "\\fR\n";
      filter(s.text(),true);
      m_t << "\\fP\n";
      break;
    case DocVerbatim::Verbatim:
      if (!m_firstCol) m_t << "\n";
      m_t << ".PP\n";
      m_t << ".nf\n";
      filter(s.text(),true);
      if (!m_firstCol) m_t << "\n";
      m_t << ".fi\n";
      m_t << ".PP\n";
      m_firstCol=true;
      break;
    case DocVerbatim::ManOnly:
      m_t << s.text();
      break;
    case DocVerbatim::HtmlOnly:
    case DocVerbatim::XmlOnly:
    case DocVerbatim::LatexOnly:
    case DocVerbatim::RtfOnly:
    case DocVerbatim::DocbookOnly:
    case DocVerbatim::Dot:
    case DocVerbatim::Msc:
    case DocVerbatim::PlantUML:
    case DocVerbatim::Mermaid:
      /* nothing */
      break;
  }
}
 
void ManDocVisitor::operator()(const DocAnchor &)
{
  /* no support for anchors in man pages */
}
 
void ManDocVisitor::operator()(const DocInclude &inc)
{
  if (m_hide) return;
  SrcLangExt langExt = getLanguageFromFileName(inc.extension());
  switch(inc.type())
  {
    case DocInclude::IncWithLines:
      {
         if (!m_firstCol) m_t << "\n";
         m_t << ".PP\n";
         m_t << ".nf\n";
         FileInfo cfi( inc.file().str() );
         auto fd = createFileDef( cfi.dirPath(), cfi.fileName() );
         getCodeParser(inc.extension()).parseCode(m_ci,inc.context(),
                                                  inc.text(),
                                                  langExt,
                                                  inc.stripCodeComments(),
                                                  CodeParserOptions()
                                                  .setExample(inc.isExample(),inc.exampleFile())
                                                  .setFileDef(fd.get())
                                                  .setInlineFragment(true)
                                                 );
         m_t << ".fi\n";
         m_t << ".PP\n";
         m_firstCol=true;
      }
      break;
    case DocInclude::Include:
      if (!m_firstCol) m_t << "\n";
      m_t << ".PP\n";
      m_t << ".nf\n";
      getCodeParser(inc.extension()).parseCode(m_ci,inc.context(),
                                               inc.text(),
                                               langExt,
                                               inc.stripCodeComments(),
                                               CodeParserOptions()
                                               .setExample(inc.isExample(),inc.exampleFile())
                                               .setInlineFragment(true)
                                               .setShowLineNumbers(false)
                                              );
      m_t << ".fi\n";
      m_t << ".PP\n";
      m_firstCol=true;
      break;
    case DocInclude::DontInclude:
    case DocInclude::DontIncWithLines:
    case DocInclude::HtmlInclude:
    case DocInclude::LatexInclude:
    case DocInclude::RtfInclude:
    case DocInclude::XmlInclude:
    case DocInclude::DocbookInclude:
      break;
    case DocInclude::ManInclude:
      m_t << inc.text();
      break;
    case DocInclude::VerbInclude:
      if (!m_firstCol) m_t << "\n";
      m_t << ".PP\n";
      m_t << ".nf\n";
      m_t << inc.text();
      if (!m_firstCol) m_t << "\n";
      m_t << ".fi\n";
      m_t << ".PP\n";
      m_firstCol=true;
      break;
    case DocInclude::Snippet:
    case DocInclude::SnippetWithLines:
      if (!m_firstCol) m_t << "\n";
      m_t << ".PP\n";
      m_t << ".nf\n";
      CodeFragmentManager::instance().parseCodeFragment(m_ci,
                                                        inc.file(),
                                                        inc.blockId(),
                                                        inc.context(),
                                                        inc.type()==DocInclude::SnippetWithLines,
                                                        inc.trimLeft(),
                                                        inc.stripCodeComments()
                                                       );
      m_t << ".fi\n";
      m_t << ".PP\n";
      m_firstCol=true;
      break;
  }
}
 
void ManDocVisitor::operator()(const DocIncOperator &op)
{
  DString locLangExt = getFileNameExtension(op.includeFileName());
  if (locLangExt.empty()) locLangExt = m_langExt;
  SrcLangExt langExt = getLanguageFromFileName(locLangExt);
  //printf("DocIncOperator: type=%d first=%d, last=%d text='%s'\n",
  //    op.type(),op.isFirst(),op.isLast(),qPrint(op.text()));
  if (op.isFirst())
  {
    if (!m_hide)
    {
      if (!m_firstCol) m_t << "\n";
      m_t << ".PP\n";
      m_t << ".nf\n";
    }
    pushHidden(m_hide);
    m_hide = true;
  }
  if (op.type()!=DocIncOperator::Skip)
  {
    m_hide = popHidden();
    if (!m_hide)
    {
      std::unique_ptr<FileDef> fd;
      if (!op.includeFileName().empty())
      {
        FileInfo cfi( op.includeFileName().str() );
        fd = createFileDef( cfi.dirPath(), cfi.fileName() );
      }
 
      getCodeParser(locLangExt).parseCode(m_ci,op.context(),op.text(),langExt,
                                          op.stripCodeComments(),
                                          CodeParserOptions()
                                          .setExample(op.isExample(),op.exampleFile())
                                          .setFileDef(fd.get())
                                          .setShowLineNumbers(op.showLineNo())
                                         );
    }
    pushHidden(m_hide);
    m_hide=true;
  }
  if (op.isLast())
  {
    m_hide = popHidden();
    if (!m_hide)
    {
      if (!m_firstCol) m_t << "\n";
      m_t << ".fi\n";
      m_t << ".PP\n";
      m_firstCol=true;
    }
  }
  else
  {
    if (!m_hide) m_t << "\n";
  }
}
 
void ManDocVisitor::operator()(const DocFormula &f)
{
  if (m_hide) return;
  m_t << f.text();
}
 
void ManDocVisitor::operator()(const DocIndexEntry &)
{
}
 
void ManDocVisitor::operator()(const DocSimpleSectSep &)
{
}
 
void ManDocVisitor::operator()(const DocCite &cite)
{
  if (m_hide) return;
  m_t << "\\fB";
  auto opt = cite.option();
  DString txt;
  if (!cite.file().empty())
  {
    txt = cite.getText();
    filter(txt, false, true);
  }
  else
  {
    if (!opt.noPar()) txt += "[";
    txt += cite.target();
    if (!opt.noPar()) txt += "]";
    filter(txt);
  }
  m_t << "\\fP";
}
 
void ManDocVisitor::operator()(const DocSeparator &s)
{
  if (m_hide) return;
  m_t << s.chars();
}
 
 
//--------------------------------------
// visitor functions for compound nodes
//--------------------------------------
 
void ManDocVisitor::operator()(const DocAutoList &l)
{
  if (m_hide) return;
  m_indent++;
  visitChildren(l);
  m_indent--;
  m_t << ".PP\n";
}
 
void ManDocVisitor::operator()(const DocAutoListItem &li)
{
  if (m_hide) return;
  DString ws;
  if (m_indent>0) ws.fill(' ',2*(m_indent-1));
  if (!m_firstCol) m_t << "\n";
  m_t << ".IP \"" << ws;
  const DocAutoList *list = std::get_if<DocAutoList>(li.parent());
  if (list && list->isEnumList())
  {
    m_t << li.itemNumber() << ".\" " << (2*(m_indent+1));
  }
  else // bullet list
  {
    switch (li.itemNumber())
    {
      case DocAutoList::Unchecked: // unchecked
        m_t << "[ ]\" " << (2*m_indent) + 2;
        break;
      case DocAutoList::Checked_x: // checked with x
        m_t << "[x]\" " << (2*m_indent) + 2;
        break;
      case DocAutoList::Checked_X: // checked with X
        m_t << "[X]\" " << (2*m_indent) + 2;
        break;
      default:
        m_t << "\\(bu\" " << (2*m_indent);
        break;
    }
  }
  m_t << "\n";
  m_firstCol=true;
  visitChildren(li);
  m_t << "\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocPara &p)
{
  if (m_hide) return;
  visitChildren(p);
  if (!p.isLast() &&            // omit <p> for last paragraph
      !(p.parent() &&           // and for parameter sections
        std::get_if<DocParamSect>(p.parent())
       )
     )
  {
    if (!m_firstCol) m_t << "\n";
    m_t << "\n.PP\n";
    m_firstCol=true;
  }
}
 
void ManDocVisitor::operator()(const DocRoot &r)
{
  visitChildren(r);
}
 
void ManDocVisitor::operator()(const DocSimpleSect &s)
{
  if (m_hide) return;
  if (!m_firstCol)
  {
    m_t << "\n";
    m_t << ".PP\n";
  }
  m_t << "\\fB";
  switch(s.type())
  {
    case DocSimpleSect::See:
      m_t << theTranslator->trSeeAlso(); break;
    case DocSimpleSect::Return:
      m_t << theTranslator->trReturns(); break;
    case DocSimpleSect::Author:
      m_t << theTranslator->trAuthor(true,true); break;
    case DocSimpleSect::Authors:
      m_t << theTranslator->trAuthor(true,false); break;
    case DocSimpleSect::Version:
      m_t << theTranslator->trVersion(); break;
    case DocSimpleSect::Since:
      m_t << theTranslator->trSince(); break;
    case DocSimpleSect::Date:
      m_t << theTranslator->trDate(); break;
    case DocSimpleSect::Note:
      m_t << theTranslator->trNote(); break;
    case DocSimpleSect::Warning:
      m_t << theTranslator->trWarning(); break;
    case DocSimpleSect::Pre:
      m_t << theTranslator->trPrecondition(); break;
    case DocSimpleSect::Post:
      m_t << theTranslator->trPostcondition(); break;
    case DocSimpleSect::Copyright:
      m_t << theTranslator->trCopyright(); break;
    case DocSimpleSect::Invar:
      m_t << theTranslator->trInvariant(); break;
    case DocSimpleSect::Remark:
      m_t << theTranslator->trRemarks(); break;
    case DocSimpleSect::Attention:
      m_t << theTranslator->trAttention(); break;
    case DocSimpleSect::Important:
      m_t << theTranslator->trImportant(); break;
    case DocSimpleSect::User: break;
    case DocSimpleSect::Rcs: break;
    case DocSimpleSect::Unknown:  break;
  }
 
  // special case 1: user defined title
  if (s.title())
  {
    std::visit(*this,*s.title());
  }
  m_t << "\\fP\n";
  m_t << ".RS 4\n";
  visitChildren(s);
  if (!m_firstCol) m_t << "\n";
  m_t << ".RE\n";
  m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocTitle &t)
{
  if (m_hide) return;
  visitChildren(t);
}
 
void ManDocVisitor::operator()(const DocSimpleList &l)
{
  if (m_hide) return;
  m_indent++;
  if (!m_firstCol) m_t << "\n";
  m_t << ".PD 0\n";
  m_firstCol=true;
  visitChildren(l);
  m_indent--;
  m_t << ".PP\n";
}
 
void ManDocVisitor::operator()(const DocSimpleListItem &li)
{
  if (m_hide) return;
  DString ws;
  if (m_indent>0) ws.fill(' ',2*(m_indent-1));
  if (!m_firstCol) m_t << "\n";
  m_t << ".IP \"" << ws << "\\(bu\" " << m_indent << "\n";
  m_firstCol=true;
  if (li.paragraph())
  {
    visit(*this,*li.paragraph());
  }
  m_t << "\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocSection &s)
{
  if (m_hide) return;
  if (!m_firstCol) m_t << "\n";
  if (s.level()==1) m_t << ".SH"; else m_t << ".SS";
  m_t << " \"";
  if (s.title())
  {
    std::visit(*this,*s.title());
  }
  m_t << "\"\n";
  if (s.level()==1) m_t << ".PP\n";
  m_firstCol=true;
  visitChildren(s);
}
 
void ManDocVisitor::operator()(const DocHtmlList &l)
{
  if (m_hide) return;
  m_indent++;
  if (!m_firstCol) m_t << "\n";
  m_t << ".PD 0\n";
  m_firstCol=true;
  int indent = std::min(m_indent,maxIndentLevels-1);
  m_listItemInfo[indent].number = 1;
  m_listItemInfo[indent].type   = '1';
  for (const auto &opt : l.attribs())
  {
    if (opt.name=="type")
    {
      m_listItemInfo[indent].type = opt.value[0];
    }
    if (opt.name=="start")
    {
      bool ok = false;
      int val = opt.value.toInt(&ok);
      if (ok) m_listItemInfo[indent].number = val;
    }
  }
  visitChildren(l);
  m_indent--;
  if (!m_firstCol) m_t << "\n";
  m_t << ".PP\n";
}
 
void ManDocVisitor::operator()(const DocHtmlListItem &li)
{
  if (m_hide) return;
  DString ws;
  if (m_indent>0) ws.fill(' ',2*(m_indent-1));
  if (!m_firstCol) m_t << "\n";
  m_t << ".IP \"" << ws;
  const DocHtmlList *list = std::get_if<DocHtmlList>(li.parent());
  if (list && list->type()==DocHtmlList::Ordered)
  {
    int indent = std::min(m_indent,maxIndentLevels-1);
    for (const auto &opt : li.attribs())
    {
      if (opt.name=="value")
      {
        bool ok = false;
        int val = opt.value.toInt(&ok);
        if (ok) m_listItemInfo[indent].number = val;
      }
    }
    switch (m_listItemInfo[indent].type)
    {
      case '1':
        m_t << m_listItemInfo[indent].number;
        break;
      case 'a':
        m_t << DString::integerToAlpha(m_listItemInfo[indent].number,false);
        break;
      case 'A':
        m_t << DString::integerToAlpha(m_listItemInfo[indent].number);
        break;
      case 'i':
        m_t << DString::integerToRoman(m_listItemInfo[indent].number,false);
        break;
      case 'I':
        m_t << DString::integerToRoman(m_listItemInfo[indent].number);
        break;
      default:
        m_t << m_listItemInfo[indent].number;
        break;
    }
    m_t << ".\" " << ((m_indent+1)*2);
    m_listItemInfo[indent].number++;
  }
  else // bullet list
  {
    m_t << "\\(bu\" " << (m_indent*2);
  }
  m_t << "\n";
  m_firstCol=true;
  visitChildren(li);
  m_t << "\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocHtmlDescList &dl)
{
  if (m_hide) return;
  m_indent+=2;
  visitChildren(dl);
  m_indent-=2;
  if (!m_firstCol) m_t << "\n";
  m_t << "\n.PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocHtmlDescTitle &dt)
{
  if (m_hide) return;
  if (!m_firstCol) m_t << "\n";
  m_t << "\n.PP";
  m_t << "\n.IP \"\\fB";
  m_firstCol=false;
  visitChildren(dt);
}
 
void ManDocVisitor::operator()(const DocHtmlDescData &dd)
{
  if (!m_firstCol) m_t << "\n";
  m_t << ".IP \"\" 1c\n";
  m_firstCol=true;
  visitChildren(dd);
}
 
void ManDocVisitor::operator()(const DocHtmlTable &t)
{
  visitChildren(t);
}
 
void ManDocVisitor::operator()(const DocHtmlCaption &c)
{
  visitChildren(c);
}
 
void ManDocVisitor::operator()(const DocHtmlRow &r)
{
  visitChildren(r);
}
 
void ManDocVisitor::operator()(const DocHtmlCell &c)
{
  visitChildren(c);
}
 
void ManDocVisitor::operator()(const DocInternal &i)
{
  visitChildren(i);
}
 
void ManDocVisitor::operator()(const DocHRef &href)
{
  if (m_hide) return;
  m_t << "\\fR";
  visitChildren(href);
  m_t << "\\fP";
}
 
void ManDocVisitor::operator()(const DocHtmlSummary &s)
{
  m_t << "\\fB";
  visitChildren(s);
  m_t << "\\fP\n.PP\n";
}
 
void ManDocVisitor::operator()(const DocHtmlDetails &d)
{
  if (m_hide) return;
  if (!m_firstCol)
  {
    m_t << "\n";
    m_t << ".PP\n";
  }
  auto summary = d.summary();
  if (summary)
  {
    std::visit(*this,*summary);
    m_t << ".PP\n";
    m_t << ".RS 4\n";
  }
  visitChildren(d);
  if (!m_firstCol) m_t << "\n";
  if (summary)
  {
    m_t << ".RE\n";
  }
  m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocHtmlHeader &header)
{
  if (m_hide) return;
  if (!m_firstCol) m_t << "\n";
  if (header.level()==1) m_t << ".SH"; else m_t << ".SS";
  m_t << " \"";
  visitChildren(header);
  m_t << "\"\n";
  if (header.level()==1) m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocImage &)
{
}
 
void ManDocVisitor::operator()(const DocDotFile &)
{
}
 
void ManDocVisitor::operator()(const DocMscFile &)
{
}
 
void ManDocVisitor::operator()(const DocDiaFile &)
{
}
 
void ManDocVisitor::operator()(const DocPlantUmlFile &)
{
}
 
void ManDocVisitor::operator()(const DocMermaidFile &)
{
}
 
void ManDocVisitor::operator()(const DocLink &dl)
{
  if (m_hide) return;
  m_t << "\\fB";
  visitChildren(dl);
  m_t << "\\fP";
}
 
void ManDocVisitor::operator()(const DocRef &ref)
{
  if (m_hide) return;
  m_t << "\\fB";
  if (!ref.hasLinkText()) filter(ref.targetTitle());
  visitChildren(ref);
  m_t << "\\fP";
}
 
void ManDocVisitor::operator()(const DocSecRefItem &ref)
{
  if (m_hide) return;
  DString ws;
  if (m_indent>0) ws.fill(' ',2*(m_indent-1));
  if (!m_firstCol) m_t << "\n";
  m_t << ".IP \"" << ws << "\\(bu\" " << (2*m_indent) << "\n";
  m_firstCol=true;
  visitChildren(ref);
  m_t << "\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocSecRefList &l)
{
  if (m_hide) return;
  m_indent++;
  visitChildren(l);
  m_indent--;
  if (!m_firstCol) m_t << "\n";
  m_t << ".PP\n";
}
 
void ManDocVisitor::operator()(const DocParamSect &s)
{
  if (m_hide) return;
  if (!m_firstCol)
  {
    m_t << "\n";
    m_t << ".PP\n";
  }
  m_t << "\\fB";
  switch(s.type())
  {
    case DocParamSect::Param:
      m_t << theTranslator->trParameters(); break;
    case DocParamSect::RetVal:
      m_t << theTranslator->trReturnValues(); break;
    case DocParamSect::Exception:
      m_t << theTranslator->trExceptions(); break;
    case DocParamSect::TemplateParam:
      m_t << theTranslator->trTemplateParameters(); break;
    default:
      ASSERT(0);
  }
  m_t << "\\fP\n";
  m_t << ".RS 4\n";
  visitChildren(s);
  if (!m_firstCol) m_t << "\n";
  m_t << ".RE\n";
  m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocParamList &pl)
{
  if (m_hide) return;
  m_t << "\\fI";
  bool first=true;
  for (const auto &param : pl.parameters())
  {
    if (!first) m_t << ","; else first=false;
    std::visit(*this,param);
  }
  m_t << "\\fP ";
  for (const auto &par : pl.paragraphs())
  {
    std::visit(*this,par);
  }
  if (!pl.isLast())
  {
    if (!m_firstCol) m_t << "\n";
    m_t << ".br\n";
  }
}
 
void ManDocVisitor::operator()(const DocXRefItem &x)
{
  if (m_hide) return;
  if (x.title().empty()) return;
  if (!m_firstCol)
  {
    m_t << "\n";
    m_t << ".PP\n";
  }
  m_t << "\\fB";
  filter(x.title());
  m_t << "\\fP\n";
  m_t << ".RS 4\n";
  visitChildren(x);
  if (x.title().empty()) return;
  if (!m_firstCol) m_t << "\n";
  m_t << ".RE\n";
  m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocInternalRef &ref)
{
  if (m_hide) return;
  m_t << "\\fB";
  visitChildren(ref);
  m_t << "\\fP";
}
 
void ManDocVisitor::operator()(const DocText &t)
{
  visitChildren(t);
}
 
void ManDocVisitor::operator()(const DocHtmlBlockQuote &q)
{
  if (m_hide) return;
  if (!m_firstCol)
  {
    m_t << "\n";
    m_t << ".PP\n";
  }
  m_t << ".RS 4\n"; // TODO: add support for nested block quotes
  visitChildren(q);
  if (!m_firstCol) m_t << "\n";
  m_t << ".RE\n";
  m_t << ".PP\n";
  m_firstCol=true;
}
 
void ManDocVisitor::operator()(const DocVhdlFlow &)
{
}
 
void ManDocVisitor::operator()(const DocParBlock &pb)
{
  visitChildren(pb);
}
 
void ManDocVisitor::filter(const DString &str, const bool retainNewline, const bool citeEntry)
{
  if (!str.empty())
  {
    const char *p=str.data();
    char c=0;
    bool insideDoubleQuote = false;
    while ((c=*p++))
    {
      switch(c)
      {
        case '.':  m_t << "\\&."; break; // see  bug652277
        case '\\': m_t << "\\\\"; break;
        case '\"': m_t << "\""; insideDoubleQuote = !insideDoubleQuote; break;
        case '\n': if (retainNewline || !insideDoubleQuote) m_t << c; break;
        case '&':  // possibility to have a special symbol
          if (!citeEntry) { m_t << c; break;}
          p = HtmlEntityMapper::instance().writeHtmlEntity(
              m_t,
              p-1,
              [](HtmlEntityMapper::SymType symType) { return HtmlEntityMapper::instance().man(symType); },
              "&");
          break;
        default: m_t << c; break;
      }
    }
  }
}