Re: [PATCH] Port GCC documentation to Sphinx

[Hans-Peter Nilsson <hp@bitrange.com>]

On Wed, 30 Jun 2021, Eli Zaretskii via Gcc-patches 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
> > > 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.

I'd miss them, and they're helpful when the title or term is not
familiar, when looking for a concept you know is documented in
there.

I've read the discussion downthread, but I seem to miss (a recap
of) the benefits of moving to Sphinx.  Maybe other have too and
it'd be a good idea to repeat them?  Otherwise, the impression
is not so good, as all I see is bits here and there getting lost
in translation.

brgds, H-P