|
Packit Service |
50c9f2 |
/******************************************************************************
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Copyright (C) 1997-2015 by Dimitri van Heesch.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Permission to use, copy, modify, and distribute this software and its
|
|
Packit Service |
50c9f2 |
* documentation under the terms of the GNU General Public License is hereby
|
|
Packit Service |
50c9f2 |
* granted. No representations are made about the suitability of this software
|
|
Packit Service |
50c9f2 |
* for any purpose. It is provided "as is" without express or implied warranty.
|
|
Packit Service |
50c9f2 |
* See the GNU General Public License for more details.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Documents produced by Doxygen are derivative works derived from the
|
|
Packit Service |
50c9f2 |
* input used in their production; they are not affected by this license.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
/*! \page markdown Markdown support
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[TOC]
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[Markdown] support
|
|
Packit Service |
50c9f2 |
was introduced in doxygen version 1.8.0. It is a plain text formatting
|
|
Packit Service |
50c9f2 |
syntax written by John Gruber, with the following underlying design goal:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
> The design goal for Markdown's formatting syntax is to
|
|
Packit Service |
50c9f2 |
> make it as readable as possible. The idea is that a Markdown-formatted
|
|
Packit Service |
50c9f2 |
> document should be publishable as-is, as plain text, without
|
|
Packit Service |
50c9f2 |
> looking like it's been marked up with tags or formatting instructions.
|
|
Packit Service |
50c9f2 |
> While Markdown's syntax has been influenced by several existing
|
|
Packit Service |
50c9f2 |
> text-to-HTML filters, the single biggest source of inspiration
|
|
Packit Service |
50c9f2 |
> for Markdown's syntax is the format of plain text email.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In the \ref markdown_std "next section" the standard Markdown features
|
|
Packit Service |
50c9f2 |
are briefly discussed. The reader is referred to the [Markdown site][markdown]
|
|
Packit Service |
50c9f2 |
for more details.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Some enhancements were made, for instance [PHP Markdown Extra][mdextra], and
|
|
Packit Service |
50c9f2 |
[GitHub flavored Markdown][github]. The section \ref markdown_extra discusses
|
|
Packit Service |
50c9f2 |
the extensions that doxygen supports.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Finally section \ref markdown_dox discusses some specifics for doxygen's
|
|
Packit Service |
50c9f2 |
implementation of the Markdown standard.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[markdown]: http://daringfireball.net/projects/markdown/
|
|
Packit Service |
50c9f2 |
[mdextra]: https://michelf.ca/projects/php-markdown/extra/
|
|
Packit Service |
50c9f2 |
[github]: https://github.github.com/github-flavored-markdown/
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section markdown_std Standard Markdown
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_para Paragraphs
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Even before doxygen had Markdown support it supported the same way
|
|
Packit Service |
50c9f2 |
of paragraph handling as Markdown: to make a paragraph you just separate
|
|
Packit Service |
50c9f2 |
consecutive lines of text by one or more blank lines.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
An example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Here is text for one paragraph.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
We continue with more text in another paragraph.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_headers Headers
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Just like Markdown, doxygen supports two types of headers
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Level 1 or 2 headers can be made as the follows
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This is a level 1 header
|
|
Packit Service |
50c9f2 |
========================
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This is a level 2 header
|
|
Packit Service |
50c9f2 |
------------------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A header is followed by a line containing only ='s or -'s.
|
|
Packit Service |
50c9f2 |
Note that the exact amount of ='s or -'s is not important as long as
|
|
Packit Service |
50c9f2 |
there are at least two.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Alternatively, you can use #'s at the start of a line to make a header.
|
|
Packit Service |
50c9f2 |
The number of #'s at the start of the line determines the level (up to 6 levels are supported).
|
|
Packit Service |
50c9f2 |
You can end a header by any number of #'s.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Here is an example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
# This is a level 1 header
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
### This is level 3 header #######
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_blockquotes Block quotes
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Block quotes can be created by starting each line with one or more >'s,
|
|
Packit Service |
50c9f2 |
similar to what is used in text-only emails.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
> This is a block quote
|
|
Packit Service |
50c9f2 |
> spanning multiple lines
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Lists and code blocks (see below) can appear inside a quote block.
|
|
Packit Service |
50c9f2 |
Quote blocks can also be nested.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that doxygen requires that you put a space after the (last) > character
|
|
Packit Service |
50c9f2 |
to avoid false positives, i.e. when writing
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
0 if OK\n
|
|
Packit Service |
50c9f2 |
>1 if NOK
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
the second line will not be seen as a block quote.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_lists Lists
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Simple bullet lists can be made by starting a line with -, +, or *.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
- Item 1
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
More text for this item.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
- Item 2
|
|
Packit Service |
50c9f2 |
+ nested list item.
|
|
Packit Service |
50c9f2 |
+ another nested item.
|
|
Packit Service |
50c9f2 |
- Item 3
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
List items can span multiple paragraphs (if each paragraph starts with
|
|
Packit Service |
50c9f2 |
the proper indentation) and lists can be nested.
|
|
Packit Service |
50c9f2 |
You can also make a numbered list like so
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
1. First item.
|
|
Packit Service |
50c9f2 |
2. Second item.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Make sure to also read \ref mddox_lists for doxygen specifics.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_codeblock Code Blocks
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Preformatted verbatim blocks can be created by indenting
|
|
Packit Service |
50c9f2 |
each line in a block of text by at least 4 extra spaces
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This a normal paragraph
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This is a code block
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
We continue with a normal paragraph again.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen will remove the mandatory indentation from the code block.
|
|
Packit Service |
50c9f2 |
Note that you cannot start a code block in the middle of a paragraph
|
|
Packit Service |
50c9f2 |
(i.e. the line preceding the code block must be empty).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
See section \ref mddox_code_blocks for more info how doxygen handles
|
|
Packit Service |
50c9f2 |
indentation as this is slightly different than standard Markdown.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_rulers Horizontal Rulers
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A horizontal ruler will be produced for lines containing at least three or more
|
|
Packit Service |
50c9f2 |
hyphens, asterisks, or underscores. The line may also include any amount of whitespace.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Examples:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
- - -
|
|
Packit Service |
50c9f2 |
______
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that using asterisks in comment blocks does not work. See
|
|
Packit Service |
50c9f2 |
\ref mddox_stars for details.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_emphasis Emphasis
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To emphasize a text fragment you start and end the fragment with an underscore or star.
|
|
Packit Service |
50c9f2 |
Using two stars or underscores will produce strong emphasis.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Examples:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
* *single asterisks*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* _single underscores_
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* **double asterisks**
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* __double underscores__
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
See section \ref mddox_emph_spans for more info how doxygen handles
|
|
Packit Service |
50c9f2 |
emphasis spans slightly different than standard Markdown.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_codespan code spans
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To indicate a span of code, you should wrap it in backticks (`). Unlike code blocks,
|
|
Packit Service |
50c9f2 |
code spans appear inline in a paragraph. An example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Use the `printf()` function.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To show a literal backtick inside a code span use double backticks, i.e.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To assign the output of command `ls` to `var` use ``var=`ls```.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
See section \ref mddox_code_spans for more info how doxygen handles
|
|
Packit Service |
50c9f2 |
code spans slightly different than standard Markdown.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_links Links
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen supports both styles of make links defined by Markdown: *inline* and *reference*.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For both styles the link definition starts with the link text delimited by [square
|
|
Packit Service |
50c9f2 |
brackets].
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsubsection md_inlinelinks Inline Links
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For an inline link the link text is followed by a URL and an optional link title which
|
|
Packit Service |
50c9f2 |
together are enclosed in a set of regular parenthesis.
|
|
Packit Service |
50c9f2 |
The link title itself is surrounded by quotes.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Examples:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[The link text](http://example.net/)
|
|
Packit Service |
50c9f2 |
[The link text](http://example.net/ "Link title")
|
|
Packit Service |
50c9f2 |
[The link text](/relative/path/to/index.html "Link title")
|
|
Packit Service |
50c9f2 |
[The link text](somefile.html)
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In addition doxygen provides a similar way to link a documented entity:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[The link text](@ref MyClass)
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsubsection md_reflinks Reference Links
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Instead of putting the URL inline, you can also define the link separately
|
|
Packit Service |
50c9f2 |
and then refer to it from within the text.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The link definition looks as follows:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[link name]: http://www.example.com "Optional title"
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Instead of double quotes also single quotes or parenthesis can
|
|
Packit Service |
50c9f2 |
be used for the title part.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Once defined, the link looks as follows
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[link text][link name]
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If the link text and name are the same, also
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[link name][]
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
or even
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[link name]
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
can be used to refer to the link.
|
|
Packit Service |
50c9f2 |
Note that the link name matching is not case sensitive
|
|
Packit Service |
50c9f2 |
as is shown in the following example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
I get 10 times more traffic from [Google] than from
|
|
Packit Service |
50c9f2 |
[Yahoo] or [MSN].
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[google]: http://google.com/ "Google"
|
|
Packit Service |
50c9f2 |
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
|
Packit Service |
50c9f2 |
[msn]: http://search.msn.com/ "MSN Search"
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Link definitions will not be visible in the output.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Like for inline links doxygen also supports \@ref inside a link definition:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[myclass]: @ref MyClass "My class"
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_images Images
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Markdown syntax for images is similar to that for links.
|
|
Packit Service |
50c9f2 |
The only difference is an additional ! before the link text.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Examples:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
![Caption text](/path/to/img.jpg)
|
|
Packit Service |
50c9f2 |
![Caption text](/path/to/img.jpg "Image title")
|
|
Packit Service |
50c9f2 |
![Caption text][img def]
|
|
Packit Service |
50c9f2 |
![img def]
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[img def]: /path/to/img.jpg "Optional Title"
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Also here you can use \@ref to link to an image:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
![Caption text](@ref image.png)
|
|
Packit Service |
50c9f2 |
![img def]
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[img def]: @ref image.png "Caption text"
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The caption text is optional.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_autolink Automatic Linking
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To create a link to an URL or e-mail address Markdown supports the following
|
|
Packit Service |
50c9f2 |
syntax:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
<http://www.example.com>
|
|
Packit Service |
50c9f2 |
<https://www.example.com>
|
|
Packit Service |
50c9f2 |
<ftp://www.example.com>
|
|
Packit Service |
50c9f2 |
<mailto:address@example.com>
|
|
Packit Service |
50c9f2 |
<address@example.com>
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that doxygen will also produce the links without the angle brackets.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section markdown_extra Markdown Extensions
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_toc Table of Contents
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen supports a special link marker `[TOC]` which can be placed in a page
|
|
Packit Service |
50c9f2 |
to produce a table of contents at the start of the page, listing all sections.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that using `[TOC]` is the same as using a
|
|
Packit Service |
50c9f2 |
\ref cmdtableofcontents "\\tableofcontents" command.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_tables Tables
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Of the features defined by "Markdown Extra" is support for
|
|
Packit Service |
50c9f2 |
simple tables:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A table consists of a header line, a separator line, and at least one
|
|
Packit Service |
50c9f2 |
row line. Table columns are separated by the pipe (|) character.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Here is an example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
First Header | Second Header
|
|
Packit Service |
50c9f2 |
------------- | -------------
|
|
Packit Service |
50c9f2 |
Content Cell | Content Cell
|
|
Packit Service |
50c9f2 |
Content Cell | Content Cell
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
which will produce the following table:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
First Header | Second Header
|
|
Packit Service |
50c9f2 |
------------- | -------------
|
|
Packit Service |
50c9f2 |
Content Cell | Content Cell
|
|
Packit Service |
50c9f2 |
Content Cell | Content Cell
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Column alignment can be controlled via one or two colons
|
|
Packit Service |
50c9f2 |
at the header separator line:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
| Right | Center | Left |
|
|
Packit Service |
50c9f2 |
| ----: | :----: | :---- |
|
|
Packit Service |
50c9f2 |
| 10 | 10 | 10 |
|
|
Packit Service |
50c9f2 |
| 1000 | 1000 | 1000 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
which will look as follows:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
| Right | Center | Left |
|
|
Packit Service |
50c9f2 |
| ----: | :----: | :---- |
|
|
Packit Service |
50c9f2 |
| 10 | 10 | 10 |
|
|
Packit Service |
50c9f2 |
| 1000 | 1000 | 1000 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Additionally, column and row spans are supported. Using a caret ("^")
|
|
Packit Service |
50c9f2 |
in a cell indicates that the cell above should span rows. Sequences
|
|
Packit Service |
50c9f2 |
of carets may be used for any number of row spans. For example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
| Right | Center | Left |
|
|
Packit Service |
50c9f2 |
| ----: | :----: | :---- |
|
|
Packit Service |
50c9f2 |
| 10 | 10 | 10 |
|
|
Packit Service |
50c9f2 |
| ^ | 1000 | 1000 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
which will look as follows:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
| Right | Center | Left |
|
|
Packit Service |
50c9f2 |
| ----: | :----: | :---- |
|
|
Packit Service |
50c9f2 |
| 10 | 10 | 10 |
|
|
Packit Service |
50c9f2 |
| ^ | 1000 | 1000 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Column spans are supported by means of directly adjacent vertical bars
|
|
Packit Service |
50c9f2 |
("|"). Each additional vertical bar indicates an additional column to
|
|
Packit Service |
50c9f2 |
be spanned. To put it another way, a single vertical bar indicates a
|
|
Packit Service |
50c9f2 |
single column span, two vertical bars indicates a 2 columns span, and
|
|
Packit Service |
50c9f2 |
so on. For example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
| Right | Center | Left |
|
|
Packit Service |
50c9f2 |
| ----: | :----: | :---- |
|
|
Packit Service |
50c9f2 |
| 10 | 10 | 10 |
|
|
Packit Service |
50c9f2 |
| 1000 |||
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
which will look as follows:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
| Right | Center | Left |
|
|
Packit Service |
50c9f2 |
| ----: | :----: | :---- |
|
|
Packit Service |
50c9f2 |
| 10 | 10 | 10 |
|
|
Packit Service |
50c9f2 |
| 1000 |||
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For more complex tables in doxygen please have a look at: \ref tables
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_fenced Fenced Code Blocks
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Another feature defined by "Markdown Extra" is support for
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
fenced code blocks:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A fenced code block does not require indentation, and is
|
|
Packit Service |
50c9f2 |
defined by a pair of "fence lines". Such a line consists of 3 or
|
|
Packit Service |
50c9f2 |
more tilde (~) characters on a line. The end of the block should have the
|
|
Packit Service |
50c9f2 |
same number of tildes. Here is an example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This is a paragraph introducing:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~~~~~~~~~
|
|
Packit Service |
50c9f2 |
a one-line code block
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~~~~~~~~~
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
By default the output is the same as for a normal code block.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For languages supported by doxygen you can also make the code block
|
|
Packit Service |
50c9f2 |
appear with syntax highlighting. To do so you need to
|
|
Packit Service |
50c9f2 |
indicate the typical file extension that corresponds to the
|
|
Packit Service |
50c9f2 |
programming language after the opening fence. For highlighting according
|
|
Packit Service |
50c9f2 |
to the Python language for instance, you would need to write the following:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~{.py}
|
|
Packit Service |
50c9f2 |
# A class
|
|
Packit Service |
50c9f2 |
class Dummy:
|
|
Packit Service |
50c9f2 |
pass
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
which will produce:
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~{.py}
|
|
Packit Service |
50c9f2 |
# A class
|
|
Packit Service |
50c9f2 |
class Dummy:
|
|
Packit Service |
50c9f2 |
pass
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
and for C you would write:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~~~{.c}
|
|
Packit Service |
50c9f2 |
int func(int a,int b) { return a*b; }
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~~~
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
which will produce:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~~~{.c}
|
|
Packit Service |
50c9f2 |
int func(int a,int b) { return a*b; }
|
|
Packit Service |
50c9f2 |
~~~~~~~~~~~~~~~
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The curly braces and dot are optional by the way.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Another way to denote fenced code blocks is to use 3 or more backticks (```):
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
```
|
|
Packit Service |
50c9f2 |
also a fenced code block
|
|
Packit Service |
50c9f2 |
```
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_header_id Header Id Attributes
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Standard Markdown has no support for labeling headers, which
|
|
Packit Service |
50c9f2 |
is a problem if you want to link to a section.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
PHP Markdown Extra allows you to label a header by adding
|
|
Packit Service |
50c9f2 |
the following to the header
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Header 1 {#labelid}
|
|
Packit Service |
50c9f2 |
========
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
## Header 2 ## {#labelid2}
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To link to a section in the same comment block you can use
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[Link text](#labelid)
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
to link to a section in general, doxygen allows you to use \@ref
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
[Link text](@ref labelid)
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note this only works for the headers of level 1 to 4.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section markdown_dox Doxygen specifics
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Even though doxygen tries to following the Markdown standard as closely as
|
|
Packit Service |
50c9f2 |
possible, there are couple of deviation and doxygen specifics additions.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_page_header Including Markdown files as pages
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen can process files with Markdown formatting.
|
|
Packit Service |
50c9f2 |
For this to work the extension for such a file should
|
|
Packit Service |
50c9f2 |
be `.md` or `.markdown` (see
|
|
Packit Service |
50c9f2 |
\ref cfg_extension_mapping "EXTENSION_MAPPING" if your Markdown files have
|
|
Packit Service |
50c9f2 |
a different extension, and use `md` as the name of the parser).
|
|
Packit Service |
50c9f2 |
Each file is converted to a page (see the \ref cmdpage "page" command for
|
|
Packit Service |
50c9f2 |
details).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
By default the name and title of the page are derived from the file name.
|
|
Packit Service |
50c9f2 |
If the file starts with a level 1 header however, it is used as the title
|
|
Packit Service |
50c9f2 |
of the page. If you specify a label for the
|
|
Packit Service |
50c9f2 |
header (as shown in \ref md_header_id) doxygen will use that as the
|
|
Packit Service |
50c9f2 |
page name.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If the label is called `index` or `mainpage` doxygen will put the
|
|
Packit Service |
50c9f2 |
documentation on the front page (`index.html`).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Here is an example of a file `README.md` that will appear as the main page
|
|
Packit Service |
50c9f2 |
when processed by doxygen:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
My Main Page {#mainpage}
|
|
Packit Service |
50c9f2 |
============
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Documentation that will appear on the main page
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If a page has a label you can link to it using \ref cmdref "\@ref" as
|
|
Packit Service |
50c9f2 |
is shown above. To refer to a markdown page without
|
|
Packit Service |
50c9f2 |
such label you can simple use the file name of the page, e.g.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
See [the other page](other.md) for more info.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection md_html_blocks Treatment of HTML blocks
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Markdown is quite strict in the way it processes block-level HTML:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
> block-level HTML elements — e.g.
|
|
Packit Service |
50c9f2 |
> `
|
|
Packit Service |
50c9f2 |
> must be separated from surrounding content by blank lines,
|
|
Packit Service |
50c9f2 |
> and the start and end tags of the block should not be indented
|
|
Packit Service |
50c9f2 |
> with tabs or spaces.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen does not have this requirement, and will also process
|
|
Packit Service |
50c9f2 |
Markdown formatting inside such HTML blocks. The only exception is
|
|
Packit Service |
50c9f2 |
`` blocks, which are passed untouched (handy for ASCII art).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen will not process Markdown formatting inside verbatim or code blocks,
|
|
Packit Service |
50c9f2 |
and in other sections that need to be processed without changes
|
|
Packit Service |
50c9f2 |
(for instance formulas or inline dot graphs).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection mddox_code_blocks Code Block Indentation
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Markdown allows both a single tab or 4 spaces to start a code block.
|
|
Packit Service |
50c9f2 |
Since doxygen already replaces tabs by spaces before doing Markdown
|
|
Packit Service |
50c9f2 |
processing, the effect will only be same if TAB_SIZE in the config file
|
|
Packit Service |
50c9f2 |
has been set to 4. When it is set to a higher value spaces will be
|
|
Packit Service |
50c9f2 |
present in the code block. A lower value will prevent a single tab to be
|
|
Packit Service |
50c9f2 |
interpreted as the start of a code block.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
With Markdown any block that is indented by 4 spaces (and 8 spaces
|
|
Packit Service |
50c9f2 |
inside lists) is treated as a code block. This indentation amount
|
|
Packit Service |
50c9f2 |
is absolute, i.e. counting from the start of the line.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Since doxygen comments can appear at any indentation level
|
|
Packit Service |
50c9f2 |
that is required by the programming language, it
|
|
Packit Service |
50c9f2 |
uses a relative indentation instead. The amount of
|
|
Packit Service |
50c9f2 |
indentation is counted relative to the preceding paragraph.
|
|
Packit Service |
50c9f2 |
In case there is no preceding paragraph (i.e. you want to start with a
|
|
Packit Service |
50c9f2 |
code block), the minimal amount of indentation of the whole comment block
|
|
Packit Service |
50c9f2 |
is used as a reference.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In most cases this difference does not result in different output.
|
|
Packit Service |
50c9f2 |
Only if you play with the indentation of paragraphs the difference
|
|
Packit Service |
50c9f2 |
is noticeable:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
text
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
text
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
text
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
code
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In this case Markdown will put the word code in a code block,
|
|
Packit Service |
50c9f2 |
whereas doxygen will treat it as normal text, since although the absolute
|
|
Packit Service |
50c9f2 |
indentation is 4, the indentation with respect to the previous paragraph
|
|
Packit Service |
50c9f2 |
is only 1.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that list markers are not counted when determining the
|
|
Packit Service |
50c9f2 |
relative indent:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
1. Item1
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
More text for item1
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
2. Item2
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Code block for item2
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For Item1 the indentation is 4 (when treating the list marker as whitespace),
|
|
Packit Service |
50c9f2 |
so the next paragraph "More text..." starts at the same indentation level
|
|
Packit Service |
50c9f2 |
and is therefore not seen as a code block.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection mddox_emph_spans Emphasis limits
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Unlike standard Markdown, doxygen will not touch internal underscores or
|
|
Packit Service |
50c9f2 |
stars, so the following will appear as-is:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
a_nice_identifier
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Furthermore, a `*` or `_` only starts an emphasis if
|
|
Packit Service |
50c9f2 |
- it is followed by an alphanumerical character, and
|
|
Packit Service |
50c9f2 |
- it is preceded by a space, newline, or one the following characters `<{([,:;`
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
An emphasis ends if
|
|
Packit Service |
50c9f2 |
- it is not followed by an alphanumerical character, and
|
|
Packit Service |
50c9f2 |
- it is not preceded by a space, newline, or one the following characters `({[<=+-\@`
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Lastly, the span of the emphasis is limited to a single paragraph.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection mddox_code_spans Code Spans Limits
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that unlike standard Markdown, doxygen leaves the following untouched.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A `cool' word in a `nice' sentence.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
In other words; a single quote cancels the special treatment of a code span
|
|
Packit Service |
50c9f2 |
wrapped in a pair of backtick characters. This extra restriction was
|
|
Packit Service |
50c9f2 |
added for backward compatibility reasons.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection mddox_lists Lists Extensions
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
With Markdown two lists separated by an empty line are joined together into
|
|
Packit Service |
50c9f2 |
a single list which can be rather unexpected and many people consider it to
|
|
Packit Service |
50c9f2 |
be a bug. Doxygen, however, will make two separate lists as you would expect.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
- Item1 of list 1
|
|
Packit Service |
50c9f2 |
- Item2 of list 1
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
1. Item1 of list 2
|
|
Packit Service |
50c9f2 |
2. Item2 of list 2
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
With Markdown the actual numbers you use to mark the list have no
|
|
Packit Service |
50c9f2 |
effect on the HTML output Markdown produces. I.e. standard Markdown treats the
|
|
Packit Service |
50c9f2 |
following as one list with 3 numbered items:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
1. Item1
|
|
Packit Service |
50c9f2 |
1. Item2
|
|
Packit Service |
50c9f2 |
1. Item3
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen however requires that the numbers used as marks are in
|
|
Packit Service |
50c9f2 |
strictly ascending order, so the above example would produce 3 lists
|
|
Packit Service |
50c9f2 |
with one item. An item with an equal or lower number than
|
|
Packit Service |
50c9f2 |
the preceding item, will start a new list. For example:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
1. Item1 of list 1
|
|
Packit Service |
50c9f2 |
3. Item2 of list 1
|
|
Packit Service |
50c9f2 |
2. Item1 of list 2
|
|
Packit Service |
50c9f2 |
4. Item2 of list 2
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
will produce:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
1. Item1 of list 1
|
|
Packit Service |
50c9f2 |
3. Item2 of list 1
|
|
Packit Service |
50c9f2 |
2. Item1 of list 2
|
|
Packit Service |
50c9f2 |
4. Item2 of list 2
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Historically doxygen has an additional way to create numbered
|
|
Packit Service |
50c9f2 |
lists by using `-#` markers:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
-# item1
|
|
Packit Service |
50c9f2 |
-# item2
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection mddox_stars Use of asterisks
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Special care has to be taken when using *'s in a comment block
|
|
Packit Service |
50c9f2 |
to start a list or make a ruler.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen will strip off any leading *'s from the comment before doing
|
|
Packit Service |
50c9f2 |
Markdown processing. So although the following works fine
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
@verbatim
|
|
Packit Service |
50c9f2 |
/** A list:
|
|
Packit Service |
50c9f2 |
* * item1
|
|
Packit Service |
50c9f2 |
* * item2
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
@endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
When you remove the leading *'s doxygen will strip the other stars
|
|
Packit Service |
50c9f2 |
as well, making the list disappear!
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Rulers created with *'s will not be visible at all. They only work
|
|
Packit Service |
50c9f2 |
in Markdown files.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection mddox_limits Limits on markup scope
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To avoid that a stray * or _ matches something many paragraphs later,
|
|
Packit Service |
50c9f2 |
and shows everything in between with emphasis, doxygen limits the scope
|
|
Packit Service |
50c9f2 |
of a * and _ to a single paragraph.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For a code span, between the starting and ending backtick only two
|
|
Packit Service |
50c9f2 |
new lines are allowed.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Also for links there are limits; the link text, and link title each can
|
|
Packit Service |
50c9f2 |
contain only one new line, the URL may not contain any newlines.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section markdown_debug Debugging of problems
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
When doxygen parses the source code it first extracts the comments blocks,
|
|
Packit Service |
50c9f2 |
then passes these through the Markdown preprocessor. The output of the
|
|
Packit Service |
50c9f2 |
Markdown preprocessing consists of text with \ref cmd_intro "special commands"
|
|
Packit Service |
50c9f2 |
and \ref htmlcmds "HTML commands".
|
|
Packit Service |
50c9f2 |
A second pass takes the output of the Markdown preprocessor and
|
|
Packit Service |
50c9f2 |
converts it into the various output formats.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
During Markdown preprocessing no errors are produced. Anything that
|
|
Packit Service |
50c9f2 |
does not fit the Markdown syntax is simply passed on as-is. In the subsequent
|
|
Packit Service |
50c9f2 |
parsing phase this could lead to errors, which may not always be obvious
|
|
Packit Service |
50c9f2 |
as they are based on the intermediate format.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To see the result after Markdown processing you can run doxygen with the
|
|
Packit Service |
50c9f2 |
`-d Markdown` option. It will then print each comment block before and
|
|
Packit Service |
50c9f2 |
after Markdown processing.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\htmlonly
|
|
Packit Service |
50c9f2 |
Go to the next section or return to the
|
|
Packit Service |
50c9f2 |
index.
|
|
Packit Service |
50c9f2 |
\endhtmlonly
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
*/
|