/usr/share/doc/doxygen/html/markdown.html is in doxygen-doc 1.8.13-10.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Markdown support</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('markdown.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Markdown support </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#markdown_std">Standard Markdown</a><ul><li class="level2"><a href="#md_para">Paragraphs</a></li>
<li class="level2"><a href="#md_headers">Headers</a></li>
<li class="level2"><a href="#md_blockquotes">Block quotes</a></li>
<li class="level2"><a href="#md_lists">Lists</a></li>
<li class="level2"><a href="#md_codeblock">Code Blocks</a></li>
<li class="level2"><a href="#md_rulers">Horizontal Rulers</a></li>
<li class="level2"><a href="#md_emphasis">Emphasis</a></li>
<li class="level2"><a href="#md_codespan">code spans</a></li>
<li class="level2"><a href="#md_links">Links</a><ul><li class="level3"><a href="#md_inlinelinks">Inline Links</a></li>
<li class="level3"><a href="#md_reflinks">Reference Links</a></li>
</ul>
</li>
<li class="level2"><a href="#md_images">Images</a></li>
<li class="level2"><a href="#md_autolink">Automatic Linking</a></li>
</ul>
</li>
<li class="level1"><a href="#markdown_extra">Markdown Extensions</a><ul><li class="level2"><a href="#md_toc">Table of Contents</a></li>
<li class="level2"><a href="#md_tables">Tables</a></li>
<li class="level2"><a href="#md_fenced">Fenced Code Blocks</a></li>
<li class="level2"><a href="#md_header_id">Header Id Attributes</a></li>
</ul>
</li>
<li class="level1"><a href="#markdown_dox">Doxygen specifics</a><ul><li class="level2"><a href="#md_page_header">Including Markdown files as pages</a></li>
<li class="level2"><a href="#md_html_blocks">Treatment of HTML blocks</a></li>
<li class="level2"><a href="#mddox_code_blocks">Code Block Indentation</a></li>
<li class="level2"><a href="#mddox_emph_spans">Emphasis limits</a></li>
<li class="level2"><a href="#mddox_code_spans">Code Spans Limits</a></li>
<li class="level2"><a href="#mddox_lists">Lists Extensions</a></li>
<li class="level2"><a href="#mddox_stars">Use of asterisks</a></li>
<li class="level2"><a href="#mddox_limits">Limits on markup scope</a></li>
</ul>
</li>
<li class="level1"><a href="#markdown_debug">Debugging of problems</a></li>
</ul>
</div>
<div class="textblock"><p><a href="http://daringfireball.net/projects/markdown">Markdown</a> support was introduced in doxygen version 1.8.0. It is a plain text formatting syntax written by John Gruber, with the following underlying design goal:</p>
<blockquote class="doxtable">
<p>The 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. </p>
</blockquote>
<p>In the <a class="el" href="markdown.html#markdown_std">next section</a> the standard Markdown features are briefly discussed. The reader is referred to the <a href="http://daringfireball.net/projects/markdown">Markdown site</a> for more details.</p>
<p>Some enhancements were made, for instance <a href="http://michelf.com/projects/php-markdown/extra/">PHP Markdown Extra</a>, and <a href="http://github.github.com/github-flavored-markdown/">GitHub flavored Markdown</a>. The section <a class="el" href="markdown.html#markdown_extra">Markdown Extensions</a> discusses the extensions that doxygen supports.</p>
<p>Finally section <a class="el" href="markdown.html#markdown_dox">Doxygen specifics</a> discusses some specifics for doxygen's implementation of the Markdown standard.</p>
<h1><a class="anchor" id="markdown_std"></a>
Standard Markdown</h1>
<h2><a class="anchor" id="md_para"></a>
Paragraphs</h2>
<p>Even before doxygen had Markdown support it supported the same way of paragraph handling as Markdown: to make a paragraph you just separate consecutive lines of text by one or more blank lines.</p>
<p>An example: </p><pre class="fragment">Here is text for one paragraph.
We continue with more text in another paragraph.
</pre><h2><a class="anchor" id="md_headers"></a>
Headers</h2>
<p>Just like Markdown, doxygen supports two types of headers</p>
<p>Level 1 or 2 headers can be made as the follows </p><pre class="fragment">This is a level 1 header
========================
This is a level 2 header
------------------------
</pre><p>A header is followed by a line containing only ='s or -'s. Note that the exact amount of ='s or -'s is not important as long as there are at least two.</p>
<p>Alternatively, you can use #'s at the start of a line to make a header. The number of #'s at the start of the line determines the level (up to 6 levels are supported). You can end a header by any number of #'s.</p>
<p>Here is an example: </p><pre class="fragment"># This is a level 1 header
### This is level 3 header #######
</pre><h2><a class="anchor" id="md_blockquotes"></a>
Block quotes</h2>
<p>Block quotes can be created by starting each line with one or more >'s, similar to what is used in text-only emails. </p><pre class="fragment">> This is a block quote
> spanning multiple lines
</pre><p>Lists and code blocks (see below) can appear inside a quote block. Quote blocks can also be nested.</p>
<p>Note that doxygen requires that you put a space after the (last) > character to avoid false positives, i.e. when writing </p><pre class="fragment">0 if OK\n
>1 if NOK
</pre><p>the second line will not be seen as a block quote.</p>
<h2><a class="anchor" id="md_lists"></a>
Lists</h2>
<p>Simple bullet lists can be made by starting a line with -, +, or *. </p><pre class="fragment">- Item 1
More text for this item.
- Item 2
+ nested list item.
+ another nested item.
- Item 3
</pre><p>List items can span multiple paragraphs (if each paragraph starts with the proper indentation) and lists can be nested. You can also make a numbered list like so </p><pre class="fragment">1. First item.
2. Second item.
</pre><p>Make sure to also read <a class="el" href="markdown.html#mddox_lists">Lists Extensions</a> for doxygen specifics.</p>
<h2><a class="anchor" id="md_codeblock"></a>
Code Blocks</h2>
<p>Preformatted verbatim blocks can be created by indenting each line in a block of text by at least 4 extra spaces </p><pre class="fragment">This a normal paragraph
This is a code block
We continue with a normal paragraph again.
</pre><p>Doxygen will remove the mandatory indentation from the code block. Note that you cannot start a code block in the middle of a paragraph (i.e. the line preceding the code block must be empty).</p>
<p>See section <a class="el" href="markdown.html#mddox_code_blocks">Code Block Indentation</a> for more info how doxygen handles indentation as this is slightly different than standard Markdown.</p>
<h2><a class="anchor" id="md_rulers"></a>
Horizontal Rulers</h2>
<p>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.</p>
<p>Examples: </p><pre class="fragment">- - -
______
</pre><p>Note that using asterisks in comment blocks does not work. See <a class="el" href="markdown.html#mddox_stars">Use of asterisks</a> for details.</p>
<h2><a class="anchor" id="md_emphasis"></a>
Emphasis</h2>
<p>To emphasize a text fragment you start and end the fragment with an underscore or star. Using two stars or underscores will produce strong emphasis.</p>
<p>Examples: </p><pre class="fragment"> single asterisks*
_single underscores_
double asterisks**
__double underscores__
</pre><p>See section <a class="el" href="markdown.html#mddox_emph_spans">Emphasis limits</a> for more info how doxygen handles emphasis spans slightly different than standard Markdown.</p>
<h2><a class="anchor" id="md_codespan"></a>
code spans</h2>
<p>To indicate a span of code, you should wrap it in backticks (`). Unlike code blocks, code spans appear inline in a paragraph. An example: </p><pre class="fragment">Use the `printf()` function.
</pre><p>To show a literal backtick inside a code span use double backticks, i.e. </p><pre class="fragment">To assign the output of command `ls` to `var` use ``var=`ls```.
</pre><p>See section <a class="el" href="markdown.html#mddox_code_spans">Code Spans Limits</a> for more info how doxygen handles code spans slightly different than standard Markdown.</p>
<h2><a class="anchor" id="md_links"></a>
Links</h2>
<p>Doxygen supports both styles of make links defined by Markdown: <em>inline</em> and <em>reference</em>.</p>
<p>For both styles the link definition starts with the link text delimited by [square brackets].</p>
<h3><a class="anchor" id="md_inlinelinks"></a>
Inline Links</h3>
<p>For an inline link 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.</p>
<p>Examples: </p><pre class="fragment">[The link text](http://example.net/)
[The link text](http://example.net/ "Link title")
[The link text](/relative/path/to/index.html "Link title")
[The link text](somefile.html)
</pre><p>In addition doxygen provides a similar way to link a documented entity: </p><pre class="fragment">[The link text](@ref MyClass)
</pre><h3><a class="anchor" id="md_reflinks"></a>
Reference Links</h3>
<p>Instead of putting the URL inline, you can also define the link separately and then refer to it from within the text.</p>
<p>The link definition looks as follows: </p><pre class="fragment">[link name]: http://www.example.com "Optional title"
</pre><p>Instead of double quotes also single quotes or parenthesis can be used for the title part.</p>
<p>Once defined, the link looks as follows </p><pre class="fragment">[link text][link name]
</pre><p>If the link text and name are the same, also </p><pre class="fragment">[link name][]
</pre><p>or even </p><pre class="fragment">[link name]
</pre><p>can be used to refer to the link. Note that the link name matching is not case sensitive as is shown in the following example: </p><pre class="fragment">I get 10 times more traffic from [Google] than from
[Yahoo] or [MSN].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
</pre><p>Link definitions will not be visible in the output.</p>
<p>Like for inline links doxygen also supports @ref inside a link definition: </p><pre class="fragment">[myclass]: @ref MyClass "My class"
</pre><h2><a class="anchor" id="md_images"></a>
Images</h2>
<p>Markdown syntax for images is similar to that for links. The only difference is an additional ! before the link text.</p>
<p>Examples: </p><pre class="fragment">
![Caption text][img def]
![img def]
[img def]: /path/to/img.jpg "Optional Title"
</pre><p>Also here you can use @ref to link to an image: </p><pre class="fragment">
![img def]
[img def]: @ref image.png "Caption text"
</pre><p>The caption text is optional.</p>
<h2><a class="anchor" id="md_autolink"></a>
Automatic Linking</h2>
<p>To create a link to an URL or e-mail address Markdown supports the following syntax: </p><pre class="fragment"><http://www.example.com>
<https://www.example.com>
<ftp://www.example.com>
<mailto:address@example.com>
<address@example.com>
</pre><p>Note that doxygen will also produce the links without the angle brackets.</p>
<h1><a class="anchor" id="markdown_extra"></a>
Markdown Extensions</h1>
<h2><a class="anchor" id="md_toc"></a>
Table of Contents</h2>
<p>Doxygen supports a special link marker <code>[TOC]</code> which can be placed in a page to produce a table of contents at the start of the page, listing all sections.</p>
<p>Note that using <code>[TOC]</code> is the same as using a <a class="el" href="commands.html#cmdtableofcontents">\tableofcontents</a> command.</p>
<h2><a class="anchor" id="md_tables"></a>
Tables</h2>
<p>Of the features defined by "Markdown Extra" is support for <a href="http://michelf.com/projects/php-markdown/extra/#table">simple tables</a>:</p>
<p>A table consists of a header line, a separator line, and at least one row line. Table columns are separated by the pipe (|) character.</p>
<p>Here is an example: </p><pre class="fragment">First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
</pre><p>which will produce the following table:</p>
<table class="doxtable">
<tr>
<th>First Header </th><th>Second Header </th></tr>
<tr>
<td>Content Cell </td><td>Content Cell </td></tr>
<tr>
<td>Content Cell </td><td>Content Cell </td></tr>
</table>
<p>Column alignment can be controlled via one or two colons at the header separator line: </p><pre class="fragment">| Right | Center | Left |
| ----: | :----: | :---- |
| 10 | 10 | 10 |
| 1000 | 1000 | 1000 |
</pre><p>which will look as follows:</p>
<table class="doxtable">
<tr>
<th align="right">Right </th><th align="center">Center </th><th align="left">Left </th></tr>
<tr>
<td align="right">10 </td><td align="center">10 </td><td align="left">10 </td></tr>
<tr>
<td align="right">1000 </td><td align="center">1000 </td><td align="left">1000 </td></tr>
</table>
<p>Additionally, column and row spans are supported. Using a caret ("^") in a cell indicates that the cell above should span rows. Sequences of carets may be used for any number of row spans. For example: </p><pre class="fragment">| Right | Center | Left |
| ----: | :----: | :---- |
| 10 | 10 | 10 |
| ^ | 1000 | 1000 |
</pre><p>which will look as follows:</p>
<table class="doxtable">
<tr>
<th align="right">Right </th><th align="center">Center </th><th align="left">Left </th></tr>
<tr>
<td align="right">10 </td><td align="center">10 </td><td align="left">10 </td></tr>
<tr>
<td align="right">^ </td><td align="center">1000 </td><td align="left">1000 </td></tr>
</table>
<p>Column spans are supported by means of directly adjacent vertical bars ("|"). Each additional vertical bar indicates an additional column to be spanned. To put it another way, a single vertical bar indicates a single column span, two vertical bars indicates a 2 columns span, and so on. For example: </p><pre class="fragment">| Right | Center | Left |
| ----: | :----: | :---- |
| 10 | 10 | 10 |
| 1000 |||
</pre><p>which will look as follows:</p>
<table class="doxtable">
<tr>
<th align="right">Right </th><th align="center">Center </th><th align="left">Left </th></tr>
<tr>
<td align="right">10 </td><td align="center">10 </td><td align="left">10 </td></tr>
<tr>
<td align="right">1000 </td><td align="center"></td></tr>
</table>
<p>For more complex tables in doxygen please have a look at: <a class="el" href="tables.html">Including tables</a></p>
<h2><a class="anchor" id="md_fenced"></a>
Fenced Code Blocks</h2>
<p>Another feature defined by "Markdown Extra" is support for <a href="http://michelf.com/projects/php-markdown/extra/#fenced-code-blocks">fenced code blocks</a>:</p>
<p>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. Here is an example:</p>
<pre class="fragment">This is a paragraph introducing:
~~~~~~~~~~~~~~~~~~~~~
a one-line code block
~~~~~~~~~~~~~~~~~~~~~
</pre><p>By default the output is the same as for a normal code block.</p>
<p>For languages supported by doxygen you can also make the code block appear with syntax highlighting. To do so you need to indicate the typical file extension that corresponds to the programming language after the opening fence. For highlighting according to the Python language for instance, you would need to write the following: </p><pre class="fragment">~~~~~~~~~~~~~{.py}
# A class
class Dummy:
pass
~~~~~~~~~~~~~
</pre><p>which will produce: </p><div class="fragment"><div class="line"><span class="comment"># A class</span></div><div class="line"><span class="keyword">class </span>Dummy:</div><div class="line"> <span class="keywordflow">pass</span></div></div><!-- fragment --><p>and for C you would write: </p><pre class="fragment">~~~~~~~~~~~~~~~{.c}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~
</pre><p>which will produce:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> func(<span class="keywordtype">int</span> a,<span class="keywordtype">int</span> b) { <span class="keywordflow">return</span> a*b; }</div></div><!-- fragment --><p>The curly braces and dot are optional by the way.</p>
<p>Another way to denote fenced code blocks is to use 3 or more backticks (```): </p><pre class="fragment">```
also a fenced code block
```
</pre><h2><a class="anchor" id="md_header_id"></a>
Header Id Attributes</h2>
<p>Standard Markdown has no support for labeling headers, which is a problem if you want to link to a section.</p>
<p>PHP Markdown Extra allows you to label a header by adding the following to the header </p><pre class="fragment">Header 1 {#labelid}
========
## Header 2 ## {#labelid2}
</pre><p>To link to a section in the same comment block you can use </p><pre class="fragment">[Link text](#labelid)
</pre><p>to link to a section in general, doxygen allows you to use @ref </p><pre class="fragment">[Link text](@ref labelid)
</pre><p>Note this only works for the headers of level 1 to 4.</p>
<h1><a class="anchor" id="markdown_dox"></a>
Doxygen specifics</h1>
<p>Even though doxygen tries to following the Markdown standard as closely as possible, there are couple of deviation and doxygen specifics additions.</p>
<h2><a class="anchor" id="md_page_header"></a>
Including Markdown files as pages</h2>
<p>Doxygen can process files with Markdown formatting. For this to work the extension for such a file should be <code>.md</code> or <code>.markdown</code> (see <a class="el" href="config.html#cfg_extension_mapping">EXTENSION_MAPPING</a> if your Markdown files have a different extension, and use <code>md</code> as the name of the parser). Each file is converted to a page (see the <a class="el" href="commands.html#cmdpage">page</a> command for details).</p>
<p>By default the name and title of the page are derived from the file name. If the file starts with a level 1 header however, it is used as the title of the page. If you specify a label for the header (as shown in <a class="el" href="markdown.html#md_header_id">Header Id Attributes</a>) doxygen will use that as the page name.</p>
<p>If the label is called <code>index</code> or <code>mainpage</code> doxygen will put the documentation on the front page (<code>index.html</code>).</p>
<p>Here is an example of a file <code>README.md</code> that will appear as the main page when processed by doxygen: </p><pre class="fragment">My Main Page {#mainpage}
============
Documentation that will appear on the main page
</pre><p>If a page has a label you can link to it using <a class="el" href="commands.html#cmdref">@ref</a> as is shown above. To refer to a markdown page without such label you can simple use the file name of the page, e.g. </p><pre class="fragment">See [the other page](other.md) for more info.
</pre><h2><a class="anchor" id="md_html_blocks"></a>
Treatment of HTML blocks</h2>
<p>Markdown is quite strict in the way it processes block-level HTML:</p>
<blockquote class="doxtable">
<p>block-level HTML elements — e.g. <code><div></code>, <code><table></code>, <code><pre></code>, <code><p></code>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. </p>
</blockquote>
<p>Doxygen does not have this requirement, and will also process Markdown formatting inside such HTML blocks. The only exception is <code><pre></code> blocks, which are passed untouched (handy for ASCII art).</p>
<p>Doxygen will not process Markdown formatting inside verbatim or code blocks, and in other sections that need to be processed without changes (for instance formulas or inline dot graphs).</p>
<h2><a class="anchor" id="mddox_code_blocks"></a>
Code Block Indentation</h2>
<p>Markdown allows both a single tab or 4 spaces to start a code block. Since doxygen already replaces tabs by spaces before doing Markdown processing, the effect will only be same if TAB_SIZE in the config file has been set to 4. When it is set to a higher value spaces will be present in the code block. A lower value will prevent a single tab to be interpreted as the start of a code block.</p>
<p>With Markdown any block that is indented by 4 spaces (and 8 spaces inside lists) is treated as a code block. This indentation amount is absolute, i.e. counting from the start of the line.</p>
<p>Since doxygen comments can appear at any indentation level that is required by the programming language, it uses a relative indentation instead. The amount of indentation is counted relative to the preceding paragraph. In case there is no preceding paragraph (i.e. you want to start with a code block), the minimal amount of indentation of the whole comment block is used as a reference.</p>
<p>In most cases this difference does not result in different output. Only if you play with the indentation of paragraphs the difference is noticeable: </p><pre class="fragment">text
text
text
code
</pre><p>In this case Markdown will put the word code in a code block, whereas doxygen will treat it as normal text, since although the absolute indentation is 4, the indentation with respect to the previous paragraph is only 1.</p>
<p>Note that list markers are not counted when determining the relative indent: </p><pre class="fragment">1. Item1
More text for item1
2. Item2
Code block for item2
</pre><p>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.</p>
<h2><a class="anchor" id="mddox_emph_spans"></a>
Emphasis limits</h2>
<p>Unlike standard Markdown, doxygen will not touch internal underscores or stars, so the following will appear as-is: </p><pre class="fragment">a_nice_identifier
</pre><p>Furthermore, a <code>*</code> or <code>_</code> only starts an emphasis if</p><ul>
<li>it is followed by an alphanumerical character, and</li>
<li>it is preceded by a space, newline, or one the following characters <code><{([,:;</code></li>
</ul>
<p>An emphasis ends if</p><ul>
<li>it is not followed by an alphanumerical character, and</li>
<li>it is not preceded by a space, newline, or one the following characters <code>({[<=+-\@</code></li>
</ul>
<p>Lastly, the span of the emphasis is limited to a single paragraph.</p>
<h2><a class="anchor" id="mddox_code_spans"></a>
Code Spans Limits</h2>
<p>Note that unlike standard Markdown, doxygen leaves the following untouched. </p><pre class="fragment">A `cool' word in a `nice' sentence.
</pre><p>In other words; a single quote cancels the special treatment of a code span wrapped in a pair of backtick characters. This extra restriction was added for backward compatibility reasons.</p>
<h2><a class="anchor" id="mddox_lists"></a>
Lists Extensions</h2>
<p>With Markdown two lists separated by an empty line are joined together into a single list which can be rather unexpected and many people consider it to be a bug. Doxygen, however, will make two separate lists as you would expect.</p>
<p>Example: </p><pre class="fragment">- Item1 of list 1
- Item2 of list 1
1. Item1 of list 2
2. Item2 of list 2
</pre><p>With Markdown the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. I.e. standard Markdown treats the following as one list with 3 numbered items: </p><pre class="fragment">1. Item1
1. Item2
1. Item3
</pre><p>Doxygen however requires that the numbers used as marks are in strictly ascending order, so the above example would produce 3 lists with one item. An item with an equal or lower number than the preceding item, will start a new list. For example: </p><pre class="fragment">1. Item1 of list 1
3. Item2 of list 1
2. Item1 of list 2
4. Item2 of list 2
</pre><p>will produce:</p>
<ol type="1">
<li>Item1 of list 1</li>
<li>Item2 of list 1</li>
</ol>
<ol type="1">
<li>Item1 of list 2</li>
<li>Item2 of list 2</li>
</ol>
<p>Historically doxygen has an additional way to create numbered lists by using <code>-#</code> markers: </p><pre class="fragment">-# item1
-# item2
</pre><h2><a class="anchor" id="mddox_stars"></a>
Use of asterisks</h2>
<p>Special care has to be taken when using *'s in a comment block to start a list or make a ruler.</p>
<p>Doxygen will strip off any leading *'s from the comment before doing Markdown processing. So although the following works fine</p>
<pre class="fragment"> /** A list:
* * item1
* * item2
*/
</pre><p>When you remove the leading *'s doxygen will strip the other stars as well, making the list disappear!</p>
<p>Rulers created with *'s will not be visible at all. They only work in Markdown files.</p>
<h2><a class="anchor" id="mddox_limits"></a>
Limits on markup scope</h2>
<p>To avoid that a stray * or _ matches something many paragraphs later, and shows everything in between with emphasis, doxygen limits the scope of a * and _ to a single paragraph.</p>
<p>For a code span, between the starting and ending backtick only two new lines are allowed.</p>
<p>Also for links there are limits; the link text, and link title each can contain only one new line, the URL may not contain any newlines.</p>
<h1><a class="anchor" id="markdown_debug"></a>
Debugging of problems</h1>
<p>When doxygen 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 <a class="el" href="commands.html#cmd_intro">special commands</a> and <a class="el" href="htmlcmds.html">HTML commands</a>. A second pass takes the output of the Markdown preprocessor and converts it into the various output formats.</p>
<p>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 could lead to errors, which may not always be obvious as they are based on the intermediate format.</p>
<p>To see the result after Markdown processing you can run doxygen with the <code>-d Markdown</code> option. It will then print each comment block before and after Markdown processing.</p>
<p>
Go to the <a href="lists.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
</ul>
</div>
</body>
</html>
|