public inbox for libstdc++-cvs@sourceware.org
help / color / mirror / Atom feed
* [gcc r13-4056] libstdc++: Document use of Markdown for Doxygen comments
@ 2022-11-15 11:36 Jonathan Wakely
0 siblings, 0 replies; only message in thread
From: Jonathan Wakely @ 2022-11-15 11:36 UTC (permalink / raw)
To: gcc-cvs, libstdc++-cvs
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>
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2022-11-15 11:36 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-11-15 11:36 [gcc r13-4056] libstdc++: Document use of Markdown for Doxygen comments Jonathan Wakely
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).