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

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?

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