public inbox for libstdc++-cvs@sourceware.org help / color / mirror / Atom feed
From: Jonathan Wakely <redi@gcc.gnu.org> To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r13-4056] libstdc++: Document use of Markdown for Doxygen comments Date: Tue, 15 Nov 2022 11:36:39 +0000 (GMT) [thread overview] Message-ID: <20221115113639.3D4FB388B69C@sourceware.org> (raw) https://gcc.gnu.org/g:d34dea05f8e9af3e85c45067bad9990c0040946d commit r13-4056-gd34dea05f8e9af3e85c45067bad9990c0040946d Author: Jonathan Wakely <jwakely@redhat.com> Date: Tue Nov 15 11:34:46 2022 +0000 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: --- .../doc/html/manual/documentation_hacking.html | 21 +++++++++------- .../doc/xml/manual/documentation_hacking.xml | 28 ++++++++++++++++------ 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/libstdc++-v3/doc/html/manual/documentation_hacking.html b/libstdc++-v3/doc/html/manual/documentation_hacking.html index c978d5f3d1f..bd44b61010d 100644 --- 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"><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> diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml index 776d5e857b5..44672f6e26d 100644 --- 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><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>
reply other threads:[~2022-11-15 11:36 UTC|newest] Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20221115113639.3D4FB388B69C@sourceware.org \ --to=redi@gcc.gnu.org \ --cc=gcc-cvs@gcc.gnu.org \ --cc=libstdc++-cvs@gcc.gnu.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).