1 /****************************************************************************
2 **
3 ** Copyright (C) 2019 Thibaut Cuvelier
4 ** Contact: https://www.qt.io/licensing/
5 **
6 ** This file is part of the tools applications of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:GPL-EXCEPT$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see https://www.qt.io/terms-conditions. For further
15 ** information use the contact form at https://www.qt.io/contact-us.
16 **
17 ** GNU General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU
19 ** General Public License version 3 as published by the Free Software
20 ** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
21 ** included in the packaging of this file. Please review the following
22 ** information to ensure the GNU General Public License requirements will
23 ** be met: https://www.gnu.org/licenses/gpl-3.0.html.
24 **
25 ** $QT_END_LICENSE$
26 **
27 ****************************************************************************/
28 
29 /*
30   docbookgenerator.h
31 */
32 
33 #ifndef DOCBOOKGENERATOR_H
34 #define DOCBOOKGENERATOR_H
35 
36 #include "codemarker.h"
37 #include "config.h"
38 #include "xmlgenerator.h"
39 
40 #include <QtCore/qhash.h>
41 #include <QtCore/qregexp.h>
42 #include <QtCore/qxmlstream.h>
43 
44 QT_BEGIN_NAMESPACE
45 
46 class DocBookGenerator : public XmlGenerator
47 {
48 public:
49     explicit DocBookGenerator() = default;
50 
51     void initializeGenerator() override;
52     QString format() override;
53 
54 protected:
55     QString fileExtension() const override;
56     void generateDocumentation(Node *node) override;
57     using Generator::generateCppReferencePage;
58     void generateCppReferencePage(Node *node);
59     using Generator::generatePageNode;
60     void generatePageNode(PageNode *pn);
61     using Generator::generateQmlTypePage;
62     void generateQmlTypePage(QmlTypeNode *qcn);
63     using Generator::generateQmlBasicTypePage;
64     void generateQmlBasicTypePage(QmlBasicTypeNode *qbtn);
65     using Generator::generateCollectionNode;
66     void generateCollectionNode(CollectionNode *cn);
67     using Generator::generateGenericCollectionPage;
68     void generateGenericCollectionPage(CollectionNode *cn);
69     using Generator::generateProxyPage;
70     void generateProxyPage(Aggregate *aggregate);
71 
72     void generateList(const Node *relative, const QString &selector);
73     void generateHeader(const QString &title, const QString &subtitle, const Node *node);
74     void closeTextSections();
75     void generateFooter();
76     void generateDocBookSynopsis(const Node *node);
77     void generateRequisites(const Aggregate *inner);
78     void generateQmlRequisites(const QmlTypeNode *qcn);
79     void generateSortedNames(const ClassNode *cn, const QVector<RelatedClass> &rc);
80     void generateSortedQmlNames(const Node *base, const NodeList &subs);
81     bool generateStatus(const Node *node);
82     bool generateThreadSafeness(const Node *node);
83     bool generateSince(const Node *node);
84     void generateAddendum(const Node *node, Generator::Addendum type, CodeMarker *marker = nullptr,
85                           bool generateNote = true) override;
86     using Generator::generateBody;
87     void generateBody(const Node *node);
88 
89     bool generateText(const Text &text, const Node *relative,
90                       CodeMarker *marker = nullptr) override;
91     const Atom *generateAtomList(const Atom *atom, const Node *relative, bool generate,
92                                  int &numAtoms);
93     int generateAtom(const Atom *atom, const Node *relative, CodeMarker *marker = nullptr) override;
94 
95 private:
96     QXmlStreamWriter *startDocument(const Node *node);
97     QXmlStreamWriter *startDocument(const ExampleNode *en, const QString &file);
98     QXmlStreamWriter *startGenericDocument(const Node *node, const QString &fileName);
99     void endDocument();
100 
101     void generateAnnotatedList(const Node *relative, const NodeList &nodeList,
102                                const QString &selector);
103     void generateAnnotatedList(const Node *relative, const NodeMultiMap &nmm,
104                                const QString &selector);
105     void generateAnnotatedLists(const Node *relative, const NodeMultiMap &nmm,
106                                 const QString &selector);
107     void generateCompactList(ListType listType, const Node *relative, const NodeMultiMap &nmm,
108                              const QString &commonPrefix, const QString &selector);
109     using Generator::generateFileList;
110     void generateFileList(const ExampleNode *en, bool images);
111     void generateObsoleteMembers(const Sections &sections);
112     void generateObsoleteQmlMembers(const Sections &sections);
113     void generateSectionList(const Section &section, const Node *relative,
114                              Section::Status status = Section::Active);
115     void generateSectionInheritedList(const Section &section, const Node *relative);
116     void generateSynopsisName(const Node *node, const Node *relative, bool generateNameLink);
117     void generateParameter(const Parameter &parameter, const Node *relative, bool generateExtra,
118                            bool generateType);
119     void generateSynopsis(const Node *node, const Node *relative, Section::Style style);
120     void generateEnumValue(const QString &enumValue, const Node *relative);
121     void generateDetailedMember(const Node *node, const PageNode *relative);
122     void generateDetailedQmlMember(Node *node, const Aggregate *relative);
123 
124     void generateFullName(const Node *node, const Node *relative);
125     void generateFullName(const Node *apparentNode, const QString &fullName,
126                           const Node *actualNode);
127     void generateBrief(const Node *node);
128     void generateAlsoList(const Node *node, CodeMarker *marker = nullptr) override;
129     void generateSignatureList(const NodeList &nodes);
130     void generateMaintainerList(const Aggregate *node, CodeMarker *marker = nullptr) override;
131     void generateReimplementsClause(const FunctionNode *fn);
132     void generateClassHierarchy(const Node *relative, NodeMap &classMap);
133     void generateFunctionIndex(const Node *relative);
134     void generateLegaleseList(const Node *relative);
135     void generateExampleFilePage(const Node *en, const QString &file,
136                                  CodeMarker *marker = nullptr) override;
137     void generateOverloadedSignal(const Node *node);
138     bool generateQmlText(const Text &text, const Node *relative, CodeMarker *marker = nullptr,
139                          const QString &qmlName = QString()) override;
140     void generateRequiredLinks(const Node *node);
141     void generateLinkToExample(const ExampleNode *en, const QString &baseUrl);
142 
143     void typified(const QString &string, const Node *relative, bool trailingSpace = false,
144                   bool generateType = true);
145     void generateLink(const Atom *atom);
146     void beginLink(const QString &link, const Node *node, const Node *relative);
147     void endLink();
148     inline void newLine();
149     void startSectionBegin();
150     void startSectionBegin(const QString &id);
151     void startSectionEnd();
152     void startSection(const QString &id, const QString &title);
153     void endSection();
154     void writeAnchor(const QString &id);
155     void generateSimpleLink(const QString &href, const QString &text);
156     void generateStartRequisite(const QString &description);
157     void generateEndRequisite();
158     void generateRequisite(const QString &description, const QString &value);
159     void generateSynopsisInfo(const QString &key, const QString &value);
160     void generateModifier(const QString &value);
161 
162     bool inListItemLineOpen {};
163     bool inLink {};
164     int currentSectionLevel {};
165     QStack<int> sectionLevels {};
166     QString qflagsHref_;
167 
168     QString project;
169     QString projectDescription;
170     QString naturalLanguage;
171     QString buildversion;
172     QXmlStreamWriter *writer = nullptr;
173 
174     Config *config = nullptr;
175 };
176 
177 QT_END_NAMESPACE
178 
179 #endif
180