Re: [PATCH] Port GCC documentation to Sphinx

[Michael Matz <matz@suse.de>]

Hello,

On Thu, 1 Jul 2021, Martin Liška wrote:

> On 7/1/21 3:33 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: Thu, 1 Jul 2021 14:44:10 +0200
> > > 
> > > > It helps some, but not all of the issues disappear.  For example,
> > > > stuff like this is still hard to read:
> > > > 
> > > >     To select this standard in GCC, use one of the options -ansi
> > > >                                                            -----
> > > >     -std.‘=c90’ or -std.‘=iso9899:1990’
> > > >     ----           ----
> > > 
> > > If I understand the notes correct, the '.' should be also hidden by e.g.
> > > Emacs.
> > 
> > No, it doesn't.  The actual text in the Info file is:
> > 
> >     *note -std: f.‘=iso9899:1990’
> > 
> > and the period after " f" isn't hidden.  Where does that "f" come from
> > and what is its purpose here? can it be removed (together with the
> > period)?
> 
> It's name of the anchor used for the @ref. The names are automatically
> generated
> by makeinfo. So there's an example:
> 
> This is the warning level of @ref{e,,-Wshift-overflow3} and …
> 
> becomes in info:
> This is the warning level of *note -Wshift-overflow3: e. and …
> 
> I can ask the question at Sphinx, the Emacs script should hide that.

Not everyone reads info within Emacs; even if there's an emacs solution to 
postprocess info pages to make them nicer we can't rely on that.  It must 
look sensible without that.  In this case it seems that already the 
generated .texinfo input to makeinfo is bad, where does the 'e' (or 'f') 
come from?  The original texinfo file simply contains:

  @option{-std=iso9899:1990}

so that's what perhaps should be generated, or maybe the anchor in @ref is 
optional and could be left out if it doesn't provide any info (a single 
character as anchor doesn't seem very useful)?

> > > > > We can adjust 'emph' formatting to nil, what do you think?
> > > > 
> > > > Something like that, yes.  But the problem is: how will you format it
> > > > instead?  The known alternatives, _foo_ and *foo* both use punctuation
> > > > characters, which will get in the way similarly to the quotes.  Can
> > > > you format those in caps, like makeinfo does?
> > > 
> > > You are fully right, info is very simple format and it uses wrapping for
> > > the formatting
> > > purpose (by default * and _). So, I don't have any elegant solution.
> > 
> > Well, it sounds from another mail that you did find a solution: to
> > up-case the string in @var.
> 
> I don't know. Some of them can be e.g. keywords and using upper-case 
> does not seem to me feasible.

Then that needs to be different already in the input, so that the 
directive that (in info) capitalizes is only used in contexts where that 
makes sense.  People reading info pages will know that an all-caps word 
often means a syntactic variable/placeholder, so that should be preserved.


Ciao,
Michael.