RFC: Sphinx for GCC documentation

Tobias Burnus tobias@codesourcery.com
Fri Jun 4 07:55:07 GMT 2021


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


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

More information about the Gcc-patches mailing list