RFC: Sphinx for GCC documentation

[Tobias Burnus]

Hello,

On 13.05.21 13:45, Martin Liška wrote:
> On 4/1/21 3:30 PM, Martin Liška wrote:
>> That said, I'm asking the GCC community for a green light before I
>> invest
>> more time on it?
> So far, I've received just a small feedback about the transition. In
> most cases positive.
>
> [1] https://splichal.eu/scripts/sphinx/

The HTML output looks quite nice.

What I observed:

* Looking at
   https://splichal.eu/scripts/sphinx/gfortran/_build/html/intrinsic-procedures/access-checks-file-access-modes.html
why is the first argument description in bold?
It is also not very readable to have a scollbar there – linebreaks would be better.
→ I think that's because the assumption is that the first line contains a header
   and the rest the data

* https://splichal.eu/scripts/sphinx/gfortran/_build/latex/gfortran.pdf
   If I look at page 92 (alias 96), 8.2.13 _gfortran_caf_sendget, the first column
   is too small to fit the argument names. – Admittedly, the current gfortran.pdf
   is not much better – it is very tight but just fits. I don't know how to fix this.

* I note that we write before the argument index, that those are without -/-- prefix
   but that's not true. Something to fix after the conversation.

* The syntax highlighting for gfortran is odd. Looking at @smallexample:
- intrinsic.texi: All Fortran examples (F90/free-form)
- gfc-internals.texi: 4x Fortran, 4x C, 3x plain text
- gfortran.texi: Shell, Fortran, C, plain text.
- invoke.texi: 4x Shell, 2x C, 4x Fortran
Does not seem to be that simple, but it would be nice if at least all in
intrinsic.texi would be marked as Fortran.

Actually, I do not quite understand when the output is formatted a C (wrongly
or rightly) as Fortran (rarely but correctly) as plain or in some odd formatting
which randomly highlights some examples.
Possibly also an item for after the conversion.

Tobias

-----------------
Mentor Graphics (Deutschland) GmbH, Arnulfstrasse 201, 80634 München Registergericht München HRB 106955, Geschäftsführer: Thomas Heurung, Frank Thürauf