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
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(int);
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  size_t 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 
114  // structural output interface
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 addLabel(const QCString &,const QCString &);
224  void writeLatexSpacing(){DB_GEN_EMPTY}
225  void writeStartAnnoItem(const QCString &,const QCString &,
226  const QCString &,const QCString &){DB_GEN_NEW};
227  void startMemberDescription(const QCString &,const QCString &,bool){DB_GEN_EMPTY};
228  void endMemberDescription(){DB_GEN_EMPTY};
229  void startMemberDeclaration(){DB_GEN_EMPTY};
230  void endMemberDeclaration(const QCString &,const QCString &){DB_GEN_EMPTY};
231  void writeInheritedSectionTitle(const QCString &,const QCString &,
232  const QCString &,const QCString &,
233  const QCString &,const QCString &);
234  void startIndent(){DB_GEN_EMPTY};
235  void endIndent(){DB_GEN_EMPTY};
236  void writeSynopsis(){DB_GEN_EMPTY};
237  void startClassDiagram();
238  void endClassDiagram(const ClassDiagram &,const QCString &,const QCString &);
239  void startDotGraph();
240  void endDotGraph(DotClassGraph &g);
241  void startInclDepGraph();
242  void endInclDepGraph(DotInclDepGraph &g);
243  void startGroupCollaboration();
244  void endGroupCollaboration(DotGroupCollaboration &g);
245  void startCallGraph();
246  void endCallGraph(DotCallGraph &g);
247  void startDirDepGraph();
248  void endDirDepGraph(DotDirDeps &g);
249  void writeGraphicalHierarchy(DotGfxHierarchyTable &){DB_GEN_NEW};
250  void startQuickIndices(){DB_GEN_EMPTY};
251  void endQuickIndices(){DB_GEN_EMPTY};
252  void writeSplitBar(const QCString &){DB_GEN_EMPTY};
253  void writeNavigationPath(const QCString &){DB_GEN_NEW};
254  void writeLogo(){DB_GEN_NEW};
255  void writeQuickLinks(HighlightedItem,const QCString &){DB_GEN_EMPTY};
256  void writeSummaryLink(const QCString &,const QCString &,const QCString &,bool){DB_GEN_EMPTY};
257  void startContents(){DB_GEN_EMPTY};
258  void endContents(){DB_GEN_EMPTY};
259  void startPageDoc(const QCString &){DB_GEN_EMPTY}
260  void endPageDoc() {DB_GEN_EMPTY}
261  void startTextBlock(bool);
262  void endTextBlock(bool);
263  void lastIndexPage(){DB_GEN_EMPTY};
264  void startMemberDocPrefixItem();
265  void endMemberDocPrefixItem();
266  void startMemberDocName(bool);
267  void endMemberDocName();
268  void startParameterType(bool,const QCString &){DB_GEN_EMPTY};
269  void endParameterType(){DB_GEN_EMPTY};
270  void startParameterName(bool);
271  void endParameterName();
272  void startParameterExtra();
273  void endParameterExtra(bool,bool,bool);
274  void startParameterDefVal(const char *sep);
275  void endParameterDefVal();
276  void startParameterList(bool);
277  void endParameterList();
278  void exceptionEntry(const QCString &,bool);
279 
280  void startConstraintList(const QCString &);
281  void startConstraintParam();
282  void endConstraintParam();
283  void startConstraintType();
284  void endConstraintType();
285  void startConstraintDocs();
286  void endConstraintDocs();
287  void endConstraintList();
288 
289  void startMemberDocSimple(bool);
290  void endMemberDocSimple(bool);
291  void startInlineMemberType();
292  void endInlineMemberType();
293  void startInlineMemberName();
294  void endInlineMemberName();
295  void startInlineMemberDoc();
296  void endInlineMemberDoc();
297 
298  void startLabels();
299  void writeLabel(const QCString &,bool);
300  void endLabels();
301 
302  void writeLocalToc(const SectionRefs &sr,const LocalToc &lt);
303 
304  void setCurrentDoc(const Definition *,const QCString &,bool) {DB_GEN_EMPTY}
305  void addWord(const QCString &,bool) {DB_GEN_EMPTY}
306 
307  void addCodeGen(OutputCodeList &list);
308 private:
309  void openSection(const QCString &attr=QCString());
310  void closeSection();
311  void closeAllSections();
312 
313  QCString relPath;
314  std::unique_ptr<OutputCodeList> m_codeList;
315  DocbookCodeGenerator *m_codeGen = nullptr;
316  bool m_denseText = false;
317  bool m_inGroup = false;
318  int m_levelListItem = 0;
319  std::array<bool,20> m_inListItem = { false, };
320  std::array<bool,20> m_inSimpleSect = { false, };
321  bool m_descTable = false;
322  bool m_simpleTable = false;
323  int m_inLevel = -1;
324  bool m_firstMember = false;
325  int m_openSectionCount = 0;
326  QCString m_pageLinks;
327 };
328 
329 QCString convertToDocBook(const QCString &s, const bool retainNewline = false);
330 
331 
332 #endif
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
SectionRefs
class that represents a list of constant references to sections.
Definition: section.h:101
DotGfxHierarchyTable
Represents a graphical class hierarchy.
Definition: dotgfxhierarchytable.h:31
LocalToc
Definition: types.h:308
DotGroupCollaboration
Representation of a group collaboration graph.
Definition: dotgroupcollaboration.h:28
DocbookGenerator
Definition: docbookgen.h:96
IDocNodeAST
opaque representation of the abstract syntax tree (AST)
Definition: docparser.h:47
OutputCodeList
Class representing a list of different code generators.
Definition: outputlist.h:199
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 specific output generators.
Definition: outputgen.h:65
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:93
SourceLinkInfo
Definition: outputgen.h:50
DocLinkInfo
Definition: outputgen.h:42
Generated by   doxygen 1.8.13