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