From: Jonathan Wakely <jwakely@redhat.com>
To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org
Subject: [committed] libstdc++: Document use of Markdown for Doxygen comments
Date: Tue, 15 Nov 2022 11:37:13 +0000 [thread overview]
Message-ID: <20221115113713.1131991-1-jwakely@redhat.com> (raw)
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(-)
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>
--
2.38.1
reply other threads:[~2022-11-15 11:37 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=20221115113713.1131991-1-jwakely@redhat.com \
--to=jwakely@redhat.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=libstdc++@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: link
Be 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).