Re: [PATCH] Doxygenate gdbtypes.h

[Stan Shebs <stanshebs@earthlink.net>]

On 3/4/14 11:15 AM, Eli Zaretskii wrote:
>> Date: Tue, 04 Mar 2014 11:03:48 -0800
>> From: Stan Shebs <stanshebs@earthlink.net>
>>
>>> Just because some GNU packages use Doxygen (or CMake, or...) doesn’t
>>> mean it’s a good idea; and it remains a GCS violation.
>>
>> Paragraph and sentence, please?
> 
>>From the "GNU Manuals" node:
> 
>    The preferred document format for the GNU system is the Texinfo
>    formatting language.  Every GNU package should (ideally) have
>    documentation in Texinfo both for reference and for learners.  Texinfo
>    makes it possible to produce a good quality formatted book, using TeX,
>    and to generate an Info file.  It is also possible to generate HTML
>    output from Texinfo source.  See the Texinfo manual, either the
>    hardcopy, or the on-line version available through `info' or the Emacs
>    Info subsystem (`C-h i').
> 
>       Nowadays some other formats such as Docbook and Sgmltexi can be
>    converted automatically into Texinfo.  It is ok to produce the Texinfo
>    documentation by conversion this way, as long as it gives good results.


In this context, it's important that the standard says "preferred", not
"required".  As we've been discussing since last August, writing
internals documentation as a separate manual in Texinfo has not worked
out for GDB.  Fortunately, the general coding standards do allow
projects to set their own additional practices, where such changes
do not contradict any explicit requirements set down by the FSF.

Stan
stan@codesourcery.com