Re: [PATCH] Port GCC documentation to Sphinx

[Eli Zaretskii <eliz@gnu.org>]

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

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

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