Re: [PATCH] Port GCC documentation to Sphinx

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

On 7/1/21 5:06 PM, Michael Matz wrote:
> 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.

Sure. What's new is that Sphinx can generate much more cross references, like
option references from option listing.

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

These are auto-numbered. Theoretically one can use the verbose anchor names:

@anchor{demo cmdoption-Wshift-overflow3}@anchor{e}@anchor{demo cmdoption-wshift-overflow3}@anchor{f}
@deffn {Option} @w{-}Wshift@w{-}overflow3=n, @w{-}Wshift@w{-}overflow3

Default option value for @ref{e,,-Wshift-overflow3}.

But these would lead to even longer '*note -Wshift-overflow3: demo cmdoption-wshift-overflow3' output.

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

Yes, we can theoretically block emission of @refs for options.

Martin

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