Re: [PATCH] Port GCC documentation to Sphinx

["Martin Liška" <mliska@suse.cz>]

On 7/2/21 12:31 PM, Eli Zaretskii wrote:
>> Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org
>> From: Martin Liška <mliska@suse.cz>
>> Date: Fri, 2 Jul 2021 11:30:02 +0200
>>
>>> So the purpose of having the comma there is to avoid having a period
>>> in the middle of a sentence, which is added by makeinfo (because the
>>> Info readers need that).  Having a comma there may seem a bit
>>> redundant, but having a period will definitely look like a typo, if
>>> not confuse the heck out of the reader, especially if you want to use
>>> these inline cross-references so massively.
>>
>> Well, then it's a bug in Makeinfo.
> 
> No, it isn't a bug in makeinfo.  It's a (mis)feature of the Info
> format: a cross-reference needs to have a punctuation character after
> it, so that Info readers would know where's the end of the node/anchor
> name to which the cross-reference points.  Info files are largely
> plain-ASCII files, so the Info readers need help in this case, and
> makeinfo produces what they need.

Indeed. Agree that Info format is legacy format with very limited capability
of a formatting.

> 
>>>> What type of conversions and style are going to change with conversion to Sphinx?
>>>
>>> Anything that is different from the style conventions described in the
>>> Texinfo manual.  We have many such conventions.
>>
>> Which is supposed to be here:
>> https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation
>> right?
>>
>> I've just the text. About the shortening of section names in a TOC. I couldn't find
>> it in the GNU Documentation manual.
> 
> No, there's also a lot of style guidelines in the Texinfo manual
> itself.  Basically, the documentation of almost every Texinfo
> directive includes some style guidelines, and there are also sections
> which are pure guidelines, like the nodes "Conventions", "Node Names",
> "Structuring Command Types", and some others.

You are right, it's mentioned in "Node Names". Anyway, I declare it as a minor
regression to the current format.

> 
>>>> Again, please show up concrete examples. What you describe is very theoretical.
>>>
>>> We've already seen one: the style of writing inline cross-references
>>> with the equivalent of @ref.  We also saw another: the way you
>>> converted the menus.  It is quite clear to me that there will be
>>> others.  So I'm not sure why you need more evidence that this could be
>>> a real issue.
>>
>> As explained, @ref are generated by Makeinfo in a strange way.
>> About the menus, I was unable to find it..
> 
> See the node "Menu Parts" in the Texinfo manual.  If you look at other
> GNU manuals, you will see that it is a de-facto standard to provide
> most menu items with short descriptions.
> 
>>> But maybe all of this is intentional: maybe the GCC project
>>> consciously and deliberately decided to move away of the GNU
>>> documentation style and conventions, and replace them with whatever
>>> the Sphinx and RST conventions are?  In that case, there's no reason
>>> for me to even mention these aspects.
>>
>> My intention is preserving status quo as much as possible.
> 
> Well, but you definitely deviated from the status quo, and it sounds
> like you did that deliberately, without any discussion.
> 
>> On the other hand, Sphinx provides quite some nice features why I wanted to use it.
> 
> Which features are those?
> 

Feel free to read this email discussion, it's mentioned there multiple times what are
main benefits of the transition.

Cheers,
Martin