Re: [PATCH] Port GCC documentation to Sphinx

[Richard Sandiford <richard.sandiford@arm.com>]

Eli Zaretskii <eliz@gnu.org> writes:
>> 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.)

Whether info or HTML is the better format isn't the issue though.  The
point is that we do have HTML output that is (emperically) widely used.
And at the moment it isn't as good as it could be.

The question that I was replying to was: what is the benefit of moving
to Sphinx?  And one of the answers is that it improves the HTML output.

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

Here too I was talking about this being plain text in the online docs,
i.e. in the HTML.

In HTML the user-friendly way of letting users answer the question
“what on earth is -ftree-loop-im” is to have “-ftree-loop-im” be a
hyperlink that goes straight to the documentation of the option.
Same for PDF when viewed digitally.

One of the things that the move to Sphinx does is give us those
hyperlinks.

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

But this would be redundant in HTML: “foo (see foo)”.

Also, the benefit of hyperlinks in HTML (not info) is that they can be
used outside of prose, such as in lists, without interrupting the flow.

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

Not in the original patch, sure, but it's what I think Martin was
suggesting as a compromise (maybe I misunderstood).  The comment above
was supposed to be in support of doing that.

It sounds like those who use the info format (which includes me btw,
at least occasionally) are happy with the status quo in terms of which
links are present.  So the new links could be a non-info-only feature.

Thanks,
Richard