Re: [PATCH] Port GCC documentation to Sphinx

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

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.  IMO this subthread has
demonstrated why the limitations of info formatting have held back
the amount of cross-referencing in the online html.  (And based on
emperical evidence, I get the impression that far more people use
the online html docs than the info docs.)

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.

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

Thanks,
Richard