outputgen.h
Go to the documentation of this file.
1 /******************************************************************************
2  *
3  *
4  *
5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
6  *
7  * Permission to use, copy, modify, and distribute this software and its
8  * documentation under the terms of the GNU General Public License is hereby
9  * granted. No representations are made about the suitability of this software
10  * for any purpose. It is provided "as is" without express or implied warranty.
11  * See the GNU General Public License for more details.
12  *
13  * Documents produced by Doxygen are derivative works derived from the
14  * input used in their production; they are not affected by this license.
15  *
16  */
17 
18 #ifndef OUTPUTGEN_H
19 #define OUTPUTGEN_H
20 
21 #include <qstack.h>
22 
23 #include "index.h"
24 #include "section.h"
25 #include "ftextstream.h"
26 
27 class ClassDiagram;
28 class DotClassGraph;
29 class DotInclDepGraph;
30 class DotCallGraph;
31 class DotDirDeps;
34 class DocNode;
35 class MemberDef;
36 class GroupDef;
37 class Definition;
38 class QFile;
39 
41 {
46 };
47 
49 {
51  int line;
55 };
56 
57 /** Output interface for code parser.
58  */
60 {
61  public:
62  virtual ~CodeOutputInterface() {}
63 
64  /*! Writes an code fragment to the output. This function should keep
65  * spaces visible, should break lines at a newline and should convert
66  * tabs to the right number of spaces.
67  */
68  virtual void codify(const char *s) = 0;
69 
70  /*! Writes a link to an object in a code fragment.
71  * \param ref If this is non-zero, the object is to be found in
72  * an external documentation file.
73  * \param file The file in which the object is located.
74  * \param anchor The anchor uniquely identifying the object within
75  * the file.
76  * \param name The text to display as a placeholder for the link.
77  * \param tooltip The tooltip to display when the mouse is on the link.
78  */
79  virtual void writeCodeLink(const char *ref,const char *file,
80  const char *anchor,const char *name,
81  const char *tooltip) = 0;
82 
83  /*! Writes the line number of a source listing
84  * \param ref External reference (when imported from a tag file)
85  * \param file The file part of the URL pointing to the docs.
86  * \param anchor The anchor part of the URL pointing to the docs.
87  * \param lineNumber The line number to write
88  */
89  virtual void writeLineNumber(const char *ref,const char *file,
90  const char *anchor,int lineNumber) = 0;
91 
92  /*! Writes a tool tip definition
93  * \param id unique identifier for the tooltip
94  * \param docInfo Info about the symbol's documentation.
95  * \param decl full declaration of the symbol (for functions)
96  * \param desc brief description for the symbol
97  * \param defInfo Info about the symbol's definition in the source code
98  * \param declInfo Info about the symbol's declaration in the source code
99  */
100  virtual void writeTooltip(const char *id,
101  const DocLinkInfo &docInfo,
102  const char *decl,
103  const char *desc,
104  const SourceLinkInfo &defInfo,
105  const SourceLinkInfo &declInfo
106  ) = 0;
107 
108  virtual void startCodeLine(bool hasLineNumbers) = 0;
109 
110  /*! Ends a line of code started with startCodeLine() */
111  virtual void endCodeLine() = 0;
112 
113  /*! Starts a block with a certain meaning. Used for syntax highlighting,
114  * which elements of the same type are rendered using the same 'font class'.
115  * \param clsName The category name.
116  */
117  virtual void startFontClass(const char *clsName) = 0;
118 
119  /*! Ends a block started with startFontClass() */
120  virtual void endFontClass() = 0;
121 
122  /*! Write an anchor to a source listing.
123  * \param name The name of the anchor.
124  */
125  virtual void writeCodeAnchor(const char *name) = 0;
126 
127  virtual void setCurrentDoc(Definition *context,const char *anchor,bool isSourceFile) = 0;
128  virtual void addWord(const char *word,bool hiPriority) = 0;
129 };
130 
131 /** Base Interface used for generating output outside of the
132  * comment blocks.
133  *
134  * This abstract class is used by output generation functions
135  * to generate the output for a specific format,
136  * or a list of formats (see OutputList). This interface
137  * contains functions that generate fragments of the output.
138  */
140 {
141  public:
143  enum ParamListTypes { Param, RetVal, Exception };
144  enum SectionTypes { /*See, Return, Author, Version,
145  Since, Date, Bug, Note,
146  Warning, Par, Deprecated, Pre,
147  Post, Invar, Remark, Attention,
148  Todo, Test, RCS, */ EnumValues,
149  Examples
150  };
151 
152  virtual bool parseText(const QCString &s) { return s.isEmpty(); }
153 
154  /*! Start of a bullet list: e.g. \c <ul> in html. startItemListItem() is
155  * Used for the bullet items.
156  */
157  virtual void startItemList() = 0;
158 
159  /*! Writes a list item for a bullet or enumerated
160  * list: e.g. \c <li> in html
161  */
162  virtual void startItemListItem() = 0;
163 
164  /*! Writes a list item for a bullet or enumerated
165  * list: e.g. \c </li> in html
166  */
167  virtual void endItemListItem() = 0;
168 
169  /*! Ends a bullet list: e.g. \c </ul> in html */
170  virtual void endItemList() = 0;
171 
172  /*! Writes an ASCII string to the output. Converts characters that have
173  * A special meaning, like \c & in html.
174  */
175  virtual void docify(const char *s) = 0;
176 
177  /*! Writes a single ASCII character to the output. Converts characters
178  * that have a special meaning.
179  */
180  virtual void writeChar(char c) = 0;
181 
182  /*! Writes an ASCII string to the output, \e without converting
183  * special characters.
184  */
185  virtual void writeString(const char *text) = 0;
186 
187  /*! Starts a new paragraph */
188  //virtual void newParagraph() = 0;
189 
190  /*! Starts a new paragraph */
191  virtual void startParagraph() = 0;
192  /*! Ends a paragraph */
193  virtual void endParagraph() = 0;
194 
195  /*! Writes a link to an object in the documentation.
196  * \param ref If this is non-zero, the object is to be found in
197  * an external documentation file.
198  * \param file The file in which the object is located.
199  * \param anchor The anchor uniquely identifying the object within
200  * the file.
201  * \param name The text to display as a placeholder for the link.
202  */
203  virtual void writeObjectLink(const char *ref,const char *file,
204  const char *anchor, const char *name) = 0;
205 
206 
207  /*! Starts a (link to an) URL found in the documentation.
208  * \param url The URL to link to.
209  */
210  virtual void startHtmlLink(const char *url) = 0;
211 
212  /*! Ends a link started by startHtmlLink().
213  */
214  virtual void endHtmlLink() = 0;
215 
216 
217  /*! Changes the text font to bold face. The bold section ends with
218  * endBold()
219  */
220  virtual void startBold() = 0;
221 
222  /*! End a section of text displayed in bold face. */
223  virtual void endBold() = 0;
224 
225  /*! Changes the text font to fixed size. The section ends with
226  * endTypewriter()
227  */
228  virtual void startTypewriter() = 0;
229 
230  /*! End a section of text displayed in typewriter style. */
231  virtual void endTypewriter() = 0;
232 
233  /*! Changes the text font to italic. The italic section ends with
234  * endEmphasis()
235  */
236  virtual void startEmphasis() = 0;
237 
238  /*! Ends a section of text displayed in italic. */
239  virtual void endEmphasis() = 0;
240 
241  /*! Starts a source code fragment. The fragment will be
242  * fed to the code parser (see code.h) for syntax highlighting
243  * and cross-referencing. The fragment ends by a call to
244  * endCodeFragment()
245  */
246  virtual void startCodeFragment() = 0;
247 
248  /*! Ends a source code fragment
249  */
250  virtual void endCodeFragment() = 0;
251 
252 
253 
254 
255  /*! Writes a horizontal ruler to the output */
256  virtual void writeRuler() = 0;
257 
258  /*! Starts a description list: e.g. \c <dl> in HTML
259  * Items are surrounded by startDescItem() and endDescItem()
260  */
261  virtual void startDescription() = 0;
262 
263  /*! Ends a description list: e.g. \c </dl> in HTML */
264  virtual void endDescription() = 0;
265 
266  /*! Starts an item of a description list: e.g. \c <dt> in HTML. */
267  virtual void startDescItem() = 0;
268 
269  virtual void startDescForItem() = 0;
270  virtual void endDescForItem() = 0;
271 
272  /*! Ends an item of a description list and starts the
273  * description itself: e.g. \c </dt> in HTML.
274  */
275  virtual void endDescItem() = 0;
276 
277  virtual void startCenter() = 0;
278  virtual void endCenter() = 0;
279  virtual void startSmall() = 0;
280  virtual void endSmall() = 0;
281 
282  virtual void startSimpleSect(SectionTypes t,const char *file,
283  const char *anchor,const char *title) = 0;
284  virtual void endSimpleSect() = 0;
285  virtual void startParamList(ParamListTypes t,const char *title) = 0;
286  virtual void endParamList() = 0;
287 
288  //virtual void writeDescItem() = 0;
289  virtual void startTitle() = 0;
290  virtual void endTitle() = 0;
291 
292  virtual void writeAnchor(const char *fileName,const char *name) = 0;
293  virtual void startSection(const char *,const char *,SectionInfo::SectionType) = 0;
294  virtual void endSection(const char *,SectionInfo::SectionType) = 0;
295 
296  virtual void lineBreak(const char *style) = 0;
297  virtual void addIndexItem(const char *s1,const char *s2) = 0;
298 
299  virtual void writeNonBreakableSpace(int) = 0;
300  virtual void startDescTable(const char *title) = 0;
301  virtual void endDescTable() = 0;
302  virtual void startDescTableTitle() = 0;
303  virtual void endDescTableTitle() = 0;
304  virtual void startDescTableData() = 0;
305  virtual void endDescTableData() = 0;
306  virtual void startTextLink(const char *file,const char *anchor) = 0;
307  virtual void endTextLink() = 0;
308  virtual void startPageRef() = 0;
309  virtual void endPageRef(const char *,const char *) = 0;
310  virtual void startSubsection() = 0;
311  virtual void endSubsection() = 0;
312  virtual void startSubsubsection() = 0;
313  virtual void endSubsubsection() = 0;
314 };
315 
316 /** Abstract output generator.
317  *
318  * Subclass this class to add support for a new output format
319  */
321 {
322  public:
323  enum OutputType { Html, Latex, Man, RTF, XML, DEF, Perl };
324 
325  OutputGenerator();
326  virtual ~OutputGenerator();
327 
328  ///////////////////////////////////////////////////////////////
329  // generic generator methods
330  ///////////////////////////////////////////////////////////////
331  virtual void enable() = 0;
332  virtual void disable() = 0;
333  virtual void enableIf(OutputType o) = 0;
334  virtual void disableIf(OutputType o) = 0;
335  virtual void disableIfNot(OutputType o) = 0;
336  virtual bool isEnabled(OutputType o) = 0;
337  virtual OutputGenerator *get(OutputType o) = 0;
338  void startPlainFile(const char *name);
339  void endPlainFile();
340  //QCString getContents() const;
341  bool isEnabled() const { return active; }
342  void pushGeneratorState();
343  void popGeneratorState();
344  //void setEncoding(const QCString &enc) { encoding = enc; }
345  //virtual void postProcess(QByteArray &) { }
346 
347  virtual void writeDoc(DocNode *,Definition *ctx,MemberDef *md) = 0;
348 
349  ///////////////////////////////////////////////////////////////
350  // structural output interface
351  ///////////////////////////////////////////////////////////////
352  virtual void startFile(const char *name,const char *manName,
353  const char *title) = 0;
354  virtual void writeSearchInfo() = 0;
355  virtual void writeFooter(const char *navPath) = 0;
356  virtual void endFile() = 0;
357  virtual void startIndexSection(IndexSections) = 0;
358  virtual void endIndexSection(IndexSections) = 0;
359  virtual void writePageLink(const char *,bool) = 0;
360  virtual void startProjectNumber() = 0;
361  virtual void endProjectNumber() = 0;
362  virtual void writeStyleInfo(int part) = 0;
363  virtual void startTitleHead(const char *) = 0;
364  virtual void endTitleHead(const char *fileName,const char *name) = 0;
365  virtual void startIndexListItem() = 0;
366  virtual void endIndexListItem() = 0;
367  virtual void startIndexList() = 0;
368  virtual void endIndexList() = 0;
369  virtual void startIndexKey() = 0;
370  virtual void endIndexKey() = 0;
371  virtual void startIndexValue(bool) = 0;
372  virtual void endIndexValue(const char *,bool) = 0;
373  virtual void startIndexItem(const char *ref,const char *file) = 0;
374  virtual void endIndexItem(const char *ref,const char *file) = 0;
375  virtual void startGroupHeader(int) = 0;
376  virtual void endGroupHeader(int) = 0;
377  virtual void startMemberSections() = 0;
378  virtual void endMemberSections() = 0;
379  virtual void startHeaderSection() = 0;
380  virtual void endHeaderSection() = 0;
381  virtual void startMemberHeader(const char *anchor) = 0;
382  virtual void endMemberHeader() = 0;
383  virtual void startMemberSubtitle() = 0;
384  virtual void endMemberSubtitle() = 0;
385  virtual void startMemberDocList() = 0;
386  virtual void endMemberDocList() = 0;
387  virtual void startMemberList() = 0;
388  virtual void endMemberList() = 0;
389  virtual void startInlineHeader() = 0;
390  virtual void endInlineHeader() = 0;
391  virtual void startAnonTypeScope(int) = 0;
392  virtual void endAnonTypeScope(int) = 0;
393  virtual void startMemberItem(const char *,int,const char *) = 0;
394  virtual void endMemberItem() = 0;
395  virtual void startMemberTemplateParams() = 0;
396  virtual void endMemberTemplateParams(const char *,const char *) = 0;
397  virtual void startMemberGroupHeader(bool) = 0;
398  virtual void endMemberGroupHeader() = 0;
399  virtual void startMemberGroupDocs() = 0;
400  virtual void endMemberGroupDocs() = 0;
401  virtual void startMemberGroup() = 0;
402  virtual void endMemberGroup(bool) = 0;
403  virtual void insertMemberAlign(bool) = 0;
404  virtual void startMemberDoc(const char *,const char *,
405  const char *,const char *,bool) = 0;
406  virtual void endMemberDoc(bool) = 0;
407  virtual void startDoxyAnchor(const char *fName,const char *manName,
408  const char *anchor,const char *name,
409  const char *args) = 0;
410  virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;
411  virtual void writeLatexSpacing() = 0;
412  virtual void writeStartAnnoItem(const char *type,const char *file,
413  const char *path,const char *name) = 0;
414  virtual void writeEndAnnoItem(const char *name) = 0;
415  virtual void startMemberDescription(const char *anchor,const char *inheritId) = 0;
416  virtual void endMemberDescription() = 0;
417  virtual void startMemberDeclaration() = 0;
418  virtual void endMemberDeclaration(const char *anchor,const char *inheritId) = 0;
419  virtual void writeInheritedSectionTitle(const char *id,const char *ref,
420  const char *file,const char *anchor,
421  const char *title,const char *name) = 0;
422  virtual void startIndent() = 0;
423  virtual void endIndent() = 0;
424  virtual void writeSynopsis() = 0;
425  virtual void startClassDiagram() = 0;
426  virtual void endClassDiagram(const ClassDiagram &,const char *,const char *) = 0;
427  virtual void startDotGraph() = 0;
428  virtual void endDotGraph(const DotClassGraph &g) = 0;
429  virtual void startInclDepGraph() = 0;
430  virtual void endInclDepGraph(const DotInclDepGraph &g) = 0;
431  virtual void startGroupCollaboration() = 0;
432  virtual void endGroupCollaboration(const DotGroupCollaboration &g) = 0;
433  virtual void startCallGraph() = 0;
434  virtual void endCallGraph(const DotCallGraph &g) = 0;
435  virtual void startDirDepGraph() = 0;
436  virtual void endDirDepGraph(const DotDirDeps &g) = 0;
437  virtual void writeGraphicalHierarchy(const DotGfxHierarchyTable &g) = 0;
438  virtual void startQuickIndices() = 0;
439  virtual void endQuickIndices() = 0;
440  virtual void writeSplitBar(const char *) = 0;
441  virtual void writeNavigationPath(const char *) = 0;
442  virtual void writeLogo() = 0;
443  virtual void writeQuickLinks(bool compact,HighlightedItem hli,const char *file) = 0;
444  virtual void writeSummaryLink(const char *file,const char *anchor,const char *title,bool first) = 0;
445  virtual void startContents() = 0;
446  virtual void endContents() = 0;
447  virtual void startTextBlock(bool) = 0;
448  virtual void endTextBlock(bool) = 0;
449  virtual void lastIndexPage() = 0;
450  virtual void startMemberDocPrefixItem() = 0;
451  virtual void endMemberDocPrefixItem() = 0;
452  virtual void startMemberDocName(bool) = 0;
453  virtual void endMemberDocName() = 0;
454  virtual void startParameterType(bool,const char *key) = 0;
455  virtual void endParameterType() = 0;
456  virtual void startParameterName(bool) = 0;
457  virtual void endParameterName(bool,bool,bool) = 0;
458  virtual void startParameterList(bool) = 0;
459  virtual void endParameterList() = 0;
460  virtual void exceptionEntry(const char*,bool) = 0;
461 
462  virtual void startConstraintList(const char *) = 0;
463  virtual void startConstraintParam() = 0;
464  virtual void endConstraintParam() = 0;
465  virtual void startConstraintType() = 0;
466  virtual void endConstraintType() = 0;
467  virtual void startConstraintDocs() = 0;
468  virtual void endConstraintDocs() = 0;
469  virtual void endConstraintList() = 0;
470 
471  virtual void startMemberDocSimple() = 0;
472  virtual void endMemberDocSimple() = 0;
473  virtual void startInlineMemberType() = 0;
474  virtual void endInlineMemberType() = 0;
475  virtual void startInlineMemberName() = 0;
476  virtual void endInlineMemberName() = 0;
477  virtual void startInlineMemberDoc() = 0;
478  virtual void endInlineMemberDoc() = 0;
479 
480 
481  virtual void startLabels() = 0;
482  virtual void writeLabel(const char *,bool) = 0;
483  virtual void endLabels() = 0;
484 
485  protected:
490  bool active;
492 
493  private:
495  OutputGenerator &operator=(const OutputGenerator &o);
496 };
497 
498 /** Interface used for generating documentation.
499  *
500  * This abstract class is used by several functions
501  * to generate the output for a specific format.
502  * This interface contains some state saving and changing
503  * functions for dealing with format specific output.
504  */
506 {
507  public:
508  virtual ~OutputDocInterface() {}
509 
510  /*! Create a new output generator. This can later by appended
511  * to the current one using append().
512  */
513  //virtual OutputDocInterface *clone() = 0;
514 
515  /*! Disables all output formats except format \a o
516  * (useful for OutputList only)
517  */
518  virtual void disableAllBut(OutputGenerator::OutputType o) = 0;
519 
520  /*! Enables all output formats as far as they have been enabled in
521  * the config file. (useful for OutputList only)
522  */
523  virtual void enableAll() = 0;
524 
525  /*! Disables all output formats (useful for OutputList only) */
526  virtual void disableAll()= 0;
527 
528  /*! Disables a specific output format (useful for OutputList only) */
529  virtual void disable(OutputGenerator::OutputType o) = 0;
530 
531  /*! Enables a specific output format (useful for OutputList only) */
532  virtual void enable(OutputGenerator::OutputType o) = 0;
533 
534  /*! Check whether a specific output format is currently enabled
535  * (useful for OutputList only)
536  */
537  virtual bool isEnabled(OutputGenerator::OutputType o) = 0;
538 
539  /*! Appends the output generated by generator \a g to this
540  * generator.
541  */
542  //virtual void append(const OutputDocInterface *g) = 0;
543 
544  /*! Pushes the state of the current generator (or list of
545  * generators) on a stack.
546  */
547  virtual void pushGeneratorState() = 0;
548 
549  /*! Pops the state of the current generator (or list of
550  * generators) on a stack. Should be preceded by a call
551  * the pushGeneratorState().
552  */
553  virtual void popGeneratorState() = 0;
554 };
555 
556 
557 #endif
QCString ref
Definition: outputgen.h:43
void endFile(OutputList &ol, bool skipNavIndex, bool skipEndContents, const QCString &navPath)
Definition: index.cpp:263
QCString file
Definition: outputgen.h:50
static constexpr double g
Definition: Units.h:144
bool isEmpty() const
Definition: qcstring.h:189
void startFile(OutputList &ol, const char *name, const char *manName, const char *title, HighlightedItem hli, bool additionalIndices, const char *altSidebarName)
Definition: index.cpp:244
QCString url
Definition: outputgen.h:53
void writeLogo(const char *dir)
static void endFontClass()
Definition: code.cpp:11962
QCString ref
Definition: outputgen.h:52
static void startCodeLine()
Definition: code.cpp:11021
static void startFontClass(const char *s)
Definition: code.cpp:11971
QCString anchor
Definition: outputgen.h:54
IndexSections
Definition: index.h:157
Simplified and optimized version of QTextStream.
Definition: ftextstream.h:11
static QCString args
Definition: declinfo.cpp:674
static void writeString(QFile &f, const char *s)
fileName
Definition: dumpTree.py:9
def key(type, name=None)
Definition: graph.py:13
QStack< bool > * genStack
Definition: outputgen.h:491
virtual ~OutputDocInterface()
Definition: outputgen.h:508
virtual ~BaseOutputDocInterface()
Definition: outputgen.h:142
virtual ~CodeOutputInterface()
Definition: outputgen.h:62
QCString name
Definition: outputgen.h:42
QFile * file
Definition: outputgen.h:487
static void endCodeLine()
Definition: code.cpp:11081
static void codify(const char *text)
Definition: pycode.cpp:1580
The QFile class is an I/O device that operates on files.
Definition: qfile.h:50
QCString fileName
Definition: outputgen.h:488
QCString dir
Definition: outputgen.h:489
cet::coded_exception< errors::ErrorCodes, ExceptionDetail::translate > Exception
Definition: Exception.h:66
void startTitle(OutputList &ol, const char *fileName, Definition *def)
Definition: index.cpp:228
FTextStream t
Definition: outputgen.h:486
QCString anchor
Definition: outputgen.h:45
bool isEnabled() const
Definition: outputgen.h:341
static void setCurrentDoc(const QCString &anchor)
Definition: code.cpp:10966
virtual bool parseText(const QCString &s)
Definition: outputgen.h:152
QCString url
Definition: outputgen.h:44
void endTitle(OutputList &ol, const char *fileName, const char *name)
Definition: index.cpp:237
HighlightedItem
Definition: index.h:180
static QCString * s
Definition: config.cpp:1042
union ptb::content::word::word word