src/docbookgen.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 1997-2022 by Dimitri van Heesch.
   4 *
   5 * Permission to use, copy, modify, and distribute this software and its
   6 * documentation under the terms of the GNU General Public License is hereby
   7 * granted. No representations are made about the suitability of this software
   8 * for any purpose. It is provided "as is" without express or implied warranty.
   9 * See the GNU General Public License for more details.
  10 *
  11 */
  12
  13 #ifndef DOCBOOKGEN_H
  14 #define DOCBOOKGEN_H
  15
  16 #include <memory>
  17 #include <array>
  18
  19 #include "config.h"
  20 #include "outputgen.h"
  21
  22 #if 0
  23 // define for cases that have been implemented with an empty body
  24 #define DB_GEN_EMPTY  m_t << "<!-- DBG_GEN_head_check " << __LINE__ << " -->\n";
  25 #else
  26 #define DB_GEN_EMPTY
  27 #endif
  28
  29 #if 0
  30 // Generic debug statements
  31 #define DB_GEN_H DB_GEN_H1(m_t)
  32 #define DB_GEN_H1(x) x << "<!-- DBG_GEN_head " << __LINE__ << " -->\n";
  33 #define DB_GEN_H2(y) DB_GEN_H2a(m_t,y)
  34 #define DB_GEN_H2a(x,y) x << "<!-- DBG_GEN_head " << __LINE__ << " " << y << " -->\n";
  35 // define for cases that have NOT yet been implemented / considered
  36 #define DB_GEN_NEW fprintf(stderr,"DBG_GEN_head %d\n",__LINE__); DB_GEN_H
  37 #else
  38 #define DB_GEN_H
  39 #define DB_GEN_H1(x)
  40 #define DB_GEN_H2(y)
  41 #define DB_GEN_H2a(x,y)
  42 #define DB_GEN_NEW
  43 #endif
  44
  45 class OutputCodeList;
  46
  47 class DocbookCodeGenerator
  48 {
  49   public:
  50     DocbookCodeGenerator(TextStream *t);
  51     void setTextStream(TextStream *t) { m_t = t; }
  52
  53     OutputType type() const { return OutputType::Docbook; }
  54
  55     void codify(const QCString &text);
  56     void writeCodeLink(CodeSymbolType type,
  57         const QCString &ref,const QCString &file,
  58         const QCString &anchor,const QCString &name,
  59         const QCString &tooltip);
  60     void writeTooltip(const QCString &, const DocLinkInfo &, const QCString &,
  61                       const QCString &, const SourceLinkInfo &, const SourceLinkInfo &
  62                      );
  63     void startCodeLine(bool);
  64     void endCodeLine();
  65     void startFontClass(const QCString &colorClass);
  66     void endFontClass();
  67     void writeCodeAnchor(const QCString &);
  68     void writeLineNumber(const QCString &extRef,const QCString &compId,
  69         const QCString &anchorId,int l, bool writeLineAnchor);
  70     void startCodeFragment(const QCString &style);
  71     void endCodeFragment(const QCString &style);
  72     void startFold(int,const QCString &,const QCString &) {}
  73     void endFold() {}
  74
  75     void setRelativePath(const QCString &path) { m_relPath = path; }
  76     void setSourceFileName(const QCString &sourceFileName) { m_sourceFileName = sourceFileName; }
  77     QCString sourceFileName() { return m_sourceFileName; }
  78     void finish();
  79
  80   private:
  81     void writeCodeLinkLine(CodeSymbolType type,
  82         const QCString &ref,const QCString &file,
  83         const QCString &anchor,const QCString &name,
  84         const QCString &tooltip, bool);
  85     TextStream *m_t;
  86     QCString    m_refId;
  87     QCString    m_external;
  88     int         m_lineNumber = -1;
  89     int         m_col = 0;
  90     bool        m_insideCodeLine = false;
  91     bool        m_insideSpecialHL = false;
  92     QCString    m_relPath;
  93     QCString    m_sourceFileName;
  94 };
  95
  96 class DocbookGenerator : public OutputGenerator
  97 {
  98   public:
  99     DocbookGenerator();
 100     DocbookGenerator(const DocbookGenerator &);
 101     DocbookGenerator &operator=(const DocbookGenerator &);
 102     DocbookGenerator(DocbookGenerator &&);
 103     DocbookGenerator &operator=(DocbookGenerator &&) = delete;
 104    ~DocbookGenerator();
 105
 106     static void init();
 107     void cleanup();
 108
 109     OutputType type() const { return OutputType::Docbook; }
 110
 111     void writeDoc(const IDocNodeAST *node,const Definition *ctx,const MemberDef *md,int id);
 112
 113     ///////////////////////////////////////////////////////////////
 114     // structural output interface
 115     ///////////////////////////////////////////////////////////////
 116     void startFile(const QCString &name,const QCString &manName,
 117                            const QCString &title,int id,int hierarchyLevel);
 118     void writeSearchInfo(){DB_GEN_EMPTY};
 119     void writeFooter(const QCString &){DB_GEN_NEW};
 120     void endFile();
 121     void startIndexSection(IndexSection);
 122     void endIndexSection(IndexSection);
 123     void writePageLink(const QCString &,bool);
 124     void startProjectNumber(){DB_GEN_NEW};
 125     void endProjectNumber(){DB_GEN_NEW};
 126     void writeStyleInfo(int){DB_GEN_EMPTY};
 127     void startTitleHead(const QCString &);
 128     void endTitleHead(const QCString &fileName,const QCString &name);
 129     void startIndexListItem(){DB_GEN_NEW};
 130     void endIndexListItem(){DB_GEN_NEW};
 131     void startIndexList(){DB_GEN_NEW};
 132     void endIndexList(){DB_GEN_NEW};
 133     void startIndexKey(){DB_GEN_NEW};
 134     void endIndexKey(){DB_GEN_NEW};
 135     void startIndexValue(bool){DB_GEN_NEW};
 136     void endIndexValue(const QCString &,bool){DB_GEN_NEW};
 137     void startItemList()  {DB_GEN_EMPTY};
 138     void endItemList()    {DB_GEN_EMPTY};
 139
 140     void startIndexItem(const QCString &,const QCString &){DB_GEN_NEW};
 141     void endIndexItem(const QCString &,const QCString &){DB_GEN_NEW};
 142     void startItemListItem() {DB_GEN_EMPTY};
 143     void endItemListItem() {DB_GEN_EMPTY};
 144     void docify(const QCString &text);
 145     void writeChar(char);
 146     void writeString(const QCString &);
 147     void startParagraph(const QCString &);
 148     void endParagraph();
 149     void writeObjectLink(const QCString &,const QCString &,const QCString &,const QCString &);
 150     void startBold();
 151     void endBold();
 152     void startTypewriter();
 153     void endTypewriter();
 154     void startEmphasis(){DB_GEN_NEW};
 155     void endEmphasis(){DB_GEN_NEW};
 156     void writeRuler();
 157     void startDescForItem(){DB_GEN_EMPTY};
 158     void endDescForItem(){DB_GEN_EMPTY};
 159     void startCenter(){DB_GEN_NEW};
 160     void endCenter(){DB_GEN_NEW};
 161     void startSmall(){DB_GEN_NEW};
 162     void endSmall(){DB_GEN_NEW};
 163     void startExamples();
 164     void endExamples();
 165     void writeAnchor(const QCString &,const QCString &){DB_GEN_EMPTY};
 166     void startSection(const QCString &,const QCString &,SectionType);
 167     void endSection(const QCString &,SectionType);
 168     void lineBreak(const QCString &);
 169     void addIndexItem(const QCString &,const QCString &);
 170     void writeNonBreakableSpace(int);
 171     void startDescTable(const QCString &);
 172     void endDescTable();
 173     void startDescTableRow();
 174     void endDescTableRow();
 175     void startDescTableTitle();
 176     void endDescTableTitle();
 177     void startDescTableData();
 178     void endDescTableData();
 179     void startTextLink(const QCString &,const QCString &){DB_GEN_NEW};
 180     void endTextLink(){DB_GEN_NEW};
 181     void startPageRef(){DB_GEN_NEW};
 182     void endPageRef(const QCString &,const QCString &){DB_GEN_NEW};
 183
 184     void startGroupHeader(int);
 185     void endGroupHeader(int);
 186     void startMemberSections(){DB_GEN_EMPTY};
 187     void endMemberSections(){DB_GEN_EMPTY};
 188     void startHeaderSection(){DB_GEN_EMPTY};
 189     void endHeaderSection(){DB_GEN_EMPTY};
 190     void startMemberHeader(const QCString &anchor, int typ);
 191     void endMemberHeader();
 192     void startMemberSubtitle(){DB_GEN_EMPTY};
 193     void endMemberSubtitle(){DB_GEN_EMPTY};
 194     void startMemberDocList();
 195     void endMemberDocList();
 196     void startMemberList();
 197     void endMemberList();
 198     void startInlineHeader(){DB_GEN_NEW};
 199     void endInlineHeader(){DB_GEN_NEW};
 200     void startAnonTypeScope(int){DB_GEN_EMPTY};
 201     void endAnonTypeScope(int){DB_GEN_EMPTY};
 202     void startMemberItem(const QCString &,MemberItemType,const QCString &);
 203     void endMemberItem(MemberItemType);
 204     void startMemberTemplateParams();
 205     void endMemberTemplateParams(const QCString &,const QCString &);
 206     void startCompoundTemplateParams();
 207     void endCompoundTemplateParams();
 208     void startMemberGroupHeader(bool);
 209     void endMemberGroupHeader();
 210     void startMemberGroupDocs(){DB_GEN_EMPTY};
 211     void endMemberGroupDocs(){DB_GEN_EMPTY};
 212     void startMemberGroup();
 213     void endMemberGroup(bool);
 214     void insertMemberAlign(bool){DB_GEN_EMPTY};
 215     void insertMemberAlignLeft(MemberItemType,bool){DB_GEN_EMPTY};
 216     void startMemberDoc(const QCString &,const QCString &,
 217                         const QCString &,const QCString &,int,int,bool);
 218     void endMemberDoc(bool);
 219     void startDoxyAnchor(const QCString &fName,const QCString &manName,
 220                          const QCString &anchor,const QCString &name,
 221                          const QCString &args);
 222     void endDoxyAnchor(const QCString &fileName,const QCString &anchor);
 223     void writeLatexSpacing(){DB_GEN_EMPTY}
 224     void writeStartAnnoItem(const QCString &,const QCString &,
 225                             const QCString &,const QCString &){DB_GEN_NEW};
 226     void startMemberDescription(const QCString &,const QCString &,bool){DB_GEN_EMPTY};
 227     void endMemberDescription(){DB_GEN_EMPTY};
 228     void startMemberDeclaration(){DB_GEN_EMPTY};
 229     void endMemberDeclaration(const QCString &,const QCString &){DB_GEN_EMPTY};
 230     void writeInheritedSectionTitle(const QCString &,const QCString &,
 231                                     const QCString &,const QCString &,
 232                                     const QCString &,const QCString &);
 233     void startIndent(){DB_GEN_EMPTY};
 234     void endIndent(){DB_GEN_EMPTY};
 235     void writeSynopsis(){DB_GEN_EMPTY};
 236     void startClassDiagram();
 237     void endClassDiagram(const ClassDiagram &,const QCString &,const QCString &);
 238     void startDotGraph();
 239     void endDotGraph(DotClassGraph &g);
 240     void startInclDepGraph();
 241     void endInclDepGraph(DotInclDepGraph &g);
 242     void startGroupCollaboration();
 243     void endGroupCollaboration(DotGroupCollaboration &g);
 244     void startCallGraph();
 245     void endCallGraph(DotCallGraph &g);
 246     void startDirDepGraph();
 247     void endDirDepGraph(DotDirDeps &g);
 248     void writeGraphicalHierarchy(DotGfxHierarchyTable &){DB_GEN_NEW};
 249     void startQuickIndices(){DB_GEN_EMPTY};
 250     void endQuickIndices(){DB_GEN_EMPTY};
 251     void writeSplitBar(const QCString &){DB_GEN_EMPTY};
 252     void writeNavigationPath(const QCString &){DB_GEN_NEW};
 253     void writeLogo(){DB_GEN_NEW};
 254     void writeQuickLinks(bool,HighlightedItem,const QCString &,bool){DB_GEN_EMPTY};
 255     void writeSummaryLink(const QCString &,const QCString &,const QCString &,bool){DB_GEN_EMPTY};
 256     void startContents(){DB_GEN_EMPTY};
 257     void endContents(){DB_GEN_EMPTY};
 258     void startPageDoc(const QCString &){DB_GEN_EMPTY}
 259     void endPageDoc() {DB_GEN_EMPTY}
 260     void startTextBlock(bool);
 261     void endTextBlock(bool);
 262     void lastIndexPage(){DB_GEN_EMPTY};
 263     void startMemberDocPrefixItem();
 264     void endMemberDocPrefixItem();
 265     void startMemberDocName(bool);
 266     void endMemberDocName();
 267     void startParameterType(bool,const QCString &){DB_GEN_EMPTY};
 268     void endParameterType(){DB_GEN_EMPTY};
 269     void startParameterName(bool);
 270     void endParameterName(bool,bool,bool);
 271     void startParameterList(bool);
 272     void endParameterList();
 273     void exceptionEntry(const QCString &,bool);
 274
 275     void startConstraintList(const QCString &);
 276     void startConstraintParam();
 277     void endConstraintParam();
 278     void startConstraintType();
 279     void endConstraintType();
 280     void startConstraintDocs();
 281     void endConstraintDocs();
 282     void endConstraintList();
 283
 284     void startMemberDocSimple(bool);
 285     void endMemberDocSimple(bool);
 286     void startInlineMemberType();
 287     void endInlineMemberType();
 288     void startInlineMemberName();
 289     void endInlineMemberName();
 290     void startInlineMemberDoc();
 291     void endInlineMemberDoc();
 292
 293     void startLabels();
 294     void writeLabel(const QCString &,bool);
 295     void endLabels();
 296
 297     void writeLocalToc(const SectionRefs &sr,const LocalToc &lt);
 298
 299     void setCurrentDoc(const Definition *,const QCString &,bool) {DB_GEN_EMPTY}
 300     void addWord(const QCString &,bool) {DB_GEN_EMPTY}
 301
 302     void addCodeGen(OutputCodeList &list);
 303 private:
 304     void openSection(const QCString &attr=QCString());
 305     void closeSection();
 306     void closeAllSections();
 307
 308     QCString relPath;
 309     std::unique_ptr<OutputCodeList>  m_codeList;
 310     DocbookCodeGenerator *m_codeGen = nullptr;
 311     bool m_denseText = false;
 312     bool m_inGroup = false;
 313     int  m_levelListItem = 0;
 314     std::array<bool,20> m_inListItem = { false, };
 315     std::array<bool,20> m_inSimpleSect = { false, };
 316     bool m_descTable = false;
 317     bool m_simpleTable = false;
 318     int m_inLevel = -1;
 319     bool m_firstMember = false;
 320     int m_openSectionCount = 0;
 321     QCString m_pageLinks;
 322 };
 323
 324 QCString convertToDocBook(const QCString &s, const bool retainNewline = false);
 325
 326
 327 #endif