doxygen
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 : public OutputCodeIntf
48 {
49  public:
50  DocbookCodeGenerator(TextStream *t);
51  void setTextStream(TextStream *t) { m_t = t; }
52 
53  OutputType type() const override { return OutputType::Docbook; }
54  std::unique_ptr<OutputCodeIntf> clone() override { return std::make_unique<DocbookCodeGenerator>(m_t); }
55  void codify(const QCString &text) override;
56  void stripCodeComments(bool b) override;
57  void startSpecialComment() override;
58  void endSpecialComment() override;
59  void setStripIndentAmount(size_t amount) override;
60  void writeCodeLink(CodeSymbolType type,
61  const QCString &ref,const QCString &file,
62  const QCString &anchor,const QCString &name,
63  const QCString &tooltip) override;
64  void writeTooltip(const QCString &, const DocLinkInfo &, const QCString &,
65  const QCString &, const SourceLinkInfo &, const SourceLinkInfo &
66  ) override;
67  void startCodeLine(int) override;
68  void endCodeLine() override;
69  void startFontClass(const QCString &colorClass) override;
70  void endFontClass() override;
71  void writeCodeAnchor(const QCString &) override;
72  void writeLineNumber(const QCString &extRef,const QCString &compId,
73  const QCString &anchorId,int l, bool writeLineAnchor) override;
74  void startCodeFragment(const QCString &style) override;
75  void endCodeFragment(const QCString &style) override;
76  void startFold(int,const QCString &,const QCString &) override {}
77  void endFold() override {}
78 
79  void setRelativePath(const QCString &path) { m_relPath = path; }
80  void setSourceFileName(const QCString &sourceFileName) { m_sourceFileName = sourceFileName; }
81  QCString sourceFileName() { return m_sourceFileName; }
82  void finish();
83 
84  private:
85  void writeCodeLinkLine(CodeSymbolType type,
86  const QCString &ref,const QCString &file,
87  const QCString &anchor,const QCString &name,
88  const QCString &tooltip, bool);
89  TextStream *m_t;
90  QCString m_refId;
91  QCString m_external;
92  int m_lineNumber = -1;
93  size_t m_col = 0;
94  bool m_insideCodeLine = false;
95  bool m_insideSpecialHL = false;
96  QCString m_relPath;
97  QCString m_sourceFileName;
98  bool m_stripCodeComments = false;
99  bool m_hide = false;
100  size_t m_stripIndentAmount = 0;
101 };
102 
103 class DocbookGenerator : public OutputGenerator, public OutputGenIntf
104 {
105  public:
106  DocbookGenerator();
107  DocbookGenerator(const DocbookGenerator &);
108  DocbookGenerator &operator=(const DocbookGenerator &);
109  DocbookGenerator(DocbookGenerator &&) = delete;
110  DocbookGenerator &operator=(DocbookGenerator &&) = delete;
111  ~DocbookGenerator();
112 
113  static void init();
114 
115  //void setCurrentDoc(const Definition *,const QCString &,bool) override {DB_GEN_EMPTY}
116  //void addWord(const QCString &,bool) override {DB_GEN_EMPTY}
117 
118  //--------------------------------------
119 
120  OutputType type() const override { return OutputType::Docbook; }
121  std::unique_ptr<OutputGenIntf> clone() override { return std::make_unique<DocbookGenerator>(*this); }
122  void addCodeGen(OutputCodeList &list) override;
123  void cleanup() override;
124  void writeDoc(const IDocNodeAST *node,const Definition *ctx,const MemberDef *md,int id) override;
125  void startFile(const QCString &name,bool isSource,const QCString &manName,const QCString &title,int id,int hierarchyLevel) override;
126  void endFile() override;
127 
128  void writeSearchInfo() override {DB_GEN_EMPTY}
129  void writeFooter(const QCString &) override {DB_GEN_NEW}
130  void startIndexSection(IndexSection) override;
131  void endIndexSection(IndexSection) override;
132  void writePageLink(const QCString &,bool) override;
133  void startProjectNumber() override {DB_GEN_NEW}
134  void endProjectNumber() override {DB_GEN_NEW}
135  void writeStyleInfo(int) override {DB_GEN_EMPTY}
136  void startTitleHead(const QCString &) override;
137  void endTitleHead(const QCString &fileName,const QCString &name) override;
138  void startIndexListItem() override {DB_GEN_NEW}
139  void endIndexListItem() override {DB_GEN_NEW}
140  void startIndexList() override {DB_GEN_NEW}
141  void endIndexList() override {DB_GEN_NEW}
142  void startIndexKey() override {DB_GEN_NEW}
143  void endIndexKey() override {DB_GEN_NEW}
144  void startIndexValue(bool) override {DB_GEN_NEW}
145  void endIndexValue(const QCString &,bool) override {DB_GEN_NEW}
146  void startItemList() override {DB_GEN_EMPTY}
147  void endItemList() override {DB_GEN_EMPTY}
148 
149  void startIndexItem(const QCString &,const QCString &) override {DB_GEN_NEW}
150  void endIndexItem(const QCString &,const QCString &) override {DB_GEN_NEW}
151  void startItemListItem() override {DB_GEN_EMPTY}
152  void endItemListItem() override {DB_GEN_EMPTY}
153  void docify(const QCString &text) override;
154  void writeChar(char) override;
155  void writeString(const QCString &) override;
156  void startParagraph(const QCString &) override;
157  void endParagraph() override;
158  void writeObjectLink(const QCString &,const QCString &,const QCString &,const QCString &) override;
159  void startBold() override;
160  void endBold() override;
161  void startTypewriter() override;
162  void endTypewriter() override;
163  void startEmphasis() override {DB_GEN_NEW}
164  void endEmphasis() override {DB_GEN_NEW}
165  void writeRuler() override;
166  void startDescForItem() override {DB_GEN_EMPTY}
167  void endDescForItem() override {DB_GEN_EMPTY}
168  void startCenter() override {DB_GEN_NEW}
169  void endCenter() override {DB_GEN_NEW}
170  void startSmall() override {DB_GEN_NEW}
171  void endSmall() override {DB_GEN_NEW}
172  void startExamples() override;
173  void endExamples() override;
174  void writeAnchor(const QCString &,const QCString &) override {DB_GEN_EMPTY}
175  void startSection(const QCString &,const QCString &,SectionType) override;
176  void endSection(const QCString &,SectionType) override;
177  void lineBreak(const QCString &) override;
178  void addIndexItem(const QCString &,const QCString &) override;
179  void writeNonBreakableSpace(int) override;
180 
181  void startDescTable(const QCString &title,const bool hasInits) override;
182  void endDescTable() override;
183  void startDescTableRow() override;
184  void endDescTableRow() override;
185  void startDescTableTitle() override;
186  void endDescTableTitle() override;
187  void startDescTableInit() override;
188  void endDescTableInit() override;
189  void startDescTableData() override;
190  void endDescTableData() override;
191  void startTextLink(const QCString &,const QCString &) override {DB_GEN_NEW}
192  void endTextLink() override {DB_GEN_NEW}
193  void startPageRef() override {DB_GEN_NEW}
194  void endPageRef(const QCString &,const QCString &) override {DB_GEN_NEW}
195 
196  void startGroupHeader(const QCString &,int) override;
197  void endGroupHeader(int) override;
198  void startMemberSections() override {DB_GEN_EMPTY}
199  void endMemberSections() override {DB_GEN_EMPTY}
200  void startHeaderSection() override {DB_GEN_EMPTY}
201  void endHeaderSection() override {DB_GEN_EMPTY}
202  void startMemberHeader(const QCString &anchor, int typ) override;
203  void endMemberHeader() override;
204  void startMemberSubtitle() override {DB_GEN_EMPTY}
205  void endMemberSubtitle() override {DB_GEN_EMPTY}
206  void startMemberDocList() override;
207  void endMemberDocList() override;
208  void startMemberList() override;
209  void endMemberList() override;
210  void startInlineHeader() override {DB_GEN_NEW}
211  void endInlineHeader() override {DB_GEN_NEW}
212  void startAnonTypeScope(int) override {DB_GEN_EMPTY}
213  void endAnonTypeScope(int) override {DB_GEN_EMPTY}
214  void startMemberItem(const QCString &,MemberItemType,const QCString &) override;
215  void endMemberItem(MemberItemType) override;
216  void startMemberTemplateParams() override;
217  void endMemberTemplateParams(const QCString &,const QCString &) override;
218  void startCompoundTemplateParams() override;
219  void endCompoundTemplateParams() override;
220  void startMemberGroupHeader(const QCString &,bool) override;
221  void endMemberGroupHeader() override;
222  void startMemberGroupDocs() override {DB_GEN_EMPTY}
223  void endMemberGroupDocs() override {DB_GEN_EMPTY}
224  void startMemberGroup() override;
225  void endMemberGroup(bool) override;
226  void insertMemberAlign(bool) override {DB_GEN_EMPTY}
227  void insertMemberAlignLeft(MemberItemType,bool) override {DB_GEN_EMPTY}
228  void startMemberDoc(const QCString &,const QCString &,
229  const QCString &,const QCString &,int,int,bool) override;
230  void endMemberDoc(bool) override;
231  void startDoxyAnchor(const QCString &fName,const QCString &manName,
232  const QCString &anchor,const QCString &name,
233  const QCString &args) override;
234  void endDoxyAnchor(const QCString &fileName,const QCString &anchor) override;
235  void addLabel(const QCString &,const QCString &) override;
236  void writeLatexSpacing() override {DB_GEN_EMPTY}
237  void writeStartAnnoItem(const QCString &,const QCString &,
238  const QCString &,const QCString &) override {DB_GEN_NEW}
239  void startMemberDescription(const QCString &,const QCString &,bool) override {DB_GEN_EMPTY}
240  void endMemberDescription() override {DB_GEN_EMPTY}
241  void startMemberDeclaration() override {DB_GEN_EMPTY}
242  void endMemberDeclaration(const QCString &,const QCString &) override {DB_GEN_EMPTY}
243  void writeInheritedSectionTitle(const QCString &,const QCString &,
244  const QCString &,const QCString &,
245  const QCString &,const QCString &) override;
246  void startIndent() override {DB_GEN_EMPTY}
247  void endIndent() override {DB_GEN_EMPTY}
248  void writeSynopsis() override {DB_GEN_EMPTY}
249  void startClassDiagram() override;
250  void endClassDiagram(const ClassDiagram &,const QCString &,const QCString &) override;
251  void startDotGraph() override;
252  void endDotGraph(DotClassGraph &g) override;
253  void startInclDepGraph() override;
254  void endInclDepGraph(DotInclDepGraph &g) override;
255  void startGroupCollaboration() override;
256  void endGroupCollaboration(DotGroupCollaboration &g) override;
257  void startCallGraph() override;
258  void endCallGraph(DotCallGraph &g) override;
259  void startDirDepGraph() override;
260  void endDirDepGraph(DotDirDeps &g) override;
261  void writeGraphicalHierarchy(DotGfxHierarchyTable &) override {DB_GEN_NEW}
262  void startQuickIndices() override {DB_GEN_EMPTY}
263  void endQuickIndices() override {DB_GEN_EMPTY}
264  void writeSplitBar(const QCString &,const QCString &) override {DB_GEN_EMPTY}
265  void writeNavigationPath(const QCString &) override {DB_GEN_NEW}
266  void writeLogo() override {DB_GEN_NEW}
267  void writeQuickLinks(HighlightedItem,const QCString &,bool) override {DB_GEN_EMPTY}
268  void writeSummaryLink(const QCString &,const QCString &,const QCString &,bool) override {DB_GEN_EMPTY}
269  void writePageOutline() override {DB_GEN_EMPTY}
270  void startContents() override {DB_GEN_EMPTY}
271  void endContents() override {DB_GEN_EMPTY}
272  void startPageDoc(const QCString &) override {DB_GEN_EMPTY}
273  void endPageDoc() override {DB_GEN_EMPTY}
274  void startTextBlock(bool) override;
275  void endTextBlock(bool) override;
276  void lastIndexPage() override {DB_GEN_EMPTY}
277  void startMemberDocPrefixItem() override;
278  void endMemberDocPrefixItem() override;
279  void startMemberDocName(bool) override;
280  void endMemberDocName() override;
281  void startParameterType(bool,const QCString &) override {DB_GEN_EMPTY}
282  void endParameterType() override {DB_GEN_EMPTY}
283  void startParameterName(bool) override;
284  void endParameterName() override;
285  void startParameterExtra() override;
286  void endParameterExtra(bool,bool,bool) override;
287  void startParameterDefVal(const char *sep) override;
288  void endParameterDefVal() override;
289  void startParameterList(bool) override;
290  void endParameterList() override;
291  void exceptionEntry(const QCString &,bool) override;
292 
293  void startConstraintList(const QCString &) override;
294  void startConstraintParam() override;
295  void endConstraintParam() override;
296  void startConstraintType() override;
297  void endConstraintType() override;
298  void startConstraintDocs() override;
299  void endConstraintDocs() override;
300  void endConstraintList() override;
301 
302  void startMemberDocSimple(bool) override;
303  void endMemberDocSimple(bool) override;
304  void startInlineMemberType() override;
305  void endInlineMemberType() override;
306  void startInlineMemberName() override;
307  void endInlineMemberName() override;
308  void startInlineMemberDoc() override;
309  void endInlineMemberDoc() override;
310 
311  void startLabels() override;
312  void writeLabel(const QCString &,bool) override;
313  void endLabels() override;
314 
315  void startLocalToc(int level) override;
316  void endLocalToc() override;
317  void startTocEntry(const SectionInfo *si) override;
318  void endTocEntry(const SectionInfo *si) override;
319 
320  void startPlainFile(const QCString &name) override { OutputGenerator::startPlainFile(name); }
321  void endPlainFile() override { OutputGenerator::endPlainFile(); }
322 
323 private:
324  void openSection(const QCString &attr=QCString());
325  void closeSection();
326  void closeAllSections();
327 
328  QCString relPath;
329  std::unique_ptr<OutputCodeList> m_codeList;
330  DocbookCodeGenerator *m_codeGen = nullptr;
331  bool m_denseText = false;
332  bool m_inGroup = false;
333  int m_levelListItem = 0;
334  std::array<bool,20> m_inListItem = { false, };
335  std::array<bool,20> m_inSimpleSect = { false, };
336  bool m_descTable = false;
337  bool m_simpleTable = false;
338  int m_inLevel = -1;
339  bool m_firstMember = false;
340  int m_openSectionCount = 0;
341  QCString m_pageLinks;
342 
343  struct TocState
344  {
345  int level = 0;
346  int maxLevel = 0;
347  BoolVector inLi;
348  };
349  TocState m_tocState;
350 };
351 
352 QCString convertToDocBook(const QCString &s, const bool retainNewline = false);
353 
354 
355 #endif
OutputCodeIntf
Base class for code generators.
Definition: outputgen.h:64
Definition
The common base class of all entity definitions found in the sources.
Definition: definition.h:75
MemberDef
A model of a class/file/namespace member symbol.
Definition: memberdef.h:47
TextStream
Text streaming class that buffers data.
Definition: textstream.h:35
DotGfxHierarchyTable
Represents a graphical class hierarchy.
Definition: dotgfxhierarchytable.h:31
DotGroupCollaboration
Representation of a group collaboration graph.
Definition: dotgroupcollaboration.h:28
DocbookGenerator
Definition: docbookgen.h:103
IDocNodeAST
opaque representation of the abstract syntax tree (AST)
Definition: docparser.h:49
SectionInfo
class that provide information about a section.
Definition: section.h:56
OutputCodeList
Class representing a list of different code generators.
Definition: outputlist.h:163
ClassDiagram
Class representing a built-in class diagram.
Definition: diagram.h:30
SectionType
Definition: section.h:28
DotCallGraph
Representation of an call graph.
Definition: dotcallgraph.h:26
DotClassGraph
Representation of a class inheritance or dependency graph.
Definition: dotclassgraph.h:28
DocbookCodeGenerator
Definition: docbookgen.h:47
OutputGenerator
Base class for shared implementation for all output generators.
Definition: outputgen.h:98
DotInclDepGraph
Representation of an include dependency graph.
Definition: dotincldepgraph.h:30
DotDirDeps
Representation of an directory dependency graph.
Definition: dotdirdeps.h:25
QCString
This is an alternative implementation of QCString.
Definition: qcstring.h:100
OutputGenIntf
Abstract interface for output generators.
Definition: outputgen.h:126
SourceLinkInfo
Definition: outputgen.h:50
DocLinkInfo
Definition: outputgen.h:42
Generated by   doxygen 1.8.13