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.

diff --git a/libstdc++-v3/doc/html/manual/documentation_hacking.html b/libstdc++-v3/doc/html/manual/documentation_hacking.html
index c978d5f3d1fa548bcc7d949809b7d8a21d480e00..bd44b61010d484c01abc0f13adc3b5a0cba76a2a 100644 (file)
--- a/libstdc++-v3/doc/html/manual/documentation_hacking.html
+++ b/libstdc++-v3/doc/html/manual/documentation_hacking.html
@@ -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">&lt;i&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;b&gt;</td><td align="left">@b word</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">@c word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;em&gt;two words or more&lt;/em&gt;</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">&lt;i&gt;</td><td align="left">@a word</td><td align="left">_word_ or *word*</td></tr><tr><td align="left">&lt;b&gt;</td><td align="left">@b word</td><td align="left">**word** or __word__</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">@c word</td><td align="left">`word`</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">@a word</td><td align="left">_word_ or *word*</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;em&gt;two words or more&lt;/em&gt;</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>

diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
index 776d5e857b53d1fb1ac876b033a33d52bc01cac4..44672f6e26d5848d4930941cc4913ea57e8c251e 100644 (file)
--- a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
+++ b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
@@ -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>&lt;i&gt;</entry>
       <entry>@a word</entry>
+      <entry>_word_ or *word*</entry>
     </row>
 
     <row>
       <entry>&lt;b&gt;</entry>
       <entry>@b word</entry>
+      <entry>**word** or __word__</entry>
     </row>
 
     <row>
       <entry>&lt;code&gt;</entry>
       <entry>@c word</entry>
+      <entry>`word`</entry>
     </row>
 
     <row>
       <entry>&lt;em&gt;</entry>
       <entry>@a word</entry>
+      <entry>_word_ or *word*</entry>
     </row>
 
     <row>
       <entry>&lt;em&gt;</entry>
       <entry>&lt;em&gt;two words or more&lt;/em&gt;</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>