|
DoxyPress
1.7.0
|
Markdown support is a plain text formatting syntax written by John Gruber. The following is a quote from his website regarding why Markdown was developed.
The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown's syntax is the format of plain text email.
For more information about Markdown refer to the official website Markdown
To make a paragraph separate consecutive lines of text by one or more blank lines.
An example:
Here is text for one paragraph. We continue with more text in another paragraph.
Just like Markdown, DoxyPress supports two types of headers. Level 1 (<h1>) or Level 2 (<h2>) headers can be accomplished as follows:
This is a level 1 header ======================== This is a level 2 header ------------------------
A header is followed by a line containing only the equal sign or dashes. The exact amount is not important as long as there are at least two. Alternatively, use the pound sign at the start of a line to make a header. The number of pound characters at the start of the line determines the level. Up to 6 levels are supported.
End a header by any number of pound signs if desired. For example:
# This is a level 1 header ### This is level 3 header #######
Block quotes can be created by starting each line with one or more greater than signs. This is similar to what is used in text only emails.
> This is a block quote > spanning multiple lines
Lists and code blocks (see below) can appear inside a quote block. Quote blocks can also be nested.
DoxyPress requires a space after the last greater than character on a line to avoid false positives. The second line in this example will not be seen as a block quote.
0 if OK\n >1 if NOK
Simple bullet lists can be made by starting a line with -, +, or *.
- Item 1 More text for this item. - Item 2 + nested list item. + another nested item. - Item 3
List items can span multiple paragraphs. Each paragraph must start with the proper indentation. Lists can also be nested.
You can also make a numbered list as follows:
1. Chicken 2. Fish
Refer to List Extensions for DoxyPress specifics information.
Preformatted verbatim blocks can be created by indenting each line in a block of text by at least 4 extra spaces.
This a normal paragraph
This is a code block
We continue with a normal paragraph again
DoxyPress will remove the mandatory indentation from the code block. You can not start a code block in the middle of a paragraph. The line preceding the code block must be empty.
Refer to Code Block Indentation for more info how DoxyPress handles indentation as this is slightly different than standard Markdown.
A horizontal ruler will be produced for lines containing at least three or more hyphens, asterisks, or underscores. The line may also include any amount of whitespace.
Examples:
- - - ______
Using using asterisks in comment blocks does not work. Refer to Use of Asterisks for more details.
To emphasize a text fragment start and end the fragment with an underscore or star. Using two stars or underscores will produce strong emphasis. Refer to Emphasis Limits for more information on how DoxyPress handles emphasis spans, which is slightly different from the standard Markdown.
To indicate a span of code wrap it in backticks (`). Unlike code blocks, code spans appear inline in a paragraph. For example:
Use the printf() function.
To show a literal backtick inside a code span, use double backticks.
To assign the output of command `ls` to `var` use ``var=`ls```
Refer to Code Spans Limits for more information on how DoxyPress handles code spans, which is slightly different than the standard Markdown.
DoxyPress supports both styles of make links defined by Markdown. For Both styles, the link definition starts with the link text delimited by [square brackets].
Inline Links
The link text is followed by a URL and an optional link title which together are enclosed in a set of regular parenthesis. The link title itself is surrounded by quotes.
Examples:
[The link text](https://example.net/) [The link text](https://example.net/ "Link title") [The link text](/relative/path/to/index.html "Link title") [The link text](somefile.html)
DoxyPress extends the Markdown syntax for linking a documented entity:
[The link text](@ref MyClass)
Reference Links
Instead of putting the URL inline you can define the link separately, and then refer to it from within the text. Instead of double quotes, single quotes or parenthesis can be used for the title. The link name is not case sensitive and link definitions will not be visible in the output.
The following is an example of how the link is defined:
[link name]: https://www.example.com "Optional title"
This example shows how the link is referenced:
[link text][link name]
This example shows how the link is referenced if the link text and name are the same:
[link name][]
DoxyPress extends the Markdown syntax for linking a documented entity:
[myclass]: @ref MyClass "My class"
The syntax for images is similar to links with the inclusion of an additional "!" before the link text. The caption text is optional.
Examples:
  ![Caption text][img def] ![img def] [img def]: /path/to/img.jpg "Optional Title"
The @ref syntax can be used to link to an image:
 ![img def] [img def]: @ref image.png "Caption text"
To create a link to an URL or e-mail address Markdown supports the following syntax.
<http://www.example.com> <https://www.example.com> <ftp://www.example.com> <mailto:address@example.com> <address@example.com>
The following are the four Markdown Extensions in DoxyPress.
The special command [TOC] can be placed on a page to produce a table of contents. Using [TOC] is the same as the \tableofcontents command. The toc-include-headers tag must be set to a value greater than 0 otherwise no table of contents will be shown when using markdown syntax headers.
For additional information refer to Headers in the Markdown documentation.
A simple table consists of a header line, a separator line, and at least one row line. Table columns are separated by the pipe (|) character.
The following documentation will generate the table shown below:
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
| First Header | Second Header |
|---|---|
| Content Cell | Content Cell |
| Content Cell | Content Cell |
Column alignment can be controlled via one or two colons at the header separator line.
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 20 | 30 | | 1000 | 2000 | 3000 |
| Right | Center | Left |
|---|---|---|
| 10 | 20 | 30 |
| 1000 | 1000 | 1000 |
A fenced code block does not require indentation and is defined by a pair of "fence lines". Such a line consists of 3 or more tilde (~) characters on a line. The end of the block should have the same number of tildes. By default the output is the same as for a normal code block.
This is a paragraph introducing: ~~~~~~~~~~~~~~~~~~~~~ a one-line code block ~~~~~~~~~~~~~~~~~~~~~
For languages supported by DoxyPress you can also make the code block appear with syntax highlighting. Indicate the file extension which corresponds to the programming language after the opening fence. As an example, the following is highlighting for a Python code. The resulting code block is shown below.
~~~~~~~~~~~~~{.py}
# Some class definition
class SomeClass:
pass
~~~~~~~~~~~~~
The following is an example of C source code styling. The result of this code block is shown below.
~~~~~~~~~~~~~~~{.c}
int func(int a, int b) {
return a * b;
}
~~~~~~~~~~~~~~~
Another way to denote a fenced code block is to use 3 or more backticks (```). The first block below shows the syntax, the second block is how the block will appear in the generated documentation.
``` This is also a fenced code block ```
Standard Markdown has no support for labeling headers which is a problem if you want to link to a section. This feature only works for headers of levels 1, 2, 3, or 4. An example of the Header Id attribute is shown below.
Header 1 {#labelid}
========
## Header 2 ## {#labelid2}
To link to a section in the same comment block use:
[Link text](#labelid)
To link to any section use @ref as follows:
[Link text](@ref labelid)
DoxyPress follows the Markdown standard as closely as possible. There are however some differences.
For DoxyPress to process files with Markdown formatting, the extension of the file should be .md or .markdown. Each file is converted to a page, where the name and title of the page are derived from the file name. If the file starts with a level 1 header, the header is used as the title of the page.
If you specify a label for the header DoxyPress will use the label as the page name. If the label name is index or the label name is mainpage DoxyPress will use the markdown file as the index.html page.
Refer to page command for more details about pages. Refer to language-mapping if your Markdown file does not have the standard extension.
Th following is an example of a file README.md which will appear as the index.html page.
My Main Page {#mainpage}
============
This documentation will appear on the main page . . .
If a markdown page has a label you can link to it using the @ref command. To link to a markdown page without a label you must use the file name of the page.
See [the other page](other.md) for more information.
Markdown has strict requirements for how it processes block-level HTML.
Block-level HTML elements like
<div>,<table>,<pre>, and<p>must be separated from surrounding content by blank lines. The start and end tags of the block should not be indented with tabs or spaces.
DoxyPress does not have this requirement and will process Markdown formatting inside these HTML blocks. The only exception is <pre> blocks, which are passed untouched. DoxyPress will not process Markdown formatting inside verbatim or code blocks and in other sections which need to be processed without changes, like formulas or inline dot graphs.
Markdown allows either a single tab or four spaces to start a code block. DoxyPress replaces tabs with spaces before doing Markdown processing. To have tabs and spaces do the same thing, the TAB-SIZE in the project file must be set to four.
When it is set to a higher value, spaces will be present in the code block. A lower value will prevent a single tab from being interpreted as the start of a code block.
With Markdown, any block which is indented by four spaces (and 8 spaces inside lists) is treated as a code block. This indentation amount is absolute and counting begins from the start of the line.
Since DoxyPress comments can appear at any indentation level required by the programming language, relative indentation is used. The amount of indentation is counted relative to the preceding paragraph. In case there is no preceding paragraph the minimal amount of indentation of the whole comment block is used as a reference.
In most cases the difference between Markdown and DoxyPress does not result in different output. In some cases the indentation levels for DoxyPress are different than what Markdown would have produced.
List markers are not counted when determining the relative indent level. For Item1 the indentation is 4 (when treating the list marker as whitespace), so the next paragraph "More text..." starts at the same indentation level and is therefore not seen as a code block.
1. Item1
More text for item1
2. Item2
Code block for item2
Unlike standard Markdown DoxyPress will not modify internal stars or underscores so the following will appear verbatim.
a_nice_identifier
A * starts a bold span and _ starts an underline span only if both of the following are true.
<{([,:;The bold or underline span ends when both of the following are true.
({[<=+-\@The span of the bold or underline is limited to a single paragraph.
Unlike standard Markdown DoxyPress leaves the following text unmodified when it is inside a code block.
A `cool' word in a `nice' sentence.
A single quote cancels the normal processing of a code span.
With Markdown two lists separated by an empty line are joined together into a single list. This is often thought to be a bug or a problem. DoxyPress will make two separate lists as normally expected.
For example:
- Item1 of list A - Item2 of list A 1. Item1 of list B 2. Item2 of list B
With Markdown the actual numbers you use to mark a list have no effect on the HTML output Markdown produces. Given the following example, standard Markdown treats the following as one list with items numbers one, two, and three.
DoxyPress requires numbers to be in strictly ascending order. Given the following example DoxyPress will produce three lists with a numbered item value of one, in each list.
1. Item1 1. Item2 1. Item3
An item with an equal or lower number than the preceding item, will start a new list. Given the following example:
1. Item1 of list X 3. Item2 of list X 2. Item1 of list Y 4. Item2 of list Y
The output will be as follows:
DoxyPress has an additional way to create numbered lists by using -# markers as follows:
-# item1 -# item2
DoxyPress will strip any leading asterisks from a comment before doing any Markdown processing. Asterisks must be used carefully when creating a list or make a ruler within a comment block.
The following example works fine. If you remove the leading asterisks DoxyPress will strip the other stars, making the list disappear.
Rulers created with asterisks will not be visible at all. They only work in Markdown files.
/** A list:
* * item1
* * item2
*/
When DoxyPress parses the source code it first extracts the comments blocks, then passes these through the Markdown preprocessor. The output of the Markdown preprocessing consists of text with General Commands and HTML Tags.
A second pass takes the output of the Markdown preprocessor and converts it into the various output formats.
During Markdown preprocessing no errors are produced. Anything that does not fit the Markdown syntax is simply passed on as-is. In the subsequent parsing phase this may lead to errors, which may not always be obvious since the actual issue could be in the Markdown.
1.7.0