mirror of
https://gcc.gnu.org/git/gcc.git
synced 2024-11-23 10:54:07 +08:00
libstdc++: Document use of Markdown for Doxygen comments
libstdc++-v3/ChangeLog: * doc/xml/manual/documentation_hacking.xml: Document use of Markdown for Doxygen comments. Tweak formatting. * doc/html/manual/documentation_hacking.html: Regenerate.
This commit is contained in:
Jonathan Wakely
parent
f5f2686b2c
commit
d34dea05f8
@ -135,7 +135,9 @@
|
||||
formatting system, and will require the expansion of TeX's memory
|
||||
capacity. Specifically, the <code class="literal">pool_size</code>
|
||||
variable in the configuration file <code class="filename">texmf.cnf</code> may
|
||||
need to be increased by a minimum factor of two.
|
||||
need to be increased by a minimum factor of two. Alternatively, using
|
||||
<strong class="userinput"><code>LATEX_CMD=lualatex</code></strong> might allow the docs to be
|
||||
build without running out of memory.
|
||||
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p>
|
||||
The following Makefile rules run Doxygen to generate HTML
|
||||
docs, XML docs, XML docs as a single file, PDF docs, and the
|
||||
@ -269,9 +271,12 @@
|
||||
purpose. See <code class="filename">stl_iterator.h</code>
|
||||
for a good example of the <span class="quote">“<span class="quote">other</span>”</span> kind of grouping.
|
||||
</p><p>
|
||||
Please use markup tags like @p and @a when referring to things
|
||||
such as the names of function parameters. Use @e for emphasis
|
||||
when necessary. Use @c to refer to other standard names.
|
||||
Markdown can be used for formatting text. Doxygen is configured to
|
||||
support this, and it is a good compromise between readable comments
|
||||
in the C++ source and nice formatting in the generated HTML.
|
||||
Please format the names of function parameters in either code font
|
||||
or italics. Use underscores or @e for emphasis when necessary.
|
||||
Use backticks or @c to refer to other standard names.
|
||||
(Examples of all these abound in the present code.)
|
||||
</p><p>
|
||||
Complicated math functions should use the multi-line format.
|
||||
@ -322,8 +327,8 @@
|
||||
writing Doxygen comments. Single and double quotes, and
|
||||
separators in filenames are two common trouble spots. When in
|
||||
doubt, consult the following table.
|
||||
</p><div class="table"><a id="table.doxygen_cmp"></a><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table class="table" summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td></tr><tr><td align="left"><i></td><td align="left">@a word</td></tr><tr><td align="left"><b></td><td align="left">@b word</td></tr><tr><td align="left"><code></td><td align="left">@c word</td></tr><tr><td align="left"><em></td><td align="left">@a word</td></tr><tr><td align="left"><em></td><td align="left"><em>two words or more</em></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"></a>Docbook</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="table.docbook_prereq"></a><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table class="table" summary="Docbook Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">docbook5-style-xsl</td><td align="center">1.76.1</td><td align="center">all</td></tr><tr><td align="center">xsltproc</td><td align="center">1.1.26</td><td align="center">all</td></tr><tr><td align="center">xmllint</td><td align="center">2.7.7</td><td align="center">validation</td></tr><tr><td align="center">dblatex</td><td align="center">0.3</td><td align="center">pdf output</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr><tr><td align="center">docbook2X</td><td align="center">0.8.8</td><td align="center">info output</td></tr><tr><td align="center">epub3 stylesheets</td><td align="center">b3</td><td align="center">epub output</td></tr></tbody></table></div></div><br class="table-break" /><p>
|
||||
Editing the DocBook sources requires an XML editor. Many
|
||||
</p><div class="table"><a id="table.doxygen_cmp"></a><p class="title"><strong>Table B.2. HTML to Doxygen Markup Comparison</strong></p><div class="table-contents"><table class="table" summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th><th align="left">Markdown</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td><td align="left">\'</td></tr><tr><td align="left"><i></td><td align="left">@a word</td><td align="left">_word_ or *word*</td></tr><tr><td align="left"><b></td><td align="left">@b word</td><td align="left">**word** or __word__</td></tr><tr><td align="left"><code></td><td align="left">@c word</td><td align="left">`word`</td></tr><tr><td align="left"><em></td><td align="left">@a word</td><td align="left">_word_ or *word*</td></tr><tr><td align="left"><em></td><td align="left"><em>two words or more</em></td><td align="left">_two words or more_</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="doc.docbook"></a>Docbook</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><div class="table"><a id="table.docbook_prereq"></a><p class="title"><strong>Table B.3. Docbook Prerequisites</strong></p><div class="table-contents"><table class="table" summary="Docbook Prerequisites" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /><col align="center" class="c3" /></colgroup><thead><tr><th align="center">Tool</th><th align="center">Version</th><th align="center">Required By</th></tr></thead><tbody><tr><td align="center">docbook5-style-xsl</td><td align="center">1.76.1</td><td align="center">all</td></tr><tr><td align="center">xsltproc</td><td align="center">1.1.26</td><td align="center">all</td></tr><tr><td align="center">xmllint</td><td align="center">2.7.7</td><td align="center">validation</td></tr><tr><td align="center">dblatex</td><td align="center">0.3</td><td align="center">pdf output</td></tr><tr><td align="center">pdflatex</td><td align="center">2007-59</td><td align="center">pdf output</td></tr><tr><td align="center">docbook2X</td><td align="center">0.8.8</td><td align="center">info output</td></tr><tr><td align="center">epub3 stylesheets</td><td align="center">b3</td><td align="center">epub output</td></tr></tbody></table></div></div><br class="table-break" /><p>
|
||||
An XML editor is recommended for editing the DocBook sources. Many
|
||||
exist: some notable options
|
||||
include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>,
|
||||
or <span class="application">Conglomerate</span>.
|
||||
@ -386,8 +391,8 @@
|
||||
build directory, based on the output format. For instance, the
|
||||
HTML docs will be in <code class="filename">doc/docbook/html</code>.
|
||||
</p><p>
|
||||
The </p><pre class="screen">doc-html-docbook-regenerate</pre><p> target will generate
|
||||
the HTML files and copy them back to the libstdc++ source tree.
|
||||
The <strong class="userinput"><code>doc-html-docbook-regenerate</code></strong> target will
|
||||
generate the HTML files and copy them back to the libstdc++ source tree.
|
||||
This can be used to update the HTML files that are checked in to
|
||||
version control.
|
||||
</p><p>
|
||||
|
||||
@ -286,7 +286,9 @@
|
||||
formatting system, and will require the expansion of TeX's memory
|
||||
capacity. Specifically, the <literal>pool_size</literal>
|
||||
variable in the configuration file <filename>texmf.cnf</filename> may
|
||||
need to be increased by a minimum factor of two.
|
||||
need to be increased by a minimum factor of two. Alternatively, using
|
||||
<userinput>LATEX_CMD=lualatex</userinput> might allow the docs to be
|
||||
build without running out of memory.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
@ -515,9 +517,12 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Please use markup tags like @p and @a when referring to things
|
||||
such as the names of function parameters. Use @e for emphasis
|
||||
when necessary. Use @c to refer to other standard names.
|
||||
Markdown can be used for formatting text. Doxygen is configured to
|
||||
support this, and it is a good compromise between readable comments
|
||||
in the C++ source and nice formatting in the generated HTML.
|
||||
Please format the names of function parameters in either code font
|
||||
or italics. Use underscores or @e for emphasis when necessary.
|
||||
Use backticks or @c to refer to other standard names.
|
||||
(Examples of all these abound in the present code.)
|
||||
</para>
|
||||
|
||||
@ -595,6 +600,7 @@
|
||||
<row>
|
||||
<entry>HTML</entry>
|
||||
<entry>Doxygen</entry>
|
||||
<entry>Markdown</entry>
|
||||
</row>
|
||||
</thead>
|
||||
|
||||
@ -602,41 +608,49 @@
|
||||
<row>
|
||||
<entry>\</entry>
|
||||
<entry>\\</entry>
|
||||
<entry>\\</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>"</entry>
|
||||
<entry>\"</entry>
|
||||
<entry>\"</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>'</entry>
|
||||
<entry>\'</entry>
|
||||
<entry>\'</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><i></entry>
|
||||
<entry>@a word</entry>
|
||||
<entry>_word_ or *word*</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><b></entry>
|
||||
<entry>@b word</entry>
|
||||
<entry>**word** or __word__</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><code></entry>
|
||||
<entry>@c word</entry>
|
||||
<entry>`word`</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><em></entry>
|
||||
<entry>@a word</entry>
|
||||
<entry>_word_ or *word*</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><em></entry>
|
||||
<entry><em>two words or more</em></entry>
|
||||
<entry>_two words or more_</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
|
||||
@ -719,7 +733,7 @@
|
||||
</table>
|
||||
|
||||
<para>
|
||||
Editing the DocBook sources requires an XML editor. Many
|
||||
An XML editor is recommended for editing the DocBook sources. Many
|
||||
exist: some notable options
|
||||
include <command>emacs</command>, <application>Kate</application>,
|
||||
or <application>Conglomerate</application>.
|
||||
@ -815,8 +829,8 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <screen>doc-html-docbook-regenerate</screen> target will generate
|
||||
the HTML files and copy them back to the libstdc++ source tree.
|
||||
The <userinput>doc-html-docbook-regenerate</userinput> target will
|
||||
generate the HTML files and copy them back to the libstdc++ source tree.
|
||||
This can be used to update the HTML files that are checked in to
|
||||
version control.
|
||||
</para>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user