Re: [PATCH] Port GCC documentation to Sphinx

[Eli Zaretskii <eliz@gnu.org>]

> From: Richard Sandiford <richard.sandiford@arm.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  gcc@gcc.gnu.org,  gcc-patches@gcc.gnu.org,  joseph@codesourcery.com
> Date: Mon, 05 Jul 2021 10:17:38 +0100
> 
> Hans-Peter Nilsson <hp@bitrange.com> writes:
> > 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.
> 
> Better cross-referencing is one big feature.

See below: the Info format has some features in addition to
cross-references that can make this a much smaller issue.  HTML has
just the cross-references, so "when you are a hammer, every problem
looks like a nail".

> IMO this subthread has demonstrated why the limitations of info
> formatting have held back the amount of cross-referencing in the
> online html.

I disagree with this conclusion, see below.

> (And based on emperical evidence, I get the impression that far more
> people use the online html docs than the info docs.)

HTML browsers currently lack some features that make Info the format
of choice for me when I need to use the documentation efficiently.
The most important feature I miss in HTML browsers is the index
search.  A good manual usually has extensive index (or indices) which
make it very easy to find a specific topic one is looking for,
i.e. use the manual as a reference (as opposed as a first-time
reading, when you read large portions of the manual in sequence).

Another important feature is regexp search across multiple sections
(with HTML you'd be forced to download the manual as a single large
file for that, and then you'll probably miss regexps).

Yet another feature which, when needed, is something to kill for, is
the "info apropos" command, which can search all the manuals on your
system and build a menu from the matching sections found in different
manuals.  And there are a few more.

(Texinfo folks are working on JavaScript code to add some missing
capabilities to Web browsers, but that effort is not yet complete.)

> E.g. quoting from Richard's recent patch:
> 
>   @item -fmove-loop-stores
>   @opindex fmove-loop-stores
>   Enables the loop store motion pass in the GIMPLE loop optimizer.  This
>   moves invariant stores to after the end of the loop in exchange for
>   carrying the stored value in a register across the iteration.
>   Note for this option to have an effect @option{-ftree-loop-im} has to 
>   be enabled as well.  Enabled at level @option{-O1} and higher, except 
>   for @option{-Og}.
> 
> In the online docs, this will just be plain text.  Anyone who doesn't
> know what -ftree-loop-im is will have to search for it manually.

First, even if there are no cross-references, manual search is not the
best way.  It is much easier to use index-search:

  i ftree TAB

will display a list of options that you could be after, and you can
simply choose from the list, or type a bit more until you have a
single match.

Moreover, adding cross-references is easy:

  @item -fmove-loop-stores
  @opindex fmove-loop-stores
  Enables the loop store motion pass in the GIMPLE loop optimizer.  This
  moves invariant stores to after the end of the loop in exchange for
  carrying the stored value in a register across the iteration.
  Note for this option to have an effect @option{-ftree-loop-im}
  (@pxref{Optimize Options, -ftree-loop-im}) 
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  has be enabled as well.  Enabled at level @option{-O1} and higher,
  except for @option{-Og}.

If this looks like too much work, a simple Texinfo macro (two, if you
want an anchor where you point) will do.

> Adding the extra references to the html (and pdf) output but dropping
> them from the info sounds like a good compromise.

But that's not what happens.  And besides, how would you decide which
cross-references to drop and which to retain in Info?