[committed] libstdc++: Document use of Markdown for Doxygen comments
Commit Message
Pushed to trunk.
-- >8 --
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.
---
.../html/manual/documentation_hacking.html | 21 ++++++++------
.../doc/xml/manual/documentation_hacking.xml | 28 ++++++++++++++-----
2 files changed, 34 insertions(+), 15 deletions(-)
@@ -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>