src/outputgen.h

   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;
  32 class DotGfxHierarchyTable;
  33 class DotGroupCollaboration;
  34 class DocNode;
  35 class MemberDef;
  36 class GroupDef;
  37 class Definition;
  38 class QFile;
  39
  40 struct DocLinkInfo
  41 {
  42   QCString name;
  43   QCString ref;
  44   QCString url;
  45   QCString anchor;
  46 };
  47
  48 struct SourceLinkInfo
  49 {
  50   QCString file;
  51   int line;
  52   QCString ref;
  53   QCString url;
  54   QCString anchor;
  55 };
  56
  57 /** Output interface for code parser.
  58  */
  59 class CodeOutputInterface
  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  */
 139 class BaseOutputDocInterface : public CodeOutputInterface
 140 {
 141   public:
 142     virtual ~BaseOutputDocInterface() {}
 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(const char *classDef) = 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 startDescTableRow() = 0;
 303     virtual void endDescTableRow() = 0;
 304     virtual void startDescTableTitle() = 0;
 305     virtual void endDescTableTitle() = 0;
 306     virtual void startDescTableData() = 0;
 307     virtual void endDescTableData() = 0;
 308     virtual void startTextLink(const char *file,const char *anchor) = 0;
 309     virtual void endTextLink() = 0;
 310     virtual void startPageRef() = 0;
 311     virtual void endPageRef(const char *,const char *) = 0;
 312     virtual void startSubsection() = 0;
 313     virtual void endSubsection() = 0;
 314     virtual void startSubsubsection() = 0;
 315     virtual void endSubsubsection() = 0;
 316 };
 317
 318 /** Abstract output generator.
 319  *
 320  *  Subclass this class to add support for a new output format
 321  */
 322 class OutputGenerator : public BaseOutputDocInterface
 323 {
 324   public:
 325     enum OutputType { Html, Latex, Man, RTF, XML, DEF, Perl };
 326
 327     OutputGenerator();
 328     virtual ~OutputGenerator();
 329
 330     ///////////////////////////////////////////////////////////////
 331     // generic generator methods
 332     ///////////////////////////////////////////////////////////////
 333     virtual void enable() = 0;
 334     virtual void disable() = 0;
 335     virtual void enableIf(OutputType o) = 0;
 336     virtual void disableIf(OutputType o) = 0;
 337     virtual void disableIfNot(OutputType o) = 0;
 338     virtual bool isEnabled(OutputType o) = 0;
 339     virtual OutputGenerator *get(OutputType o) = 0;
 340     void startPlainFile(const char *name);
 341     void endPlainFile();
 342     //QCString getContents() const;
 343     bool isEnabled() const { return active; }
 344     void pushGeneratorState();
 345     void popGeneratorState();
 346     //void setEncoding(const QCString &enc) { encoding = enc; }
 347     //virtual void postProcess(QByteArray &) { }
 348
 349     virtual void writeDoc(DocNode *,Definition *ctx,MemberDef *md) = 0;
 350
 351     ///////////////////////////////////////////////////////////////
 352     // structural output interface
 353     ///////////////////////////////////////////////////////////////
 354     virtual void startFile(const char *name,const char *manName,
 355                            const char *title) = 0;
 356     virtual void writeSearchInfo() = 0;
 357     virtual void writeFooter(const char *navPath) = 0;
 358     virtual void endFile() = 0;
 359     virtual void startIndexSection(IndexSections) = 0;
 360     virtual void endIndexSection(IndexSections) = 0;
 361     virtual void writePageLink(const char *,bool) = 0;
 362     virtual void startProjectNumber() = 0;
 363     virtual void endProjectNumber() = 0;
 364     virtual void writeStyleInfo(int part) = 0;
 365     virtual void startTitleHead(const char *) = 0;
 366     virtual void endTitleHead(const char *fileName,const char *name) = 0;
 367     virtual void startIndexListItem() = 0;
 368     virtual void endIndexListItem()   = 0;
 369     virtual void startIndexList() = 0;
 370     virtual void endIndexList()   = 0;
 371     virtual void startIndexKey() = 0;
 372     virtual void endIndexKey()   = 0;
 373     virtual void startIndexValue(bool) = 0;
 374     virtual void endIndexValue(const char *,bool) = 0;
 375     virtual void startIndexItem(const char *ref,const char *file) = 0;
 376     virtual void endIndexItem(const char *ref,const char *file) = 0;
 377     virtual void startGroupHeader(int) = 0;
 378     virtual void endGroupHeader(int) = 0;
 379     virtual void startMemberSections() = 0;
 380     virtual void endMemberSections() = 0;
 381     virtual void startHeaderSection() = 0;
 382     virtual void endHeaderSection() = 0;
 383     virtual void startMemberHeader(const char *anchor) = 0;
 384     virtual void endMemberHeader() = 0;
 385     virtual void startMemberSubtitle() = 0;
 386     virtual void endMemberSubtitle() = 0;
 387     virtual void startMemberDocList() = 0;
 388     virtual void endMemberDocList() = 0;
 389     virtual void startMemberList() = 0;
 390     virtual void endMemberList() = 0;
 391     virtual void startInlineHeader() = 0;
 392     virtual void endInlineHeader() = 0;
 393     virtual void startAnonTypeScope(int) = 0;
 394     virtual void endAnonTypeScope(int) = 0;
 395     virtual void startMemberItem(const char *,int,const char *) = 0;
 396     virtual void endMemberItem() = 0;
 397     virtual void startMemberTemplateParams() = 0;
 398     virtual void endMemberTemplateParams(const char *,const char *) = 0;
 399     virtual void startMemberGroupHeader(bool) = 0;
 400     virtual void endMemberGroupHeader() = 0;
 401     virtual void startMemberGroupDocs() = 0;
 402     virtual void endMemberGroupDocs() = 0;
 403     virtual void startMemberGroup() = 0;
 404     virtual void endMemberGroup(bool) = 0;
 405     virtual void insertMemberAlign(bool) = 0;
 406     virtual void startMemberDoc(const char *,const char *,
 407                                 const char *,const char *,int,int,bool) = 0;
 408     virtual void endMemberDoc(bool) = 0;
 409     virtual void startDoxyAnchor(const char *fName,const char *manName,
 410                                  const char *anchor,const char *name,
 411                                  const char *args) = 0;
 412     virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;
 413     virtual void writeLatexSpacing() = 0;
 414     virtual void writeStartAnnoItem(const char *type,const char *file,
 415                                     const char *path,const char *name) = 0;
 416     virtual void writeEndAnnoItem(const char *name) = 0;
 417     virtual void startMemberDescription(const char *anchor,const char *inheritId) = 0;
 418     virtual void endMemberDescription() = 0;
 419     virtual void startMemberDeclaration() = 0;
 420     virtual void endMemberDeclaration(const char *anchor,const char *inheritId) = 0;
 421     virtual void writeInheritedSectionTitle(const char *id,const char *ref,
 422                                             const char *file,const char *anchor,
 423                                             const char *title,const char *name) = 0;
 424     virtual void startIndent() = 0;
 425     virtual void endIndent() = 0;
 426     virtual void writeSynopsis() = 0;
 427     virtual void startClassDiagram() = 0;
 428     virtual void endClassDiagram(const ClassDiagram &,const char *,const char *) = 0;
 429     virtual void startDotGraph() = 0;
 430     virtual void endDotGraph(const DotClassGraph &g) = 0;
 431     virtual void startInclDepGraph() = 0;
 432     virtual void endInclDepGraph(const DotInclDepGraph &g) = 0;
 433     virtual void startGroupCollaboration() = 0;
 434     virtual void endGroupCollaboration(const DotGroupCollaboration &g) = 0;
 435     virtual void startCallGraph() = 0;
 436     virtual void endCallGraph(const DotCallGraph &g) = 0;
 437     virtual void startDirDepGraph() = 0;
 438     virtual void endDirDepGraph(const DotDirDeps &g) = 0;
 439     virtual void writeGraphicalHierarchy(const DotGfxHierarchyTable &g) = 0;
 440     virtual void startQuickIndices() = 0;
 441     virtual void endQuickIndices() = 0;
 442     virtual void writeSplitBar(const char *) = 0;
 443     virtual void writeNavigationPath(const char *) = 0;
 444     virtual void writeLogo() = 0;
 445     virtual void writeQuickLinks(bool compact,HighlightedItem hli,const char *file) = 0;
 446     virtual void writeSummaryLink(const char *file,const char *anchor,const char *title,bool first) = 0;
 447     virtual void startContents() = 0;
 448     virtual void endContents() = 0;
 449     virtual void startTextBlock(bool) = 0;
 450     virtual void endTextBlock(bool) = 0;
 451     virtual void lastIndexPage() = 0;
 452     virtual void startMemberDocPrefixItem() = 0;
 453     virtual void endMemberDocPrefixItem() = 0;
 454     virtual void startMemberDocName(bool) = 0;
 455     virtual void endMemberDocName() = 0;
 456     virtual void startParameterType(bool,const char *key) = 0;
 457     virtual void endParameterType() = 0;
 458     virtual void startParameterName(bool) = 0;
 459     virtual void endParameterName(bool,bool,bool) = 0;
 460     virtual void startParameterList(bool) = 0;
 461     virtual void endParameterList() = 0;
 462     virtual void exceptionEntry(const char*,bool) = 0;
 463
 464     virtual void startConstraintList(const char *) = 0;
 465     virtual void startConstraintParam() = 0;
 466     virtual void endConstraintParam() = 0;
 467     virtual void startConstraintType() = 0;
 468     virtual void endConstraintType() = 0;
 469     virtual void startConstraintDocs() = 0;
 470     virtual void endConstraintDocs() = 0;
 471     virtual void endConstraintList() = 0;
 472
 473     virtual void startMemberDocSimple(bool) = 0;
 474     virtual void endMemberDocSimple(bool) = 0;
 475     virtual void startInlineMemberType() = 0;
 476     virtual void endInlineMemberType() = 0;
 477     virtual void startInlineMemberName() = 0;
 478     virtual void endInlineMemberName() = 0;
 479     virtual void startInlineMemberDoc() = 0;
 480     virtual void endInlineMemberDoc() = 0;
 481
 482
 483     virtual void startLabels() = 0;
 484     virtual void writeLabel(const char *,bool) = 0;
 485     virtual void endLabels() = 0;
 486
 487   protected:
 488     FTextStream t;
 489     QFile *file;
 490     QCString fileName;
 491     QCString dir;
 492     bool active;
 493     QStack<bool> *genStack;
 494
 495   private:
 496     OutputGenerator(const OutputGenerator &o);
 497     OutputGenerator &operator=(const OutputGenerator &o);
 498 };
 499
 500 /** Interface used for generating documentation.
 501  *
 502  *  This abstract class is used by several functions
 503  *  to generate the output for a specific format.
 504  *  This interface contains some state saving and changing
 505  *  functions for dealing with format specific output.
 506  */
 507 class OutputDocInterface : public BaseOutputDocInterface
 508 {
 509   public:
 510     virtual ~OutputDocInterface() {}
 511
 512     /*! Create a new output generator. This can later by appended
 513      *  to the current one using append().
 514      */
 515     //virtual OutputDocInterface *clone() = 0;
 516
 517     /*! Disables all output formats except format \a o
 518      *  (useful for OutputList only)
 519      */
 520     virtual void disableAllBut(OutputGenerator::OutputType o) = 0;
 521
 522     /*! Enables all output formats as far as they have been enabled in
 523      *  the config file. (useful for OutputList only)
 524      */
 525     virtual void enableAll() = 0;
 526
 527     /*! Disables all output formats (useful for OutputList only) */
 528     virtual void disableAll()= 0;
 529
 530     /*! Disables a specific output format (useful for OutputList only) */
 531     virtual void disable(OutputGenerator::OutputType o) = 0;
 532
 533     /*! Enables a specific output format (useful for OutputList only) */
 534     virtual void enable(OutputGenerator::OutputType o) = 0;
 535
 536     /*! Check whether a specific output format is currently enabled
 537      *  (useful for OutputList only)
 538      */
 539     virtual bool isEnabled(OutputGenerator::OutputType o) = 0;
 540
 541     /*! Appends the output generated by generator \a g to this
 542      *  generator.
 543      */
 544     //virtual void append(const OutputDocInterface *g) = 0;
 545
 546     /*! Pushes the state of the current generator (or list of
 547      *  generators) on a stack.
 548      */
 549     virtual void pushGeneratorState() = 0;
 550
 551     /*! Pops the state of the current generator (or list of
 552      *  generators) on a stack. Should be preceded by a call
 553      *  the pushGeneratorState().
 554      */
 555     virtual void popGeneratorState() = 0;
 556 };
 557
 558
 559 #endif