diff options
Diffstat (limited to 'doc/markdown.doc')
-rw-r--r-- | doc/markdown.doc | 607 |
1 files changed, 607 insertions, 0 deletions
diff --git a/doc/markdown.doc b/doc/markdown.doc new file mode 100644 index 0000000..ea6776e --- /dev/null +++ b/doc/markdown.doc @@ -0,0 +1,607 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2011 by Dimitri van Heesch. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation under the terms of the GNU General Public License is hereby + * granted. No representations are made about the suitability of this software + * for any purpose. It is provided "as is" without express or implied warranty. + * See the GNU General Public License for more details. + * + * Documents produced by Doxygen are derivative works derived from the + * input used in their production; they are not affected by this license. + * + */ +/*! \page markdown Markdown support + +Table of contents +- \ref markdown_std + - \ref md_para + - \ref md_headers + - \ref md_blockquotes + - \ref md_lists + - \ref md_codeblock + - \ref md_rulers + - \ref md_emphasis + - \ref md_codespan + - \ref md_links + - \ref md_inlinelinks + - \ref md_reflinks + - \ref md_images + - \ref md_autolink +- \ref markdown_extra + - \ref md_tables + - \ref md_fenced + - \ref md_header_id +- \ref markdown_dox + - \ref md_page_header + - \ref md_html_blocks + - \ref mddox_code_blocks + - \ref mddox_code_spans + - \ref mddox_lists + - \ref mddox_stars + - \ref mddox_limits +- \ref markdown_debug + +[Markdown] 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: + +> 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. + +In the \ref markdown_std "next section" the standard markdown features +are briefly discussed. The reader is referred to the [Markdown site][markdown] +for more details. + +Some enhancements were made, for instance [PHP Markdown Extra][mdextra], and +[GitHub flavored Markdown][github]. The section \ref markdown_extra discusses +the extensions that doxygen supports. + +Finally section \ref markdown_dox discusses some specifics for doxygen's +implementation of the Markdown standard. + +[markdown]: http://daringfireball.net/projects/markdown +[mdextra]: http://michelf.com/projects/php-markdown/extra/ +[github]: http://github.github.com/github-flavored-markdown/ + +\section markdown_std Standard Markdown + +\subsection md_para Paragraphs + +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. + +An example: + + Here is text for one paragraph. + + We continue with more text in another paragraph. + +\subsection md_headers Headers + +Just like Markdown, doxygen supports two types of headers + +Level 1 or 2 headers can be made as the follows + + This is an level 1 header + ========================= + + This is an level 2 header + ------------------------- + +A header is followed by a line containing only ='s or -'s. +Note that the exact amount of ='s or -'s is not important. + +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. + +Here is an example: + + # This is a level 1 header + + ### This is level 3 header ####### + +\subsection md_blockquotes Block quotes + +Block quotes can be created by starting each line with one or more >'s, +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. + +Note that doxygen requires that you put a space after the (last) > character +to avoid false positives, i.e. when writing + + 0 if OK\n + >1 if NOK + +the second line will not seen as a block quote. + +\subsection md_lists Lists + +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 (if each paragraph starts with +the proper indentation) and lists can be nested. +You can also make a numbered list like so + + 1. First item. + 2. Second item. + +\subsection md_codeblock Code Blocks + +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. + +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). + +See section \ref mddox_code_blocks for more info how doxygen handles +indentation as this is slightly different than standard Markdown. + +\subsection md_rulers Horizontal Rulers + +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: + + - - - + ______ + +Note that using asterisks in comment blocks does not work. See +\ref mddox_stars for details. + +\subsection md_emphasis Emphasis + +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. + +Examples: + + *single asterisks* + + _single underscores_ + + **double asterisks** + + __double underscores__ + +Note that unlike standard Markdown, doxygen will not touch internal underscores or +stars, so the following will appear as-is: + + a_nice_identifier + +\subsection md_codespan code spans + +To indicate a span of code, you should wrap it in backticks (`). Unlike code blocks, +code spans appear inline in a paragraph. An example: + + Use the `printf()` function. + +To show a literal backtick inside a code span use double backticks, i.e. + + To assign the output of command `ls` to `var` use ``var=`ls```. + +See section \ref mddox_code_spans for more info how doxygen handles +code spans slightly different than standard Markdown. + +\subsection md_links Links + +Doxygen supports both styles of make links defined by Markdown: *inline* and *reference*. + +For both styles the link definition starts with the link text delimited by [square +brackets]. + +\subsubsection md_inlinelinks Inline Links + +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. + +Examples: + + [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) + +In addition doxygen provides a similar way to link a documented entity: + + [The link text](@ref MyClass) + +\subsubsection md_reflinks Reference Links + +Instead of putting the URL inline, you can also define the link separately +and then refer to it from within the text. + +The link definition looks as follows: + + [link name]: http://www.example.com "Optional title" + +Instead of double quotes also single quotes or parenthesis can +be used for the title part. + +Once defined, the link looks as follows + + [link text][link name] + +If the link text and name are the same, also + + [link name][] + +or even + + [link name] + +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: + + 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" + +Link definitions will not be visible in the output. + +Like for inline links doxygen also supports \@ref inside a link definition: + + [myclass]: @ref MyClass "My class" + +\subsection md_images Images + +Markdown syntax for images is similar to that for links. +The only difference is an additional ! before the link text. + +Examples: + + ![Caption text](/path/to/img.jpg) + ![Caption text](/path/to/img.jpg "Image title") + ![Caption text][img def] + ![img def] + + [img def]: /path/to/img.jpg "Optional Title" + +Also here you can use \@ref to link to an image: + + ![Caption text](@ref image.png) + ![img def] + + [img def]: @ref image.png "Caption text" + +The caption text is optional. + +\subsection md_autolink Automatic Linking + +To create a link to an URL or e-mail address Markdown supports the following +syntax: + + <http://www.example.com> + <address@example.com> + +Note that doxygen will also produce the links without the angle brackets. + +\section markdown_extra Markdown Extensions + +\subsection md_tables Tables + +Of the features defined by "Markdown Extra" is support for +<a href="http://michelf.com/projects/php-markdown/extra/#table">simple tables</a>: + +A table consists of a header line, a separator line, and at least one +row line. Table columns are separated by the pipe (!) character. + +Here is an example: + + First Header | Second Header + ------------- | ------------- + Content Cell | Content Cell + Content Cell | Content Cell + +which will produce the following table: + +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 | 10 | 10 | + | 1000 | 1000 | 1000 | + +which will look as follows: + +| Right | Center | Left | +| ----: | :----: | :---- | +| 10 | 10 | 10 | +| 1000 | 1000 | 1000 | + +\subsection md_fenced Fenced Code Blocks + +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>: + +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 tile (~) characters on a line. The end of the block should have the +same number of tildes. Here is an example: + + + This is a paragraph introducing: + + ~~~~~~~~~~~~~~~~~~~~~ + a one-line code block + ~~~~~~~~~~~~~~~~~~~~~ + +The contents of the code block is syntax highlighted. +The default language is based on the file it was found in +(i.e. a fenced block in a Python file is assumed to be Python code). +In case the language is not clear from the context or you want to +indicate a specific language you can add the language's extension after +the opening fence: + + ~~~~~~~~~~~~~{.py} + # A class + class Dummy: + pass + ~~~~~~~~~~~~~ + +will produce: +~~~~~~~~~~~~~{.py} +# A class +class Dummy: + pass +~~~~~~~~~~~~~ + +and + + ~~~~~~~~~~~~~~~{.c} + int func(int a,int b) { return a*b; } + ~~~~~~~~~~~~~~~ + +will produce: + +~~~~~~~~~~~~~~~{.c} +int func(int a,int b) { return a*b; } +~~~~~~~~~~~~~~~ + +The curly brances and dot are optional by the way. + +\subsection md_header_id Header Id Attributes + +Standard Markdown has no support for labeling headers, which +is a problem if you want to link to a section. + +PHP Markdown Extra allows you to label a header by adding +the following to the header + + Header 1 {#labelid} + ======== + + ## Header 2 ## {#labelid2} + +To link to a section in the same comment block you can use + + [Link text](#labelid) + +to link to a section in general, doxygen allows you to use \@ref + + [Link text](@ref labelid) + +Note this only works for the headers of level 1 to 4. + +\section markdown_dox Doxygen specifics + +Even doxygen tries to following the Markdown standard as closely as +possible, there are couple of deviation and doxygen specifics additions. + +\subsection md_page_header Including Markdown files as pages + +Doxygen can process files with Markdown formatting. +For this to work the extension for such a file should +be `.md` or `.markdown` (see +\ref cfg_extension_mapping "EXTENSION_MAPPING" if your Markdown files have +a different extension, and use `md` as the name of the parser). +Each file is converted to a page (see the \ref cmdpage "page" command for +details). + +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 \ref md_header_id "here") doxygen will use that as the +page name. + +If the label is called `index` or `mainpage` doxygen will put the +documentation on the front page (`index.html`). + +Here is an example of a file `README.md` that will appear as the main page +when processed by doxygen: + + My Main Page {#mainpage} + ============ + + Documentation that will appear on the main page + +\subsection md_html_blocks Treatment of HTML blocks + +Markdown is quite strict in the way it processes block-level HTML: + +> block-level HTML elements — e.g. +> `<div>`, `<table>`, `<pre>`, `<p>`, 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. + +Doxygen does not have this requirement, and will also process +Markdown formatting inside such HTML blocks. The only exception is +`<pre>` blocks, which are passed untouched (handy for ASCII art). + +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). + +\subsection mddox_code_blocks Code Block Indentation + +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. + +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. + +In most cases this difference does not result in different output. +Only if you play with the indentation of paragraphs the difference +is noticeable: + + text + + text + + text + + code + +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. + +Note that list markers are not counted when determining the +relative indent: + + 1. Item1 + + More text for item1 + + 2. Item2 + + Code block for item2 + +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. + +\subsection mddox_code_spans Code Spans Limits + +Note that unlike standard Markdown, doxygen leaves the following untouched. + + A `cool' word in a `nice' sentence. + +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. + +\subsection mddox_lists Lists Extensions + +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. + +Example: + + - Item1 of list 1 + - Item2 of list 1 + + 1. Item1 of list 2 + 2. Item2 of list 2 + +Historically doxygen has an additional way to create numbered +lists by using `-#` markers: + + -# item1 + -# item2 + +\subsection mddox_stars Use of asterisks + +Special care has to be taken when using *'s in a comment block +to start a list or make a ruler. + +Doxygen will strip off any leading *'s from the comment before doing +Markdown processing. So although the following works fine + +@verbatim + /** A list: + * * item1 + * * item2 + */ +@endverbatim + +When you remove the leading *'s doxygen will strip the other stars +as well, making the list disappear! + +Rulers created with *'s will not be visible at all. They only work +in Markdown files. + +\subsection mddox_limits Limits on markup scope + +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. + +For code span, between the starting and ending backtick only two +new lines are allowed. + +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. + +\section markdown_debug Debugging problems + +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 \ref cmd_intro "special commands" +and \ref htmlcmds "HTML commands". +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 could lead to errors, which may not always be obvious +as they are based on the intermediate format. + +To see the result after Markdown processing you can run doxygen with the +`-d Markdown` option. It will then print each comment block before and +after Markdown processing. + +*/ |