1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the tools applications of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*

    43   ditaxmlgenerator.h

    44 */

    45 

    46 #ifndef DITAXMLGENERATOR_H

    47 #define DITAXMLGENERATOR_H

    48 

    49 #include <qmap.h>

    50 #include <qregexp.h>

    51 #include <QXmlStreamWriter>

    52 #include "codemarker.h"

    53 #include "config.h"

    54 #include "pagegenerator.h"

    55 

    56 QT_BEGIN_NAMESPACE

    57 

    58 typedef QMultiMap<QString, Node*> NodeMultiMap;

    59 typedef QMap<QString, NodeMultiMap> NewSinceMaps;

    60 typedef QMap<Node*, NodeMultiMap> ParentMaps;

    61 typedef QMap<QString, const Node*> NodeMap;

    62 typedef QMap<QString, NodeMap> NewClassMaps;

    63 

    64 class HelpProjectWriter;

    65 

    66 class DitaXmlGenerator : public PageGenerator

    67 {

    68  public:

    69     enum SinceType { 

    70         Namespace, 

    71         Class, 

    72         MemberFunction,

    73         NamespaceFunction,

    74         GlobalFunction,

    75         Macro,

    76         Enum, 

    77         Typedef, 

    78         Property,

    79         Variable, 

    80         QmlClass,

    81         QmlProperty,

    82         QmlSignal,

    83         QmlMethod,

    84         LastSinceType

    85     };

    86 

    87  public:

    88     DitaXmlGenerator();

    89     ~DitaXmlGenerator();

    90 

    91     virtual void initializeGenerator(const Config& config);

    92     virtual void terminateGenerator();

    93     virtual QString format();

    94     virtual void generateTree(const Tree *tree, CodeMarker *marker);

    95 

    96     QString protectEnc(const QString &string);

    97     static QString protect(const QString &string, const QString &encoding = "ISO-8859-1");

    98     static QString cleanRef(const QString& ref);

    99     static QString sinceTitle(int i) { return sinceTitles[i]; }

   100 

   101  protected:

   102     virtual void startText(const Node *relative, CodeMarker *marker);

   103     virtual int generateAtom(const Atom *atom, 

   104                              const Node *relative,

   105                              CodeMarker *marker);

   106     virtual void generateClassLikeNode(const InnerNode *inner, CodeMarker *marker);

   107     virtual void generateFakeNode(const FakeNode *fake, CodeMarker *marker);

   108     virtual QString fileExtension(const Node *node) const;

   109     virtual QString refForNode(const Node *node);

   110     virtual QString linkForNode(const Node *node, const Node *relative);

   111     virtual QString refForAtom(Atom *atom, const Node *node);

   112     

   113     QString fullQualification(const Node* n);

   114 

   115     void writeDerivations(const ClassNode* cn, CodeMarker* marker);

   116     void writeLocation(const Node* n);

   117     void writeFunctions(const Section& s, 

   118                         const ClassNode* cn, 

   119                         CodeMarker* marker);

   120     void writeParameters(const FunctionNode* fn, CodeMarker* marker);

   121     void writeEnumerations(const Section& s, 

   122                            const ClassNode* cn, 

   123                            CodeMarker* marker);

   124     void writeTypedefs(const Section& s, 

   125                        const ClassNode* cn, 

   126                        CodeMarker* marker);

   127     void writeDataMembers(const Section& s, 

   128                           const ClassNode* cn, 

   129                           CodeMarker* marker);

   130     void writeProperties(const Section& s, 

   131                          const ClassNode* cn, 

   132                          CodeMarker* marker);

   133     void writeMacros(const Section& s, 

   134                      const ClassNode* cn, 

   135                      CodeMarker* marker);

   136     void writePropParams(const QString& tag, const NodeList& nlist);

   137 

   138  private:

   139     enum SubTitleSize { SmallSubTitle, LargeSubTitle };

   140 

   141     const QPair<QString,QString> anchorForNode(const Node *node);

   142     const Node *findNodeForTarget(const QString &target, 

   143                                   const Node *relative,

   144                                   CodeMarker *marker, 

   145                                   const Atom *atom = 0);

   146     void generateBreadCrumbs(const QString& title,

   147                              const Node *node,

   148                              CodeMarker *marker);

   149     void generateHeader(const Node* node);

   150     void generateTitle(const QString& title, 

   151                        const Text &subTitle, 

   152                        SubTitleSize subTitleSize,

   153                        const Node *relative, 

   154                        CodeMarker *marker);

   155     void generateBrief(const Node* node, CodeMarker* marker);

   156     void generateIncludes(const InnerNode *inner, CodeMarker *marker);

   157     void generateTableOfContents(const Node *node, 

   158                                  CodeMarker *marker,

   159                                  Doc::SectioningUnit sectioningUnit,

   160                                  int numColumns, 

   161                                  const Node *relative = 0);

   162     void generateTableOfContents(const Node *node, 

   163                                  CodeMarker *marker, 

   164                                  QList<Section>* sections = 0);

   165     QString generateListOfAllMemberFile(const InnerNode *inner, CodeMarker *marker);

   166     QString generateLowStatusMemberFile(const InnerNode *inner, 

   167                                         CodeMarker *marker,

   168                                         CodeMarker::Status status);

   169     void generateClassHierarchy(const Node *relative, 

   170                                 CodeMarker *marker,

   171 				const NodeMap &classMap);

   172     void generateAnnotatedList(const Node *relative, 

   173                                CodeMarker *marker,

   174 			       const NodeMap &nodeMap);

   175     void generateCompactList(const Node *relative, 

   176                              CodeMarker *marker,

   177 			     const NodeMap &classMap,

   178                              bool includeAlphabet,

   179                              QString commonPrefix = QString());

   180     void generateFunctionIndex(const Node *relative, CodeMarker *marker);

   181     void generateLegaleseList(const Node *relative, CodeMarker *marker);

   182     void generateOverviewList(const Node *relative, CodeMarker *marker);

   183     void generateSectionList(const Section& section, 

   184                              const Node *relative,

   185 			     CodeMarker *marker, 

   186                              CodeMarker::SynopsisStyle style);

   187 #ifdef QDOC_QML

   188     void generateQmlSummary(const Section& section,

   189                             const Node *relative,

   190                             CodeMarker *marker);

   191     void generateQmlItem(const Node *node,

   192                          const Node *relative,

   193                          CodeMarker *marker,

   194                          bool summary);

   195     void generateDetailedQmlMember(const Node *node,

   196                                    const InnerNode *relative,

   197                                    CodeMarker *marker);

   198     void generateQmlInherits(const QmlClassNode* cn, CodeMarker* marker);

   199     void generateQmlInheritedBy(const QmlClassNode* cn, CodeMarker* marker);

   200     void generateQmlInstantiates(const QmlClassNode* qcn, CodeMarker* marker);

   201     void generateInstantiatedBy(const ClassNode* cn, CodeMarker* marker);

   202 #endif

   203 

   204     void generateSection(const NodeList& nl,

   205                          const Node *relative,

   206                          CodeMarker *marker,

   207                          CodeMarker::SynopsisStyle style);

   208     void generateSynopsis(const Node *node, 

   209                           const Node *relative, 

   210                           CodeMarker *marker,

   211 			  CodeMarker::SynopsisStyle style,

   212                           bool nameAlignment = false);

   213     void generateSectionInheritedList(const Section& section, 

   214                                       const Node *relative,

   215                                       CodeMarker *marker,

   216                                       bool nameAlignment = false);

   217     QString highlightedCode(const QString& markedCode, 

   218                             CodeMarker *marker, 

   219                             const Node *relative,

   220                             CodeMarker::SynopsisStyle style = CodeMarker::Accessors,

   221                             bool nameAlignment = false);

   222 

   223     void generateFullName(const Node *apparentNode, 

   224                           const Node *relative, 

   225                           CodeMarker *marker,

   226 			  const Node *actualNode = 0);

   227     void generateDetailedMember(const Node *node, 

   228                                 const InnerNode *relative, 

   229                                 CodeMarker *marker);

   230     void generateLink(const Atom *atom, 

   231                       const Node *relative, 

   232                       CodeMarker *marker);

   233     void generateStatus(const Node *node, CodeMarker *marker);

   234     

   235     QString registerRef(const QString& ref);

   236     QString fileBase(const Node *node);

   237 #if 0

   238     QString fileBase(const Node *node, const SectionIterator& section);

   239 #endif

   240     QString fileName(const Node *node);

   241     void findAllClasses(const InnerNode *node);

   242     void findAllFunctions(const InnerNode *node);

   243     void findAllLegaleseTexts(const InnerNode *node);

   244     void findAllNamespaces(const InnerNode *node);

   245     void findAllSince(const InnerNode *node);

   246     static int hOffset(const Node *node);

   247     static bool isThreeColumnEnumValueTable(const Atom *atom);

   248     virtual QString getLink(const Atom *atom, 

   249                             const Node *relative, 

   250                             CodeMarker *marker, 

   251                             const Node** node);

   252     virtual void generateIndex(const QString &fileBase, 

   253                                const QString &url,

   254                                const QString &title);

   255 #ifdef GENERATE_MAC_REFS    

   256     void generateMacRef(const Node *node, CodeMarker *marker);

   257 #endif

   258     void beginLink(const QString &link, 

   259                    const Node *node, 

   260                    const Node *relative, 

   261                    CodeMarker *marker);

   262     void endLink();

   263     bool generatePageElement(QXmlStreamWriter& writer, 

   264                              const Node* node, 

   265                              CodeMarker* marker) const;

   266     void generatePageElements(QXmlStreamWriter& writer, 

   267                               const Node* node, 

   268                               CodeMarker* marker) const;

   269     void generatePageIndex(const QString& fileName, 

   270                            CodeMarker* marker) const;

   271     QString writeGuidAttribute(QString text);

   272     QString lookupGuid(QString text);

   273 

   274  private:

   275     QMap<QString, QString> refMap;

   276     QMap<QString, QString> name2guidMap;

   277     int codeIndent;

   278     bool inLink;

   279     bool inObsoleteLink;

   280     bool inContents;

   281     bool inSectionHeading;

   282     bool inTableHeader;

   283     int numTableRows;

   284     bool threeColumnEnumValueTable;

   285     bool offlineDocs;

   286     QString link;

   287     QStringList sectionNumber;

   288     QRegExp funcLeftParen;

   289     QString style;

   290     QString postHeader;

   291     QString postPostHeader;

   292     QString footer;

   293     QString address;

   294     bool pleaseGenerateMacRef;

   295     QString project;

   296     QString projectDescription;

   297     QString projectUrl;

   298     QString navigationLinks;

   299     QStringList stylesheets;

   300     QStringList customHeadElements;

   301     const Tree *myTree;

   302     bool slow;

   303     bool obsoleteLinks;

   304     int noLinks;

   305     QMap<QString, NodeMap > moduleClassMap;

   306     QMap<QString, NodeMap > moduleNamespaceMap;

   307     NodeMap nonCompatClasses;

   308     NodeMap mainClasses;

   309     NodeMap compatClasses;

   310     NodeMap obsoleteClasses;

   311     NodeMap namespaceIndex;

   312     NodeMap serviceClasses;

   313 #ifdef QDOC_QML    

   314     NodeMap qmlClasses;

   315 #endif

   316     QMap<QString, NodeMap > funcIndex;

   317     QMap<Text, const Node *> legaleseTexts;

   318     NewSinceMaps newSinceMaps;

   319     static QString sinceTitles[];

   320     NewClassMaps newClassMaps;

   321     NewClassMaps newQmlClassMaps;

   322     static int id;

   323     QXmlStreamWriter    writer;

   324 };

   325 

   326 #define DITAXMLGENERATOR_ADDRESS           "address"

   327 #define DITAXMLGENERATOR_FOOTER            "footer"

   328 #define DITAXMLGENERATOR_GENERATEMACREFS   "generatemacrefs" // ### document me

   329 #define DITAXMLGENERATOR_POSTHEADER        "postheader"

   330 #define DITAXMLGENERATOR_POSTPOSTHEADER    "postpostheader"

   331 #define DITAXMLGENERATOR_STYLE             "style"

   332 #define DITAXMLGENERATOR_STYLESHEETS       "stylesheets"

   333 #define DITAXMLGENERATOR_CUSTOMHEADELEMENTS "customheadelements"

   334 

   335 QT_END_NAMESPACE

   336 

   337 #endif

   338