[committed] libstdc++: Document use of Markdown for Doxygen comments

[committed] libstdc++: Document use of Markdown for Doxygen comments

[Jonathan Wakely]

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>&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>
-- 
2.38.1