/usr/share/qt5/doc/qdoc/22-qdoc-configuration-generalvariables.html is in qttools5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdoc-manual-qdocconf.qdoc -->
<title>Generic Configuration Variables | QDoc Manual 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qdoc-index.html">QDoc Manual</a></td><td >Generic Configuration Variables</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="21-0-qdoc-configuration.html" />
<link rel="next" href="22-creating-help-project-files.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="21-0-qdoc-configuration.html">The QDoc Configuration File</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="22-creating-help-project-files.html">Creating Help Project Files</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#alias">alias</a></li>
<li class="level1"><a href="#codeindent">codeindent</a></li>
<li class="level1"><a href="#codeprefix-codesuffix">codeprefix, codesuffix</a></li>
<li class="level1"><a href="#defines">defines</a></li>
<li class="level1"><a href="#edition">edition</a></li>
<li class="level1"><a href="#exampledirs">exampledirs</a></li>
<li class="level1"><a href="#examples">examples</a></li>
<li class="level1"><a href="#examples-fileextensions">examples.fileextensions</a></li>
<li class="level1"><a href="#excludedirs">excludedirs</a></li>
<li class="level1"><a href="#excludefiles">excludefiles</a></li>
<li class="level1"><a href="#extraimages">extraimages</a></li>
<li class="level1"><a href="#falsehoods">falsehoods</a></li>
<li class="level1"><a href="#generateindex">generateindex</a></li>
<li class="level1"><a href="#headerdirs">headerdirs</a></li>
<li class="level1"><a href="#headers">headers</a></li>
<li class="level1"><a href="#headers-fileextensions">headers.fileextensions</a></li>
<li class="level1"><a href="#imagedirs">imagedirs</a></li>
<li class="level1"><a href="#images">images</a></li>
<li class="level1"><a href="#images-fileextensions">images.fileextensions</a></li>
<li class="level1"><a href="#language">language</a></li>
<li class="level1"><a href="#macro">macro</a></li>
<li class="level1"><a href="#manifestmeta">manifestmeta</a></li>
<li class="level1"><a href="#naturallanguage">naturallanguage</a></li>
<li class="level1"><a href="#outputdir">outputdir</a></li>
<li class="level1"><a href="#outputencoding">outputencoding</a></li>
<li class="level1"><a href="#outputformats">outputformats</a></li>
<li class="level1"><a href="#outputprefixes">outputprefixes</a></li>
<li class="level1"><a href="#outputsuffixes">outputsuffixes</a></li>
<li class="level1"><a href="#qhp">qhp</a></li>
<li class="level1"><a href="#sourcedirs">sourcedirs</a></li>
<li class="level1"><a href="#sourceencoding">sourceencoding</a></li>
<li class="level1"><a href="#sources">sources</a></li>
<li class="level1"><a href="#sources-fileextensions">sources.fileextensions</a></li>
<li class="level1"><a href="#spurious">spurious</a></li>
<li class="level1"><a href="#syntaxhighlighting">syntaxhighlighting</a></li>
<li class="level1"><a href="#tabsize">tabsize</a></li>
<li class="level1"><a href="#tagfile">tagfile</a></li>
<li class="level1"><a href="#version">version</a></li>
<li class="level1"><a href="#versionsym">versionsym</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Generic Configuration Variables</h1>
<span class="subtitle"></span>
<!-- $$$22-qdoc-configuration-generalvariables.html-description -->
<div class="descr"> <a name="details"></a>
<p>With the general QDoc configuration variables, you can define where QDoc will find the various source files it needs to generate the documentation, as well as the directory to put the generated documentation. You can also do some minor manipulation of QDoc itself, controlling its output and processing behavior.</p>
<a name="alias-variable"></a><a name="alias"></a>
<h2 id="alias">alias</h2>
<p>The <code>alias</code> variable renames a QDoc command.</p>
<p>The general syntax is <code>alias.<i>original-command-name</i> = <i>temporary-command-name</i></code>.</p>
<pre class="cpp plain">
alias.e = i
</pre>
<p>This renames the built-in command \e (italics) to be \i. The <code>alias</code> variable is often used for compatibility reasons.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#macro-variable">macro</a>.</p>
<a name="codeindent-variable"></a><a name="codeindent"></a>
<h2 id="codeindent">codeindent</h2>
<p>The <code>codeindent</code> variable specifies the level of indentation that QDoc uses when writing code snippets.</p>
<p>QDoc originally used a hard-coded value of four spaces for code indentation to ensure that code snippets could be easily distinguished from surrounding text. Since we can use <a href="24-qdoc-configuration-htmlvariables.html#html-stylesheets">stylesheets</a> to adjust the appearance of certain types of HTML elements, this level of indentation is not always required.</p>
<a name="codeprefix-variable"></a><a name="codesuffix-variable"></a><a name="codeprefix-codesuffix"></a>
<h2 id="codeprefix-codesuffix">codeprefix, codesuffix</h2>
<p>The <code>codeprefix</code> and <code>codesuffix</code> variables specify a pair of strings that each code snippet is enclosed in.</p>
<a name="defines-variable"></a><a name="defines"></a>
<h2 id="defines">defines</h2>
<p>The <code>defines</code> variable specifies the C++ preprocessor symbols that QDoc will recognize and respond to.</p>
<p>When a preprocessor symbol is specified using the <code>defines</code> variable, you can also use the <a href="12-0-qdoc-commands-miscellaneous.html#if-command">\if</a> command to enclose documentation that only will be included if the preprocessor symbol is defined.</p>
<p>The values of the variable are regular expressions (see <a href="../qtcore/qregexp.html">QRegExp</a> for details). By default, no symbol is defined, meaning that code protected with #ifdef...#endif will be ignored.</p>
<pre class="cpp plain">
defines = Q_QDOC \
QT_.*_SUPPORT \
QT_.*_LIB \
QT_COMPAT \
QT3_SUPPORT \
Q_OS_.* \
Q_BYTE_ORDER \
__cplusplus
</pre>
<p>This ensures that QDoc will process the code that requires these symbols to be defined. For example:</p>
<pre class="cpp">
<span class="preprocessor">#ifdef Q_OS_WIN</span>
HDC getDC() <span class="keyword">const</span>;
<span class="type">void</span> releaseDC(HDC) <span class="keyword">const</span>;
<span class="preprocessor">#endif</span>
</pre>
<p>Since the Q_OS_.* regular expression (specified using the <code>defines</code> variable) matches <a href="../qtcore/qtglobal.html#Q_OS_WIN">Q_OS_WIN</a>, QDoc will process the code within #ifdef and #endif in our example.</p>
<p>You can also define preprocessor symbols manually on the command line using the -D option. For example:</p>
<pre class="cpp plain">
currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf
</pre>
<p>In this case the -D option ensures that the <code>consoleedition</code> preprocessor symbol is defined when QDoc processes the source files defined in the qtgui.qdocconf file.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#falsehoods-variable">falsehoods</a> and <a href="12-0-qdoc-commands-miscellaneous.html#if-command">\if</a>.</p>
<a name="edition-variable"></a><a name="edition"></a>
<h2 id="edition">edition</h2>
<p>The <code>edition</code> variable specifies which modules are included in each edition of a package, and provides QDoc with information to provide class lists for each edition.</p>
<p>This feature is mostly used when providing documentation for Qt packages.</p>
<p>The <code>edition</code> variable is always used with a particular edition name to define the modules for that edition:</p>
<pre class="cpp plain">
edition.Console = QtCore QtNetwork QtSql QtXml
edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
QtDesigner QtAssistant Qt3Support QAxContainer \
QAxServer
edition.DesktopLight = QtCore QtGui Qt3SupportLight
</pre>
<p>In the above examples, the <code>Console</code> edition only includes the contents of four modules. Only the classes from these modules will be used when the <a href="12-0-qdoc-commands-miscellaneous.html#generatelist-command">generatelist</a> command is used to generate a list of classes for this edition:</p>
<pre class="cpp plain">
\generatelist{classesbyedition Console}
</pre>
<a name="exampledirs-variable"></a><a name="exampledirs"></a>
<h2 id="exampledirs">exampledirs</h2>
<p>The <code>exampledirs</code> variable specifies the directories containing the source code of the example files.</p>
<p>The <a href="22-qdoc-configuration-generalvariables.html#examples-variable">examples</a> and <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable">exampledirs</a> variables are used by the <a href="07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command">\quotefromfile</a>, <a href="07-0-qdoc-commands-includingexternalcode.html#quotefile-command">\quotefile</a> and <a href="13-qdoc-commands-topics.html#example-command">\example</a> commands. If both the <a href="22-qdoc-configuration-generalvariables.html#examples-variable">examples</a> and <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable">exampledirs</a> variables are defined, QDoc will search in both, first in <a href="22-qdoc-configuration-generalvariables.html#examples-variable">examples</a> then in <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable">exampledirs</a>.</p>
<p>QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, <i>not</i> in subdirectories.</p>
<pre class="cpp plain">
exampledirs = $QTDIR/doc/src \
$QTDIR/examples \
$QTDIR \
$QTDIR/qmake/examples
examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
</pre>
<p>When processing</p>
<pre class="cpp plain">
\quotefromfile widgets/calculator/calculator.cpp
</pre>
<p>QDoc will see if there is a file called <code>calculator.cpp</code> listed as a value in the <a href="22-qdoc-configuration-generalvariables.html#examples-variable"><code>examples</code></a> variable. If there isn't, it will search in the <code>exampledirs</code> variable, and first see if there exists a file called</p>
<pre class="cpp plain">
$QTDIR/doc/src/widgets/calculator/calculator.cpp
</pre>
<p>If it doesn't, QDoc will continue looking for a file called</p>
<pre class="cpp plain">
$QTDIR/examples/widgets/calculator/calculator.cpp
</pre>
<p>and so forth.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#examples-variable">examples</a>.</p>
<a name="examples-variable"></a><a name="examples"></a>
<h2 id="examples">examples</h2>
<p>The <code>examples</code> variable allows you to specify individual example files in addition to those located in the directories specified by the <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable"><code>exampledirs</code></a> variable.</p>
<p>The <code>examples</code> and <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable"><code>exampledirs</code></a> variables are used by the <a href="07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command">\quotefromfile</a>, <a href="07-0-qdoc-commands-includingexternalcode.html#quotefile-command">\quotefile</a> and <a href="13-qdoc-commands-topics.html#example-command">\example</a> commands. If both the <code>examples</code> and <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable"><code>exampledirs</code></a> variables are defined, QDoc will search in both, first in <code>examples</code> then in <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable"><code>exampledirs</code></a>.</p>
<p>QDoc will search through the values listed for the <code>examples</code> variable, in the specified order, and accept the first one it finds.</p>
<p>For an extensive example, see the <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable"><code>exampledirs</code></a> command. But note that if you know the file is listed in the <code>examples</code> variable, you don't need to specify its path:</p>
<pre class="cpp plain">
\quotefromfile calculator.cpp
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#exampledirs-variable">exampledirs</a>.</p>
<a name="examples-fileextensions-variable"></a><a name="examples-fileextensions"></a>
<h2 id="examples-fileextensions">examples.fileextensions</h2>
<p>The <code>examples.fileextensions</code> variable specifies the file extensions that qdoc will look for when collecting example files for display in the documentation.</p>
<p>The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml and *.ui.</p>
<p>The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:</p>
<pre class="cpp plain">
examples.fileextensions += *.qrc
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#headers-fileextensions">headers.fileextensions</a>.</p>
<a name="excludedirs-variable"></a><a name="excludedirs"></a>
<h2 id="excludedirs">excludedirs</h2>
<p>The <code>excludedirs</code> variable is for listing directories that should <i>not</i> be processed by qdoc, even if the same directories are included by the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable">sourcedirs</a> or <a href="22-qdoc-configuration-generalvariables.html#headerdirs-variable">headerdirs</a> variables.</p>
<p>For example:</p>
<pre class="cpp plain">
sourcedirs = src/corelib
excludedirs = src/corelib/tmp
</pre>
<p>When executed, QDoc will exclude the listed directories from further consideration. Files in these directories will not be read by qdoc.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#excludefiles-variable">excludefiles</a>.</p>
<a name="excludefiles-variable"></a><a name="excludefiles"></a>
<h2 id="excludefiles">excludefiles</h2>
<p>The <code>excludefiles</code> variable allows you to specify individual files that should <i>not</i> be processed by qdoc.</p>
<pre class="cpp plain">
excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
$QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
</pre>
<p>If you include the above in your qdocconf file for qtbase, there will be no class documentation generated for <a href="../qtwidgets/qwidget.html">QWidget</a>.</p>
<p>Since Qt 5.6, also simple wildcards ('*' and '?') are recognized by <code>excludefiles</code>. For example, to exclude all private Qt header files from being parsed, define the following:</p>
<pre class="cpp plain">
excludefiles += "*_p.h"
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#excludedirs-variable">excludedirs</a>.</p>
<a name="extraimages-variable"></a><a name="extraimages"></a>
<h2 id="extraimages">extraimages</h2>
<p>The <code>extraimages</code> variable tells QDoc to incorporate specific images in the generated documentation.</p>
<p>QDoc will not recognize images used within HTML (or any other markup language). If we want the images to be copied from the directories specified by <a href="22-qdoc-configuration-generalvariables.html#imagedirs"><code>imagedirs</code></a> (the images in question must be located in these directories) to the output directory, we must specify the images using the <code>extraimages</code> variable.</p>
<p>The general syntax is <code>extraimages.<i>format</i> = <i>image</i></code>. The file extension is optional.</p>
<p>For example, in <a href="21-2-qtgui-qdocconf.html">qtgui.qdocconf</a> we use a couple of images within the HTML.postheader variable which value is pure HTML. For that reason, these images are specified using the <code>extraimages</code> variable:</p>
<pre class="cpp plain">
extraimages.HTML = qt-logo
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#images">images</a> and <a href="22-qdoc-configuration-generalvariables.html#imagedirs">imagedirs</a>.</p>
<a name="falsehoods-variable"></a><a name="falsehoods"></a>
<h2 id="falsehoods">falsehoods</h2>
<p>The <code>falsehoods</code> variable defines the truth value of specified preprocessor symbols as false.</p>
<p>If this variable is not set for a preprocessor symbol, QDoc assumes its truth value is true. The exception is '0', which value always is false.</p>
<p>QDoc will recognize, and is able to evaluate, the following preprocessor syntax:</p>
<pre class="cpp">
<span class="preprocessor">#ifdef NOTYET</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="preprocessor">#endif</span>
<span class="preprocessor">#if defined (NOTYET)</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="preprocessor">#end if</span>
</pre>
<p>However, faced with unknown syntax like</p>
<pre class="cpp">
<span class="preprocessor">#if NOTYET</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="preprocessor">#endif</span>
</pre>
<p>QDoc will evaluate it as true by default, <i>unless</i> the preprocessor symbol is specified within the <code>falsehoods</code> variable entry:</p>
<pre class="cpp plain">
falsehoods = NOTYET
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#defines">defines</a>.</p>
<a name="generateindex-variable"></a><a name="generateindex"></a>
<h2 id="generateindex">generateindex</h2>
<p>The <code>generateindex</code> variable contains a boolean value that specifies whether to generate an index file when HTML documentation is generated.</p>
<p>By default, an index file is always generated with HTML documentation, so this variable is typically only used when disabling this feature (by setting the value to <code>false</code>) or when enabling index generation for the WebXML output (by setting the value to <code>true</code>).</p>
<a name="headerdirs-variable"></a><a name="headerdirs"></a>
<h2 id="headerdirs">headerdirs</h2>
<p>The <code>headerdirs</code> variable specifies the directories containing the header files associated with the <code>.cpp</code> source files used in the documentation.</p>
<pre class="cpp plain">
headerdirs = $QTDIR/src \
$QTDIR/extensions/activeqt \
$QTDIR/extensions/motif \
$QTDIR/tools/designer/src/lib/extension \
$QTDIR/tools/designer/src/lib/sdk \
$QTDIR/tools/designer/src/lib/uilib
</pre>
<p>When executed, the first thing QDoc will do is to read through the headers specified in the <a href="22-qdoc-configuration-generalvariables.html#headers"><code>headers</code></a> variable, and the ones located in the directories specified in the <code>headerdir</code> variable (including all subdirectories), building an internal structure of the classes and their functions.</p>
<p>Then it will read through the sources specified in the <a href="22-qdoc-configuration-generalvariables.html#sources-variable"><code>sources</code></a>, and the ones located in the directories specified in the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable"><code>sourcedirs</code></a> varible (including all subdirectories), merging the documentation with the structure it retrieved from the header files.</p>
<p>If both the <code>headers</code> and <code>headerdirs</code> variables are defined, QDoc will read through both, first <a href="22-qdoc-configuration-generalvariables.html#headers"><code>headers</code></a> then <code>headerdirs</code>.</p>
<p>In the specified directories, QDoc will only read the files with the <code>fileextensions</code> specified in the <a href="22-qdoc-configuration-generalvariables.html#headers-fileextensions"><code>headers.fileextensions</code></a> variable. The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". The files specified by <a href="22-qdoc-configuration-generalvariables.html#headers"><code>headers</code></a> will be read without taking into account their fileextensions.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#headers">headers</a> and <a href="22-qdoc-configuration-generalvariables.html#headers-fileextensions">headers.fileextensions</a>.</p>
<a name="headers-variable"></a><a name="headers"></a>
<h2 id="headers">headers</h2>
<p>The <code>headers</code> variable allows you to specify individual header files in addition to those located in the directories specified by the <a href="22-qdoc-configuration-generalvariables.html#headerdirs"><code>headerdirs</code></a> variable.</p>
<pre class="cpp plain">
headers = $QTDIR/src/gui/widgets/qlineedit.h \
$QTDIR/src/gui/widgets/qpushbutton.h
</pre>
<p>When processing the <code>headers</code> variable, QDoc behaves in the same way as it does when processing the <a href="22-qdoc-configuration-generalvariables.html#headerdirs"><code>headerdirs</code></a> variable. For more information, see the <a href="22-qdoc-configuration-generalvariables.html#headerdirs"><code>headerdirs</code></a> variable.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#headerdirs">headerdirs</a>.</p>
<a name="headers-fileextensions-variable"></a><a name="headers-fileextensions"></a>
<h2 id="headers-fileextensions">headers.fileextensions</h2>
<p>The <code>headers.fileextensions</code> variable specify the extension used by the headers.</p>
<p>When processing the header files specified in the <a href="22-qdoc-configuration-generalvariables.html#headerdirs"><code>headerdirs</code></a> variable, QDoc will only read the files with the fileextensions specified in the <code>headers.fileextensions</code> variable. In this way QDoc avoids spending time reading irrelevant files.</p>
<p>The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx.</p>
<p>The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:</p>
<pre class="cpp plain">
header.fileextensions += *.H
</pre>
<p><b>Warning:</b> The above assignment may not work as described.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#headerdirs">headerdirs</a>.</p>
<a name="imagedirs-variable"></a><a name="imagedirs"></a>
<h2 id="imagedirs">imagedirs</h2>
<p>The <code>imagedirs</code> variable specifies the directories containing the images used in the documentation.</p>
<p>The <a href="22-qdoc-configuration-generalvariables.html#images"><code>images</code></a> and <code>imagedirs</code> variables are used by the <a href="09-qdoc-commands-includingimages.html#image-command">\image</a> and <a href="09-qdoc-commands-includingimages.html#inlineimage-command">\inlineimage</a> commands. If both the <a href="22-qdoc-configuration-generalvariables.html#images"><code>images</code></a> and <code>imagedirs</code> variables are defined, QDoc will search in both. First in <a href="22-qdoc-configuration-generalvariables.html#images"><code>images</code></a>, then in <code>imagedirs</code>.</p>
<p>QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, <i>not</i> in subdirectories.</p>
<pre class="cpp plain">
imagedirs = $QTDIR/doc/src/images \
$QTDIR/examples
images = $QTDIR/doc/src/images/calculator-example.png
</pre>
<p>When processing</p>
<pre class="cpp plain">
\image calculator-example.png
</pre>
<p>QDoc will then see if there is a file called calculator-example.png listed as a value in the <code>images</code> variable. If there isn't, it will search in the <code>imagedirs</code> variable for:</p>
<pre class="cpp plain">
$QTDIR/doc/src/images/calculator-example.png
</pre>
<p>If the file doesn't exist, QDoc will look for a file called</p>
<pre class="cpp plain">
$QTDIR/examples/calculator-example.png
</pre>
<p>You can filter the images in an image directory using the <a href="22-qdoc-configuration-generalvariables.html#images-fileextensions"><code>images.fileextensions</code></a> variable. The general idea behind the <a href="22-qdoc-configuration-generalvariables.html#images-fileextensions"><code>images.fileextensions</code></a> variable is to enable different image format for different output format.</p>
<p><b>Warning:</b> The <a href="22-qdoc-configuration-generalvariables.html#images-fileextensions"><code>images.fileextensions</code></a> variable's functionality is preliminary since QDoc at this point only supports HTML.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#images">images</a> and <a href="22-qdoc-configuration-generalvariables.html#images-fileextensions">images.fileextensions</a>.</p>
<a name="images-variable"></a><a name="images"></a>
<h2 id="images">images</h2>
<p>The <code>images</code> variable allows you to specify individual image files in addition to those located in the directories specified by the <a href="22-qdoc-configuration-generalvariables.html#imagedirs"><code>imagedirs</code></a> variable.</p>
<pre class="cpp plain">
images = $QTDIR/doc/src/images/calculator-example.png
</pre>
<p>When processing the <code>images</code> variable, QDoc behaves in the same way as it does when processing the <a href="22-qdoc-configuration-generalvariables.html#imagedirs"><code>imagedirs</code></a> variable. For more information, see the <a href="22-qdoc-configuration-generalvariables.html#imagedirs"><code>imagedirs</code></a> variable.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#imagedirs">imagedirs</a> and <a href="22-qdoc-configuration-generalvariables.html#images-fileextensions">images.fileextensions</a>.</p>
<a name="images-fileextensions-variable"></a><a name="images-fileextensions"></a>
<h2 id="images-fileextensions">images.fileextensions</h2>
<p>The images.fileextensions variable filters the files within an image directory.</p>
<p>The variable's values (the extensions) are given as standard wildcard expressions. The general syntax is: <code>images.fileextensions.<i>format</i> = *.<i>extension</i></code>.</p>
<p>The idea is to enable different image format for different output format.</p>
<pre class="cpp plain">
images.fileextensions.HTML = *.png
images.fileextensions.LOUT = *.eps
</pre>
<p>Then, when processing the <a href="09-qdoc-commands-includingimages.html#image-command">\image</a> and <a href="09-qdoc-commands-includingimages.html#inlineimage-command">\inlineimage</a> commands, QDoc will only search for files with extensions specified in the variable containing the list of output formats.</p>
<p><b>Warning:</b> This is only a preliminary functionality since QDoc at this point only supports HTML.</p>
<p>The default extensions for HTML are *.png, *.jpg, *.jpeg, and *.gif.</p>
<p>You can add a file extension to the filter using '+='. For example:</p>
<pre class="cpp plain">
images.fileextensions.HTML += *.eps
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#imagedirs">imagedirs</a> and <a href="22-qdoc-configuration-generalvariables.html#images">images</a>.</p>
<a name="language-variable"></a><a name="language"></a>
<h2 id="language">language</h2>
<p>The <code>language</code> variable specifies the language of the source code that is used in the documentation.</p>
<p>Currently, C++ is the only language that QDoc understands. It is also the default language, and doesn't really need to be specified. However, a possible example of a language variable statement:</p>
<pre class="cpp plain">
language = Cpp
</pre>
<p>This identifies C++ as the language of the Qt source code.</p>
<a name="macro-variable"></a><a name="macro"></a>
<h2 id="macro">macro</h2>
<p>The <code>macro</code> variable is used to create your own simple QDoc commands. The syntax is <code>macro.<i>command</i> = <i>definition</i></code>, where the definition is written using QDoc syntax.</p>
<p>A macro variable can be restricted for use in one type of output generation. By appending <code>.HTML</code> to the macro name, for example, the macro is only used when generating HTML output. By appending <code>.DITAXML</code> to the macro name, the macro is only used when generating DITA XML.</p>
<pre class="cpp plain">
macro.gui = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"
</pre>
<p>The first macro defines the \gui command to render its argument using a bold font. The second macro defines the \raisedaster command to render a superscript asterisk, but only when generating HTML.</p>
<p>A macro can also take up to seven parameters:</p>
<pre class="cpp plain">
macro.hello = "Hello \1!"
</pre>
<p>Parameters are passed to macros the same way as to other commands:</p>
<pre class="cpp plain">
\hello World
</pre>
<p>When using more than one parameter, or when an argument contains whitespace, enclose each argument in braces:</p>
<pre class="cpp plain">
macro.verinfo = "\1 (version \2)"
</pre>
<pre class="cpp plain">
\verinfo {QFooBar} {1.0 beta}
</pre>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#alias-variable">alias</a>.</p>
<a name="manifestmeta-variable"></a><a name="manifestmeta"></a>
<h2 id="manifestmeta">manifestmeta</h2>
<p>The <code>manifestmeta</code> variable specifies additional meta-content for the example manifest files generated by QDoc.</p>
<p>See the <a href="26-qdoc-configuration-example-manifest-files.html#manifest-meta-content">Manifest Meta Content</a> section for more information.</p>
<a name="naturallanguage-variable"></a><a name="naturallanguage"></a>
<h2 id="naturallanguage">naturallanguage</h2>
<p>The <code>naturallanguage</code> variable specifies the natural language used for the documentation generated by qdoc.</p>
<pre class="cpp plain">
naturallanguage = zh-Hans
</pre>
<p>By default, the natural language is <code>en</code> for compatibility with legacy documentation.</p>
<p>qdoc will add the natural language information to the HTML it generates, using the <code>lang</code> and <code>xml:lang</code> attributes.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#sourceencoding-variable">sourceencoding</a>, <a href="22-qdoc-configuration-generalvariables.html#outputencoding-variable">outputencoding</a>, <a href="http://www.w3.org/TR/xhtml1/#C_7">C.7. The lang and xml:lang Attributes</a> and <a href="http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290">Best Practice 13: Using Hans and Hant codes</a>.</p>
<a name="outputdir-variable"></a><a name="outputdir"></a>
<h2 id="outputdir">outputdir</h2>
<p>The <code>outputdir</code> variable specifies the directory where QDoc will put the generated documentation.</p>
<pre class="cpp plain">
outputdir = $QTDIR/doc/html
</pre>
<p>locates the generated Qt reference documentation in $QTDIR/doc/html. For example, the documentation of the <a href="../qtwidgets/qwidget.html">QWidget</a> class is located in</p>
<pre class="cpp plain">
$QTDIR/doc/html/qwidget.html
</pre>
<p>The associated images will be put in an <code>images</code> subdirectory.</p>
<p><b>Warning:</b> When running QDoc multiple times using the same output directory, all files from the previous run will be lost.</p>
<a name="outputencoding-variable"></a><a name="outputencoding"></a>
<h2 id="outputencoding">outputencoding</h2>
<p>The <code>outputencoding</code> variable specifies the encoding used for the documentation generated by qdoc.</p>
<pre class="cpp plain">
outputencoding = UTF-8
</pre>
<p>By default, the output encoding is <code>ISO-8859-1</code> (Latin1) for compatibility with legacy documentation. When generating documentation for some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required.</p>
<p>qdoc will encode HTML using this encoding and generate the correct declarations to indicate to browsers which encoding is being used. The <a href="22-qdoc-configuration-generalvariables.html#naturallanguage">naturallanguage</a> configuration variable should also be specified to provide browsers with a complete set of character encoding and language information.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#outputencoding">outputencoding</a> and <a href="22-qdoc-configuration-generalvariables.html#naturallanguage">naturallanguage</a>.</p>
<a name="outputformats-variable"></a><a name="outputformats"></a>
<h2 id="outputformats">outputformats</h2>
<p>The <code>outputformats</code> variable specifies the format of the generated documentation.</p>
<p>Currently, QDoc only supports the HTML format. It is also the default format, and doesn't need to be specified.</p>
<a name="outputprefixes-variable"></a><a name="outputprefixes"></a>
<h2 id="outputprefixes">outputprefixes</h2>
<p>The <code>outputprefixes</code> variable specifies a mapping between types of files and the prefixes to prepend to the HTML file names in the generated documentation.</p>
<pre class="cpp plain">
outputprefixes = QML JS
outputprefixes.QML = uicomponents-
outputprefixes.JS = uicomponents-
</pre>
<p>By default, files containing the API documentation for QML types are prefixed with "qml-", and javaScript types with "js-". In the above example, the prefix <code>"uicomponents"</code> is used instead for both.</p>
<p>The output prefix is applied to file names for documentation on QML and JS types.</p>
<a name="outputsuffixes-variable"></a><a name="outputsuffixes"></a>
<h2 id="outputsuffixes">outputsuffixes</h2>
<p>The <code>outputsuffixes</code> variable specifies a mapping between types of files and module name suffixes to append to the HTML file names.</p>
<pre class="cpp plain">
outputsuffixes = QML
outputsuffixes.QML = -tp
</pre>
<p>Given a QML module name <i>FooBar</i> and the default <a href="22-qdoc-configuration-generalvariables.html#outputprefixes-variable">output prefix</a> ("qml-"), the file name of the generated HTML page for a QML type <i>FooWidget</i> would be <code>qml-foobar-tp-foowidget.html</code>.</p>
<p>By default, no suffix is used. The output suffix, if defined, is applied to file names for documentation on QML and JS types, and their respective module pages.</p>
<p>The <code>outputsuffixes</code> variable was introduced in QDoc 5.6.</p>
<a name="qhp-variable"></a><a name="qhp"></a>
<h2 id="qhp">qhp</h2>
<p>The <code>qhp</code> variable is used to define the information to be written out to Qt Help Project (<code>qhp</code>) files.</p>
<p>See the <a href="22-creating-help-project-files.html">Creating Help Project Files</a> chapter for information about this process.</p>
<a name="sourcedirs-variable"></a><a name="sourcedirs"></a>
<h2 id="sourcedirs">sourcedirs</h2>
<p>The <code>sourcedirs</code> variable specifies the directories containing the <code>.cpp</code> or <code>.qdoc</code> files used in the documentation.</p>
<pre class="cpp plain">
sourcedirs += .. \
../../../examples/gui/doc/src
</pre>
<p>When executed, the first thing QDoc will do is to read through the headers specified in the <a href="10-qdoc-commands-tablesandlists.html#header-command"><code>header</code></a> variable, and the ones located in the directories specified in the <code>headerdir</code> variable (including all subdirectories), building an internal structure of the classes and their functions.</p>
<p>Then it will read through the sources specified in the <a href="22-qdoc-configuration-generalvariables.html#sources"><code>sources</code></a>, and the ones located in the directories specified in the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs"><code>sourcedirs</code></a> variable (including all subdirectories), merging the documentation with the structure it retrieved from the header files.</p>
<p>If both the <code>sources</code> and <code>sourcedirs</code> variables are defined, QDoc will read through both, first <a href="22-qdoc-configuration-generalvariables.html#sources"><code>sources</code></a> then <code>sourcedirs</code>.</p>
<p>In the specified directories, QDoc will only read the files with the <code>fileextensions</code> specified in the <a href="22-qdoc-configuration-generalvariables.html#sources-fileextensions"><code>sources.fileextensions</code></a> variable. The default extensions are *.c++, *.cc, *.cpp and *.cxx. The files specified by <a href="22-qdoc-configuration-generalvariables.html#sources"><code>sources</code></a> will be read independent of their fileextensions.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#sources-variable">sources</a> and <a href="22-qdoc-configuration-generalvariables.html#sources-fileextensions-variable">sources.fileextensions</a>.</p>
<a name="sourceencoding-variable"></a><a name="sourceencoding"></a>
<h2 id="sourceencoding">sourceencoding</h2>
<p>The <code>sourceencoding</code> variable specifies the encoding used for the source code and documentation.</p>
<pre class="cpp plain">
sourceencoding = UTF-8
</pre>
<p>By default, the source encoding is <code>ISO-8859-1</code> (Latin1) for compatibility with legacy documentation. For some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required.</p>
<p>Although qdoc will use the encoding to read source and documentation files, limitations of C++ compilers may prevent you from using non-ASCII characters in source code comments. In cases like these, it is possible to write API documentation completely in documentation files.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#naturallanguage-variable">naturallanguage</a> and <a href="22-qdoc-configuration-generalvariables.html#outputencoding-variable">outputencoding</a>.</p>
<a name="sources-variable"></a><a name="sources"></a>
<h2 id="sources">sources</h2>
<p>The <code>sources</code> variable allows you to specify individual source files in addition to those located in the directories specified by the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable">sourcedirs</a> variable.</p>
<pre class="cpp plain">
sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
$QTDIR/src/gui/widgets/qpushbutton.cpp
</pre>
<p>When processing the <code>sources</code> variable, QDoc behaves in the same way as it does when processing the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable">sourcedirs</a> variable. For more information, see the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable">sourcedirs</a> variable.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable">sourcedirs</a>.</p>
<a name="sources-fileextensions-variable"></a><a name="sources-fileextensions"></a>
<h2 id="sources-fileextensions">sources.fileextensions</h2>
<p>The <code>sources.fileextensions</code> variable filters the files within a source directory.</p>
<p>When processing the source files specified in the <a href="22-qdoc-configuration-generalvariables.html#sourcedirs"><code>sourcedirs</code></a> variable, QDoc will only read the files with the fileextensions specified in the <code>sources.fileextensions</code> variable. In this way QDoc avoid spending time reading irrelevant files.</p>
<p>The default extensions are *.c++, *.cc, *.cpp and *.cxx.</p>
<p>The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:</p>
<pre class="cpp plain">
sources.fileextensions += *.CC
</pre>
<p><b>Warning:</b> The above assignment may not work as described.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#sourcedirs-variable">sourcedirs</a> and <a href="22-qdoc-configuration-generalvariables.html#sources-variable">(sources-variable}</a> {sources}.</p>
<a name="spurious-variable"></a><a name="spurious"></a>
<h2 id="spurious">spurious</h2>
<p>The <code>spurious</code> variable excludes specified QDoc warnings from the output. The warnings are specified using standard wildcard expressions.</p>
<pre class="cpp plain">
spurious = "Cannot find .*" \
"Missing .*"
</pre>
<p>makes sure that warnings matching either of these expressions, will not be part of the output when running QDoc. For example would the following warning be omitted from the output:</p>
<pre class="cpp plain">
src/opengl/qgl_mac.cpp:156: Missing parameter name
</pre>
<a name="syntaxhighlighting"></a><a name="syntaxhighlighting"></a>
<h2 id="syntaxhighlighting">syntaxhighlighting</h2>
<p>The <code>syntaxhighlighting</code> variable specifies whether QDoc should perform syntax highlighting on source code quoted in the documentation it generates.</p>
<pre class="cpp plain">
syntaxhighlighting = true
</pre>
<p>will enable syntax highlighting for all supported programming languages.</p>
<a name="tabsize-variable"></a><a name="tabsize"></a>
<h2 id="tabsize">tabsize</h2>
<p>The <code>tabsize</code> variable defines the size of a tab character.</p>
<pre class="cpp plain">
tabsize = 4
</pre>
<p>will give the tab character the size of 4 spaces. The default value of the variable is 8, and doesn't need to be specified.</p>
<a name="tagfile-variable"></a><a name="tagfile"></a>
<h2 id="tagfile">tagfile</h2>
<p>The <code>tagfile</code> variable specifies the Doxygen tag file to be written when HTML is generated.</p>
<a name="version-variable"></a><a name="version"></a>
<h2 id="version">version</h2>
<p>The <code>version</code> variable specifies the version number of the documented software.</p>
<pre class="cpp plain">
version = 5.6.0
</pre>
<p>When a version number is specified (using the <code><a href="22-qdoc-configuration-generalvariables.html#version">version</a></code> or <code><a href="22-qdoc-configuration-generalvariables.html#versionsym">versionsym</a></code> variables in a <code>.qdocconf</code> file), it is accessible through the corresponding \version command for use in the documentation.</p>
<p><b>Warning:</b> The \version command's functionality is not fully implemented; currently it only works within raw HTML code.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#versionsym">versionsym</a>.</p>
<a name="versionsym-variable"></a><a name="versionsym"></a>
<h2 id="versionsym">versionsym</h2>
<p>The <code>versionsym</code> variable specifies a C++ preprocessor symbol that defines the version number of the documented software.</p>
<pre class="cpp plain">
versionsym = QT_VERSION_STR
</pre>
<p><a href="../qtcore/qtglobal.html#QT_VERSION_STR">QT_VERSION_STR</a> is defined in qglobal.h as follows</p>
<pre class="cpp plain">
#define QT_VERSION_STR "4.0.1"
</pre>
<p>When a version number is specified (using the <code><a href="22-qdoc-configuration-generalvariables.html#version">version</a></code> or <code><a href="22-qdoc-configuration-generalvariables.html#versionsym">versionsym</a></code> variables in a <code>.qdocconf</code> file), it is accessible through the corresponding \version command for use in the documentation.</p>
<p><b>Warning:</b> The \version command's functionality is not fully implemented. Currently, it only works within raw HTML code.</p>
<p>See also <a href="22-qdoc-configuration-generalvariables.html#version">\version</a>.</p>
</div>
<!-- @@@22-qdoc-configuration-generalvariables.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="21-0-qdoc-configuration.html">The QDoc Configuration File</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="22-creating-help-project-files.html">Creating Help Project Files</a>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|