Re: RFC: Sphinx for GCC documentation

[Michael Matz <matz@suse.de>]

Hello,

On Wed, 7 Apr 2021, Martin Liška wrote:

> > I like the output quite a bit, especially that things like option
> > references are automagically linked to their documentation.  I spent
> > just a bit of time looking through the HTML and PDF above and found
> > a few minor issues.  I suspect they're due to the conversion script
> > not being finished yet but just to confirm please see below.
> 
> Exactly, the script is supposed to do 99% of the transition automatically,
> the rest needs a manual intervention.
> 
> > 
> > Is the source we'd work with the same as what shows up when I click
> > the 'View page source' link?  (Or is there some preprocessing involved?)
> 
> Yes, it's the source as is.

I think doing that might be a mistake.  I do like the end result quite 
much (ignoring things missing, like @itemx), no doubt, but if the .rst 
files are the sources then we loose something: they contain markup to 
describe presentation ("make this bold/italic/a list").  The .texi files 
(want to) contain markup to describe meaning ("this is an 
chapter/section/option/attribute/code").  The former can always be 
generated from the latter, the other direction is not possible.  For 
maintaining and writing documentation it's usually better (because more 
future proof) to describe meaning.  (I'm aware that our .texi files don't 
completely adhere to that ideal and also contain quite some presentation 
markup)

Random snippet for what I mean: the .texi contains:

"The @code{access} attribute specifies that a function to whose 
by-reference arguments the attribute applies accesses the referenced 
object according to @var{access-mode}.  The @var{access-mode} argument is 
required and must be"

the .rst has:

"The ``access`` attribute specifies that a function to whose by-reference 
arguments the attribute applies accesses the referenced object according 
to :samp:`{access-mode}`.  The :samp:`{access-mode}` argument is required 
and must be"

So, @code{}/@var{} vs. `` `` / :samp:``.  Keeping in mind that 
documentation also needs to be written it's inconceivable why there should 
be such difference in expressing code vs var markup in .rst.  
Now, you could say, just use `` in the .rst file, it's rendered the same 
anyway; but then the distinction gets lost.

(Again, I'm aware that the .texi files aren't perfect here, and @code/@var 
also seems a bit forced :) )

(I'm not proposing we go the full extreme of semantic markup that docbook 
tries, but the other end of the spectrum, i.e. markdown/rst with only 
presentation markup, also doesn't seem very well fitting)

One other practical concern: it seems there's a one-to-one correspondence 
of .rst files and (web)page.  Do we really want to maintain hundreds (or 
how many?) .rst files, instead of 60 .texi files?


Ciao,
Michael.