1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the tools applications of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
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 http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file.  Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41 
42 #ifndef DITAXMLGENERATOR_H
43 #define DITAXMLGENERATOR_H
44 
45 #include <qmap.h>
46 #include <qregexp.h>
47 #include <QXmlStreamWriter>
48 #include "codemarker.h"
49 #include "config.h"
50 #include "pagegenerator.h"
51 
52 QT_BEGIN_NAMESPACE
53 
54 typedef QMap<QString, QString> GuidMap;
55 typedef QMap<QString, GuidMap*> GuidMaps;
56 
57 class DitaXmlGenerator : public PageGenerator
58 {
59  public:
60     enum SinceType {
61         Namespace,
62         Class,
63         MemberFunction,
64         NamespaceFunction,
65         GlobalFunction,
66         Macro,
67         Enum,
68         Typedef,
69         Property,
70         Variable,
71         QmlClass,
72         QmlProperty,
73         QmlSignal,
74         QmlMethod,
75         LastSinceType
76     };
77 
78     enum DitaTag {
79         DT_NONE,
80         DT_alt,
81         DT_apiDesc,
82         DT_APIMap,
83         DT_apiName,
84         DT_apiRelation,
85         DT_audience,
86         DT_author,
87         DT_b,
88         DT_body,
89         DT_bodydiv,
90         DT_brand,
91         DT_category,
92         DT_codeblock,
93         DT_comment,
94         DT_component,
95         DT_copyrholder,
96         DT_copyright,
97         DT_copyryear,
98         DT_created,
99         DT_critdates,
100         DT_cxxAPIMap,
101         DT_cxxClass,
102         DT_cxxClassAbstract,
103         DT_cxxClassAccessSpecifier,
104         DT_cxxClassAPIItemLocation,
105         DT_cxxClassBaseClass,
106         DT_cxxClassDeclarationFile,
107         DT_cxxClassDeclarationFileLine,
108         DT_cxxClassDefinition,
109         DT_cxxClassDerivation,
110         DT_cxxClassDerivationAccessSpecifier,
111         DT_cxxClassDerivations,
112         DT_cxxClassDetail,
113         DT_cxxClassNested,
114         DT_cxxClassNestedClass,
115         DT_cxxClassNestedDetail,
116         DT_cxxDefine,
117         DT_cxxDefineAccessSpecifier,
118         DT_cxxDefineAPIItemLocation,
119         DT_cxxDefineDeclarationFile,
120         DT_cxxDefineDeclarationFileLine,
121         DT_cxxDefineDefinition,
122         DT_cxxDefineDetail,
123         DT_cxxDefineNameLookup,
124         DT_cxxDefineParameter,
125         DT_cxxDefineParameterDeclarationName,
126         DT_cxxDefineParameters,
127         DT_cxxDefinePrototype,
128         DT_cxxDefineReimplemented,
129         DT_cxxEnumeration,
130         DT_cxxEnumerationAccessSpecifier,
131         DT_cxxEnumerationAPIItemLocation,
132         DT_cxxEnumerationDeclarationFile,
133         DT_cxxEnumerationDeclarationFileLine,
134         DT_cxxEnumerationDefinition,
135         DT_cxxEnumerationDefinitionFile,
136         DT_cxxEnumerationDefinitionFileLineStart,
137         DT_cxxEnumerationDefinitionFileLineEnd,
138         DT_cxxEnumerationDetail,
139         DT_cxxEnumerationNameLookup,
140         DT_cxxEnumerationPrototype,
141         DT_cxxEnumerationScopedName,
142         DT_cxxEnumerator,
143         DT_cxxEnumeratorInitialiser,
144         DT_cxxEnumeratorNameLookup,
145         DT_cxxEnumeratorPrototype,
146         DT_cxxEnumerators,
147         DT_cxxEnumeratorScopedName,
148         DT_cxxFunction,
149         DT_cxxFunctionAccessSpecifier,
150         DT_cxxFunctionAPIItemLocation,
151         DT_cxxFunctionConst,
152         DT_cxxFunctionConstructor,
153         DT_cxxFunctionDeclarationFile,
154         DT_cxxFunctionDeclarationFileLine,
155         DT_cxxFunctionDeclaredType,
156         DT_cxxFunctionDefinition,
157         DT_cxxFunctionDestructor,
158         DT_cxxFunctionDetail,
159         DT_cxxFunctionNameLookup,
160         DT_cxxFunctionParameter,
161         DT_cxxFunctionParameterDeclarationName,
162         DT_cxxFunctionParameterDeclaredType,
163         DT_cxxFunctionParameterDefaultValue,
164         DT_cxxFunctionParameters,
165         DT_cxxFunctionPrototype,
166         DT_cxxFunctionPureVirtual,
167         DT_cxxFunctionReimplemented,
168         DT_cxxFunctionScopedName,
169         DT_cxxFunctionStorageClassSpecifierStatic,
170         DT_cxxFunctionVirtual,
171         DT_cxxTypedef,
172         DT_cxxTypedefAccessSpecifier,
173         DT_cxxTypedefAPIItemLocation,
174         DT_cxxTypedefDeclarationFile,
175         DT_cxxTypedefDeclarationFileLine,
176         DT_cxxTypedefDefinition,
177         DT_cxxTypedefDetail,
178         DT_cxxTypedefNameLookup,
179         DT_cxxTypedefScopedName,
180     	DT_cxxVariable,
181     	DT_cxxVariableAccessSpecifier,
182     	DT_cxxVariableAPIItemLocation,
183         DT_cxxVariableDeclarationFile,
184         DT_cxxVariableDeclarationFileLine,
185     	DT_cxxVariableDeclaredType,
186     	DT_cxxVariableDefinition,
187     	DT_cxxVariableDetail,
188     	DT_cxxVariableNameLookup,
189     	DT_cxxVariablePrototype,
190     	DT_cxxVariableReimplemented,
191     	DT_cxxVariableScopedName,
192     	DT_cxxVariableStorageClassSpecifierStatic,
193         DT_data,
194         DT_dataabout,
195         DT_dd,
196         DT_dl,
197         DT_dlentry,
198         DT_dt,
199         DT_entry,
200         DT_fig,
201         DT_i,
202         DT_image,
203         DT_keyword,
204         DT_keywords,
205         DT_li,
206         DT_link,
207         DT_linktext,
208         DT_lq,
209         DT_metadata,
210         DT_ol,
211         DT_othermeta,
212         DT_p,
213         DT_parameter,
214         DT_permissions,
215         DT_ph,
216         DT_platform,
217         DT_pre,
218         DT_prodinfo,
219         DT_prodname,
220         DT_prolog,
221         DT_publisher,
222         DT_relatedLinks,
223         DT_resourceid,
224         DT_revised,
225         DT_row,
226         DT_section,
227         DT_sectiondiv,
228         DT_shortdesc,
229         DT_simpletable,
230         DT_source,
231         DT_stentry,
232         DT_sthead,
233         DT_strow,
234         DT_sub,
235         DT_sup,
236         DT_table,
237         DT_tbody,
238         DT_tgroup,
239         DT_thead,
240         DT_title,
241         DT_tm,
242         DT_topic,
243         DT_topicmeta,
244         DT_topicref,
245         DT_tt,
246         DT_u,
247         DT_ul,
248         DT_unknown,
249         DT_vrm,
250         DT_vrmlist,
251         DT_xref,
252         DT_LAST
253     };
254 
255  public:
256     DitaXmlGenerator();
257     ~DitaXmlGenerator();
258 
259     virtual void initializeGenerator(const Config& config);
260     virtual void terminateGenerator();
261     virtual QString format();
262     virtual bool canHandleFormat(const QString& format);
263     virtual void generateTree(const Tree *tree);
264 
265     QString protectEnc(const QString& string);
266     static QString protect(const QString& string, const QString& encoding = "ISO-8859-1");
267     static QString cleanRef(const QString& ref);
sinceTitle(int i)268     static QString sinceTitle(int i) { return sinceTitles[i]; }
269 
270  protected:
271     virtual void startText(const Node* relative, CodeMarker* marker);
272     virtual int generateAtom(const Atom* atom,
273                              const Node* relative,
274                              CodeMarker* marker);
275     virtual void generateClassLikeNode(const InnerNode* inner, CodeMarker* marker);
276     virtual void generateFakeNode(const FakeNode* fake, CodeMarker* marker);
277     virtual QString fileExtension(const Node* node) const;
278     virtual QString refForNode(const Node* node);
279     virtual QString guidForNode(const Node* node);
280     virtual QString linkForNode(const Node* node, const Node* relative);
281     virtual QString refForAtom(Atom* atom, const Node* node);
282 
283     void writeXrefListItem(const QString& link, const QString& text);
284     QString fullQualification(const Node* n);
285 
286     void writeCharacters(const QString& text);
287     void writeDerivations(const ClassNode* cn, CodeMarker* marker);
288     void writeLocation(const Node* n);
289     void writeFunctions(const Section& s,
290                         const InnerNode* parent,
291                         CodeMarker* marker,
292                         const QString& attribute = QString());
293     void writeNestedClasses(const Section& s, const Node* n);
294     void replaceTypesWithLinks(const Node* n,
295                                const InnerNode* parent,
296                                CodeMarker* marker,
297                                QString& src);
298     void writeParameters(const FunctionNode* fn, const InnerNode* parent, CodeMarker* marker);
299     void writeEnumerations(const Section& s,
300                            CodeMarker* marker,
301                            const QString& attribute = QString());
302     void writeTypedefs(const Section& s,
303                        CodeMarker* marker,
304                        const QString& attribute = QString());
305     void writeDataMembers(const Section& s,
306                           CodeMarker* marker,
307                           const QString& attribute = QString());
308     void writeProperties(const Section& s,
309                          CodeMarker* marker,
310                          const QString& attribute = QString());
311     void writeMacros(const Section& s,
312                      CodeMarker* marker,
313                      const QString& attribute = QString());
314     void writePropertyParameter(const QString& tag, const NodeList& nlist);
315     void writeRelatedLinks(const FakeNode* fake, CodeMarker* marker);
316     void writeLink(const Node* node, const QString& tex, const QString& role);
317     void writeProlog(const InnerNode* inner);
318     bool writeMetadataElement(const InnerNode* inner,
319                               DitaXmlGenerator::DitaTag t,
320                               bool force=true);
321     bool writeMetadataElements(const InnerNode* inner, DitaXmlGenerator::DitaTag t);
322     QString getMetadataElement(const InnerNode* inner, DitaXmlGenerator::DitaTag t);
323     QStringList getMetadataElements(const InnerNode* inner, DitaXmlGenerator::DitaTag t);
324 
325  private:
326     enum SubTitleSize { SmallSubTitle, LargeSubTitle };
327 
328     const QPair<QString,QString> anchorForNode(const Node* node);
329     const Node* findNodeForTarget(const QString& target,
330                                   const Node* relative,
331                                   CodeMarker* marker,
332                                   const Atom* atom = 0);
333     void generateHeader(const Node* node,
334                         const QString& name,
335                         bool subpage = false);
336     void generateBrief(const Node* node, CodeMarker* marker);
337     void generateIncludes(const InnerNode* inner, CodeMarker* marker);
338     void generateTableOfContents(const Node* node,
339                                  CodeMarker* marker,
340                                  Doc::Sections sectioningUnit,
341                                  int numColumns,
342                                  const Node* relative = 0);
343     void generateTableOfContents(const Node* node,
344                                  CodeMarker* marker,
345                                  QList<Section>* sections = 0);
346     void generateLowStatusMembers(const InnerNode* inner,
347                                   CodeMarker* marker,
348                                   CodeMarker::Status status);
349     QString generateLowStatusMemberFile(const InnerNode* inner,
350                                         CodeMarker* marker,
351                                         CodeMarker::Status status);
352     void generateClassHierarchy(const Node* relative,
353                                 CodeMarker* marker,
354 				const NodeMap& classMap);
355     void generateAnnotatedList(const Node* relative,
356                                CodeMarker* marker,
357 			       const NodeMap& nodeMap);
358     void generateCompactList(const Node* relative,
359                              CodeMarker* marker,
360 			     const NodeMap& classMap,
361                              bool includeAlphabet,
362                              QString commonPrefix = QString());
363     void generateFunctionIndex(const Node* relative, CodeMarker* marker);
364     void generateLegaleseList(const Node* relative, CodeMarker* marker);
365     void generateOverviewList(const Node* relative, CodeMarker* marker);
366 
367 #ifdef QDOC_QML
368     void generateQmlSummary(const Section& section,
369                             const Node* relative,
370                             CodeMarker* marker);
371     void generateQmlItem(const Node* node,
372                          const Node* relative,
373                          CodeMarker* marker,
374                          bool summary);
375     void generateDetailedQmlMember(const Node* node,
376                                    const InnerNode* relative,
377                                    CodeMarker* marker);
378     void generateQmlInherits(const QmlClassNode* cn, CodeMarker* marker);
379     void generateQmlInheritedBy(const QmlClassNode* cn, CodeMarker* marker);
380     void generateQmlInstantiates(const QmlClassNode* qcn, CodeMarker* marker);
381     void generateInstantiatedBy(const ClassNode* cn, CodeMarker* marker);
382 #endif
383 
384     void generateSection(const NodeList& nl,
385                          const Node* relative,
386                          CodeMarker* marker,
387                          CodeMarker::SynopsisStyle style);
388     QString getMarkedUpSynopsis(const Node* node,
389                                 const Node* relative,
390                                 CodeMarker* marker,
391                                 CodeMarker::SynopsisStyle style);
392     void generateSectionInheritedList(const Section& section,
393                                       const Node* relative,
394                                       CodeMarker* marker);
395     void writeText(const QString& markedCode,
396                    CodeMarker* marker,
397                    const Node* relative);
398 
399     void generateFullName(const Node* apparentNode,
400                           const Node* relative,
401                           CodeMarker* marker,
402 			  const Node* actualNode = 0);
403     void generateLink(const Atom* atom,
404                       const Node* relative,
405                       CodeMarker* marker);
406     void generateStatus(const Node* node, CodeMarker* marker);
407 
408     QString registerRef(const QString& ref);
409     QString fileBase(const Node *node) const;
410     QString fileName(const Node *node);
411     void findAllClasses(const InnerNode *node);
412     void findAllFunctions(const InnerNode *node);
413     void findAllLegaleseTexts(const InnerNode *node);
414     void findAllNamespaces(const InnerNode *node);
415     static int hOffset(const Node *node);
416     static bool isThreeColumnEnumValueTable(const Atom *atom);
417     virtual QString getLink(const Atom *atom,
418                             const Node *relative,
419                             CodeMarker *marker,
420                             const Node **node);
421     virtual void generateIndex(const QString& fileBase,
422                                const QString& url,
423                                const QString& title);
424 #ifdef GENERATE_MAC_REFS
425     void generateMacRef(const Node* node, CodeMarker* marker);
426 #endif
427     void beginLink(const QString& link);
428     void endLink();
429     QString writeGuidAttribute(QString text);
430     void writeGuidAttribute(Node* node);
431     QString lookupGuid(QString text);
432     QString lookupGuid(const QString& fileName, const QString& text);
433     GuidMap* lookupGuidMap(const QString& fileName);
434     virtual void beginSubPage(const Location& location, const QString& fileName);
435     virtual void endSubPage();
436     virtual void generateInnerNode(const InnerNode* node);
437     QXmlStreamWriter& xmlWriter();
438     void writeApiDesc(const Node* node, CodeMarker* marker, const QString& title);
439     void addLink(const QString& href, const QStringRef& text, DitaTag t = DT_xref);
440     void writeDitaMap();
441     void writeStartTag(DitaTag t);
442     void writeEndTag(DitaTag t=DT_NONE);
443     DitaTag currentTag();
clearSectionNesting()444     void clearSectionNesting() { sectionNestingLevel = 0; }
445     int enterApiDesc(const QString& outputclass, const QString& title);
446     int enterSection(const QString& outputclass, const QString& title);
447     int leaveSection();
inSection()448     bool inSection() const { return (sectionNestingLevel > 0); }
currentSectionNestingLevel()449     int currentSectionNestingLevel() const { return sectionNestingLevel; }
450     QString metadataDefault(DitaTag t) const;
451 
452  private:
453     /*
454       These flags indicate which elements the generator
455       is currently outputting.
456      */
457     bool inContents;
458     bool inDetailedDescription;
459     bool inLegaleseText;
460     bool inLink;
461     bool inObsoleteLink;
462     bool inSectionHeading;
463     bool inTableHeader;
464     bool inTableBody;
465 
466     bool noLinks;
467     bool obsoleteLinks;
468     bool offlineDocs;
469     bool threeColumnEnumValueTable;
470 
471     int codeIndent;
472     int numTableRows;
473     int divNestingLevel;
474     int sectionNestingLevel;
475     int tableColumnCount;
476 
477     QString link;
478     QStringList sectionNumber;
479     QRegExp funcLeftParen;
480     QString style;
481     QString postHeader;
482     QString postPostHeader;
483     QString footer;
484     QString address;
485     bool pleaseGenerateMacRef;
486     QString project;
487     QString projectDescription;
488     QString projectUrl;
489     QString navigationLinks;
490     QString version;
491     QStringList vrm;
492     QStringList stylesheets;
493     QStringList customHeadElements;
494     const Tree* myTree;
495     QMap<QString, QString> refMap;
496     QMap<QString, QString> name2guidMap;
497     GuidMaps guidMaps;
498     QMap<QString, NodeMap > moduleClassMap;
499     QMap<QString, NodeMap > moduleNamespaceMap;
500     NodeMap nonCompatClasses;
501     NodeMap mainClasses;
502     NodeMap compatClasses;
503     NodeMap obsoleteClasses;
504     NodeMap namespaceIndex;
505     NodeMap serviceClasses;
506 #ifdef QDOC_QML
507     NodeMap qmlClasses;
508 #endif
509     QMap<QString, NodeMap > funcIndex;
510     QMap<Text, const Node*> legaleseTexts;
511     static int id;
512     static QString ditaTags[];
513     QStack<QXmlStreamWriter*> xmlWriterStack;
514     QStack<DitaTag> tagStack;
515     QStringMultiMap metadataDefaults;
516 };
517 
518 #define DITAXMLGENERATOR_ADDRESS           "address"
519 #define DITAXMLGENERATOR_FOOTER            "footer"
520 #define DITAXMLGENERATOR_GENERATEMACREFS   "generatemacrefs" // ### document me
521 #define DITAXMLGENERATOR_POSTHEADER        "postheader"
522 #define DITAXMLGENERATOR_POSTPOSTHEADER    "postpostheader"
523 #define DITAXMLGENERATOR_STYLE             "style"
524 #define DITAXMLGENERATOR_STYLESHEETS       "stylesheets"
525 #define DITAXMLGENERATOR_CUSTOMHEADELEMENTS "customheadelements"
526 
527 QT_END_NAMESPACE
528 
529 #endif
530