Macros

Use the macro variable to create your own simple QDoc commands.

Macros are useful for:

• Including recurring text, such as formatted text snippets, into documentation.
• Pulling in information, such as version strings, from the build system into .documentation.
• Maintaining a single location for strings that are likely to change in the future, such as product names.
• Making sure that a term or product name is used consistently.
• Styling the generated documentation by using HTML and DocBook elements, such as forced line breaks and special characters.
• Using tabs to show examples of content for different programming languages, operating systems, or tools, for example.

Global Macros

For a set of predefined global macros that you can use in all documentation projects and their current values, see /qtbase/doc/global/macros.qdocconf and /qtbase/doc/global/htmltabs.qdocconf. They have macros that include:

• CMake Text Snippets
• HTML and DocBook Formatting
• Product Names
• Product Versions
• Tabbed Content
• Links to YouTube content
• Miscellaneous Macros

Qt Online Installer copies the macros files to your Qt installation folder, so you can use the macros even if you build the documentation using QDoc from an installed Qt (as opposed to building QDoc yourself from sources).

Adding Macros

You can add macros for a particular documentation project in the .qdocconf file of the project or any .qdocconf file that you include into it. If the macro could be useful in more than one documentation project, add it to the global macros file.

For more information about the macro syntax and options, see macro.

Using Macros

You can use macros in the same way as the built-in QDoc commands in:

• Code source files, in documentation comments (.cpp, .qml)
• Documentation source files (.qdoc, .qdocinc)

For example:

 \QOI copies the macros files to your Qt installation folder.

Obsolete Macros

The global macros file contains the following obsolete macros for compatibility with older documentation sets.