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.
