On 7/2/21 12:31 PM, Eli Zaretskii wrote:
Cc: jos...@codesourcery.com, g...@gcc.gnu.org, gcc-patches@gcc.gnu.org
From: Martin Liška <mli...@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
