Re: [PATCH] Port GCC documentation to Sphinx

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

On 6/30/21 3:09 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: Wed, 30 Jun 2021 12:11:03 +0200
>>
>>> (Admittedly, Emacs by default hides some of the text of a
>>> cross-reference, but not hiding them in this case produces an even
>>> less legible text.)
>>
>> If I'm correct, it's exactly what's documented in Sphinx FAQ here:
>> https://www.sphinx-doc.org/en/master/faq.html#displaying-links
>>
>> and there's a suggested Emacs code snippet that should help with links.
>> Does it help?
> 
> 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.
About ‘=iso9899:1990’, yes, it's a :samp: and how it's wrapper by Sphinx by default.

> 
> The quotes around the option values don't help.
> 
> Also, using the method proposed by Sphinx FAQ would need a change in
> Emacs, which will take time to propagate.  So my suggestion is to
> minimize the use of such "inline" hyperlinks.
> 
>>>     ‘@`file'’
>>>
>>>          Read command-line options from ‘`file'’.  The options read are
>>>          inserted in place of the original ‘@`file'’ option.  If ‘`file'’
>>>          does not exist, or cannot be read, then the option will be treated
>>>          literally, and not removed.
>>
>> I can confirm that, so e.g.
>> Show :samp:`Samp with a {variable}.`
>>
>> is transformed into:
>> Show @code{Samp with a @emph{variable}.}
>>
>> Default info formatting is selected as:
>>
>> @definfoenclose strong,`,'
>> @definfoenclose emph,`,'
>>
>> 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.

> 
>>> 4. Menus lost the short descriptions of the sub-sections.  Example:
>>>
>>>     * Designated Initializers
>>>     * Case Ranges
>>>     * Cast to a Union Type
>>>     * Mixed Declarations, Labels and Code
>>>     * Declaring Attributes of Functions
>>>
>>> vs
>>>
>>>     * Designated Inits::    Labeling elements of initializers.
>>>     * Case Ranges::         'case 1 ... 9' and such.
>>>     * Cast to Union::       Casting to union type from any member of the union.
>>>     * Mixed Declarations::  Mixing declarations and code.
>>>     * Function Attributes:: Declaring that functions have no side effects,
>>> 			  or that they can never return.
>>>
>>> Looks like some bug to me.
>>>
>>> Note also that nodes are now called by the same name as the section,
>>> which means node names generally got much longer.  Is that really a
>>> good idea?
>>
>> Well, I intentionally removed these and used simple TOC tree links
>> which take display text for a section title.
> 
> I would suggest to discuss these decisions first, perhaps on the
> Texinfo mailing list?  I'm accustomed to these short descriptions, but
> I'm not sure how important they are for others.

Well, it was decision done during the transition of texinfo files into Sphinx.
I don't see why it should be discussed in Texinfo community.

Cheers,
Martin