From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 3D4FB388B69C; Tue, 15 Nov 2022 11:36:39 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 3D4FB388B69C DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1668512199; bh=k+n4osmaF78akXosbSOtTJtM2+BZvp5bo+5D/YaGudY=; h=From:To:Subject:Date:From; b=qZ7UDsqUGOXttrI8E83oQX8mVhcBfewxBVWcPWpSjppe/OngAJHyaVr/iXdQi2aul qK/95Ro3H7mily0GJolhRgnI3L4Ks6hmT0Q2hNM2i/snsINPpuSePGos8TVXuyJeLr tVFAKo9wqPU8VGSppt1tFkR6viTq+u0xi/B0nnpg= MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r13-4056] libstdc++: Document use of Markdown for Doxygen comments X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: f5f2686b2cbfddba39035312e8f7704d4d822e89 X-Git-Newrev: d34dea05f8e9af3e85c45067bad9990c0040946d Message-Id: <20221115113639.3D4FB388B69C@sourceware.org> Date: Tue, 15 Nov 2022 11:36:39 +0000 (GMT) List-Id: https://gcc.gnu.org/g:d34dea05f8e9af3e85c45067bad9990c0040946d commit r13-4056-gd34dea05f8e9af3e85c45067bad9990c0040946d Author: Jonathan Wakely 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 pool_size variable in the configuration file texmf.cnf may - need to be increased by a minimum factor of two. + need to be increased by a minimum factor of two. Alternatively, using + LATEX_CMD=lualatex might allow the docs to be + build without running out of memory.

Generating the Doxygen Files

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 stl_iterator.h for a good example of the “other” kind of grouping.

- 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.)

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. -

Table B.2. HTML to Doxygen Markup Comparison

HTMLDoxygen
\\\
"\"
'\'
<i>@a word
<b>@b word
<code>@c word
<em>@a word
<em><em>two words or more</em>

Docbook

Prerequisites

Table B.3. Docbook Prerequisites

ToolVersionRequired By
docbook5-style-xsl1.76.1all
xsltproc1.1.26all
xmllint2.7.7validation
dblatex0.3pdf output
pdflatex2007-59pdf output
docbook2X0.8.8info output
epub3 stylesheetsb3epub output

- Editing the DocBook sources requires an XML editor. Many +

Table B.2. HTML to Doxygen Markup Comparison

HTMLDoxygenMarkdown
\\\\\
"\"\"
'\'\'
<i>@a word_word_ or *word*
<b>@b word**word** or __word__
<code>@c word`word`
<em>@a word_word_ or *word*
<em><em>two words or more</em>_two words or more_

Docbook

Prerequisites

Table B.3. Docbook Prerequisites

ToolVersionRequired By
docbook5-style-xsl1.76.1all
xsltproc1.1.26all
xmllint2.7.7validation
dblatex0.3pdf output
pdflatex2007-59pdf output
docbook2X0.8.8info output
epub3 stylesheetsb3epub output

+ An XML editor is recommended for editing the DocBook sources. Many exist: some notable options include emacs, Kate, or Conglomerate. @@ -386,8 +391,8 @@ build directory, based on the output format. For instance, the HTML docs will be in doc/docbook/html.

- The 

doc-html-docbook-regenerate

target will generate - the HTML files and copy them back to the libstdc++ source tree. + The doc-html-docbook-regenerate 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.

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 pool_size variable in the configuration file texmf.cnf may - need to be increased by a minimum factor of two. + need to be increased by a minimum factor of two. Alternatively, using + LATEX_CMD=lualatex might allow the docs to be + build without running out of memory. @@ -515,9 +517,12 @@ - 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.) @@ -595,6 +600,7 @@ HTML Doxygen + Markdown @@ -602,41 +608,49 @@ \ \\ + \\ " \" + \" ' \' + \' <i> @a word + _word_ or *word* <b> @b word + **word** or __word__ <code> @c word + `word` <em> @a word + _word_ or *word* <em> <em>two words or more</em> + _two words or more_ @@ -719,7 +733,7 @@ - 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 emacs, Kate, or Conglomerate. @@ -815,8 +829,8 @@ - The doc-html-docbook-regenerate target will generate - the HTML files and copy them back to the libstdc++ source tree. + The doc-html-docbook-regenerate 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.