Re: GCC documentation: porting to Sphinx

[Martin Liška]

On 6/1/21 3:31 PM, Michael Matz wrote:

Hello,

On Tue, 1 Jun 2021, Martin Liška wrote:


On 5/31/21 5:49 PM, Michael Matz wrote:

Hello Martin,

On Mon, 31 May 2021, Martin Liška wrote:


I've made quite some progress with the porting of the documentation and
I would like to present it to the community now:
https://splichal.eu/scripts/sphinx/
   Note the documentation is automatically ([1]) generated from texinfo with
a
GitHub workflow ([2]).


One other thing I was recently thinking about, in the Spinx vs. texinfo
discussion: locally available documentation browsable/searchable in
terminal with info(1) (or equivalents).


Yes, that's handy.


I think the above (i.e. generating .rst from the texinfo file) would
immediately nullify all my worries.  So, just to be extra sure: your
proposal now is to generate the .rst files, and that .texinfo remains
the maintained sources, right?


No, .texinfo files will be gone. However, Sphinx can output to info
format:
https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M


I see, that's good to hear.


And I've just added the generated Info pages here:
https://splichal.eu/scripts/sphinx/


Okay, but there's something amiss, just compare a local gcc.info with
that.  The sphinx generated one seems to only contain command line
options, but none of the other topics, in particular it seems to contain
the "Invoking GCC" chapter (and only that) as top-level, and all other
ones are missing (like "C implementation", "C++ implementation", "C
extension", and so on).


You are right, I reduced that to 'Invoking GCC', which is simply what 'man gcc'
presents. However, I moved that back to the entire GCC manual what you can
see now in the info page.



Looking at gccint.info I also seem quite some confusion, it's unclear to
me if content is missing or not.  But e.g. the top-level structure has a
different order (a less logical one, this one is btw. shared with the
order of the HTML generated docu, so it's probably specific to sphinx
setup or such).


Yes, the organization was bad and I fixed that. Now it's much better.

Martin



Ignoring that missing content what is there right now does seem somewhat
acceptable for local use, though.


Ciao,
Michael.

New vendor branch for RISC-V: integration and experimental branch

[Kito Cheng via Gcc]

Hi all:

I am Kito Cheng, one of the RISC-V port maintainers. I would like to
announce we have created two vendor branches for accepting unratified
extension support, in order to focus the development energy on FSF
repo.

RISC-V is an open standard instruction set architecture, many ISA
extensions are developing and are working in parallel by the RISC-V
community, many people are wanting a usable toolchain for those
unratified extensions for evaluation and/or experimental.

We try to maintain that on downstream repo which is based on github,
however it causes lots of maintenance issues, e.g. too many branches,
copyright issues, so we decide to move those developments to the FSF
after a long discussion with the RISC-V community.

# The policy for those vendor branches

Common policy for two branches:
- Based on trunk, will be rebased regularly.
- ChangeLog isn't a must, but nice to have.

Policy for integration branch:
- Accept released draft extension.

Policy for experimental branch:
- Accept working draft extension.
- If there is a released draft for the extension, please submit the
released draft extension one to the integration branch first if
possible.
- Might be rebased with the integration branch.

# What is the different between released draft extension and working
draft extension

Released draft means there is a formal release version, for example,
vector 0.10 and bitmanip 0.93 are released draft , there is tag for v
0.10 and b 0.93 and a corresponding released draft spec.

Other than that, we call that a working draft, like vector 1.0 and
bitmanip 0.94.

# How to fetch those branches
- Setup by contrib/git-fetch-vendor.sh script:
  You can use following command to enable fetching riscv branches:
 $ ./contrib/git-fetch-vendor.sh riscv

- Setup by git command:
$ git config --add remote.origin.fetch \
+refs/vendors/riscv/heads/*:refs/remotes/vendors/riscv/*
$ git config --add remote.origin.fetch \
+refs/vendors/riscv/tags/*:refs/tags/vendors/riscv/*

# Contribution
For contributors who are interested in sending patches to those
branches, you can send patches to gcc-patc...@gcc.gnu.org as normal
patch submission flow, but with [riscv/integration] or
[riscv/experimental] tag in the title.

# What if we want a stable release for integration and experimental branch

We don't have that yet, but we intend to maintain two corresponding
branches for  integration and experimental with the latest GCC release
branch in future, e.g. integration-gcc-11 and experimental-gcc-11.

Re: Update to GCC copyright assignment policy

[Mark Wielaard]

On Tue, Jun 01, 2021 at 11:05:24AM -0400, Richard Kenner wrote:
> > > What about the parts of GCC with FSF copyrights that are not covered by
> > > the GPL, but the GPL with exceptions?  How is it possible to move code
> > > between the parts if a contributor previously used DCO and thus gave
> > > only permission to license under the open source license "indicated in
> > > the file"?
> > 
> > Depends on which DCO you uses. Various project use the following DCO,
> > which makes clear you assign permissions under all applicable licenses
> > (this helps if the project uses more than one, possibly incompatible,
> > license and/or is dual licensed):
> 
> See above.  The issue is if the project wants to change the status of
> a file from GPL to GPL plus exception.  It can't do that if there
> was a change to the file made by somebody who did't assign the copyright.
> What's said in the DCO you cite doesn't help.

Right. The point wasn't so much as "here is the perfect DCO", but more
that the DCO as used for the linux kernel project might not be the
best for the GCC project given that GCC is not really a monolitic
project, but a collection of compiler/runtime modules each with their
own licence/exeception statements. So we might need tweaks for the
specific way we reuse code between modules. Or when using GPLed code
in the GFDLed manual.

Another example of a developer certificate of origin, which again
isn't a perfect fit for GCC, but which shows another way to handle
multiple licenses is the Samba one:
https://www.samba.org/samba/devel/copyright-policy.html

Cheers,

Mark

Does bootstrap make native compiler faster? Should I always use --disable-boostrap?

[sotrdg sotrdg via Gcc]

The document said yes. However, what does bootstrap actually do that can make 
compiler faster?

Sent from Mail for Windows 10

Re: Update to GCC copyright assignment policy

[Mark Wielaard]

Hi Thomas,

On Tue, Jun 01, 2021 at 12:58:12PM -0700, Thomas Rodgers wrote:
> On 2021-06-01 07:28, Mark Wielaard wrote:
> > If we no longer want the FSF to be the legal guardian and copyright
> > holder for GCC could we please find another legal entity that performs
> > that role and helps us as a project with copyleft compliance?
> 
> Personally, this would have been my preference.
> 
> > I would be happy to setup a shared copyright pool under the Conservancy
> > Copyleft Compliance project for example:
> > https://sfconservancy.org/copyleft-compliance/

It isn't too late to start discussing this as alternative. As far as I
understand the SC hasn't talked to the Conservancy yet. But the
Conservancy is happy to share their knowledge and discuss policy
issues with the GCC community if we decide we want their input.

Cheers,

Mark

[RISCV] RISC-V GNU Toolchain Biweekly Sync-up call (June 3, 2021)

[吴伟]

Hi all,

There is an agenda for tomorrow's meeting. If you have topics to
discuss or share, please let me know and I can add them to the agenda.

## Agenda:

1 [RFC] Relax the canonical order checking of arch string for -march option
https://github.com/riscv/riscv-toolchain-conventions/issues/11
2 New vendor branch for RISC-V: integration and experimental branch
https://gcc.gnu.org/pipermail/gcc/2021-June/236229.html
3 The progress of Zce,Zfinx and B,P extentions in the toolchain part.
4 The progress of CI for GNU Toolchain
5 Free discussion

https://calendar.google.com/calendar/ical/lm5bddk2krcmtv5iputjgqvoio%40group.calendar.google.com/public/basic.ics

BEIJING, China
11:00pThu, Jun 3 2021
12:00aFri, Jun 4 2021

PDT/PST, Pacific Daylight Time (US)
8:00aThu, Jun 3 2021
9:00aThu, Jun 3 2021

LONDON, United Kingdom, England
4:00pThu, Jun 3 2021
5:00pThu, Jun 3 2021

Join Zoom Meeting
https://zoom.com.cn/j/89393600951?pwd=ZFpWMkZ6Tm1TbUFXT1hZZjZZMHhRQT09

Meeting ID: 893 9360 0951
Passcode: 899662


-- 
Best wishes,
Wei Wu (吴伟)

Re: Update to GCC copyright assignment policy

[Jason Merrill via Gcc]

On Wed, Jun 2, 2021 at 4:10 AM Mark Wielaard  wrote:

> On Tue, Jun 01, 2021 at 11:05:24AM -0400, Richard Kenner wrote:
> > > > What about the parts of GCC with FSF copyrights that are not covered
> by
> > > > the GPL, but the GPL with exceptions?  How is it possible to move
> code
> > > > between the parts if a contributor previously used DCO and thus gave
> > > > only permission to license under the open source license "indicated
> in
> > > > the file"?
> > >
> > > Depends on which DCO you uses. Various project use the following DCO,
> > > which makes clear you assign permissions under all applicable licenses
> > > (this helps if the project uses more than one, possibly incompatible,
> > > license and/or is dual licensed):
> >
> > See above.  The issue is if the project wants to change the status of
> > a file from GPL to GPL plus exception.  It can't do that if there
> > was a change to the file made by somebody who did't assign the copyright.
> > What's said in the DCO you cite doesn't help.
>
> Right. The point wasn't so much as "here is the perfect DCO", but more
> that the DCO as used for the linux kernel project might not be the
> best for the GCC project given that GCC is not really a monolitic
> project, but a collection of compiler/runtime modules each with their
> own licence/exeception statements. So we might need tweaks for the
> specific way we reuse code between modules. Or when using GPLed code
> in the GFDLed manual.
>

This all seems much more of a theoretical issue than a practical one.  We
don't reuse code between the compiler and the runtimes, and the runtimes
are all either GPL3+GCC Runtime Exception or under a permissive license, so
moving code between them isn't a problem.  As far as I know, we have never
asked the FSF to relicense anything since the GPL3 move except for the
target macro documentation strings, which are easily handled by changing
them in both places at once.

Jason

Mailing list reconfiguration: VERP Sender: header affected

[Frank Ch. Eigler via Gcc]

Hi -

I made an experimental configuration change on sourceware/gcc.gnu.org
yesterday that had unforeseen effects on some mailing list
subscribers.  We turned on VERP (variable envelope return paths) on
outgoing mail from mailman, in order to assist tracking mail delivery
problems.  This changes the Sender: field that allows precise handling
of bounces, but interferes with filtering on that field.

If you use Sender:-based filtering for sorting your incoming email
stream, I suggest switching to observing List-Id: instead, or else
using a regexp/substring style of Sender: matching.

We're not sure we're keeping the new configuration yet.  It's
performing well.  With either of the two changes, you would be
immunized against change even if we return to the previous
configuration sometime.  I'm sorry about the inconvenience!

- FChE

Re: Does bootstrap make native compiler faster? Should I always use --disable-boostrap?

[Martin Jambor]

Hi,

On Wed, Jun 02 2021, sotrdg sotrdg via Gcc wrote:
> The document said yes. However, what does bootstrap actually do that can make 
> compiler faster?

Assuming the gcc you are bootstrapping is newer than your system
compiler, it is quite likely to be better able to optimize itself than
the older system compiler.

Martin

Re: Does bootstrap make native compiler faster? Should I always use --disable-boostrap?

[Martin Liška]

On 6/2/21 10:10 AM, sotrdg sotrdg via Gcc wrote:

The document said yes. However, what does bootstrap actually do that can make 
compiler faster?


Hello.

In case of openSUSE, we leverage both bootstrap-lto config with 'make 
profiledbootstrap'. That utilizes
profile-guided optimization. Moreover, when the latest compiler provides a new 
optimization, then
only using bootstrap can benefit from it.

Hope it helps,
Martin



Sent from Mail for Windows 10

Update to GCC copyright assignment policy

[Christopher Dimech via Gcc]

> Sent: Thursday, June 03, 2021 at 2:36 AM
> From: "Jason Merrill via Gcc" 
> To: "Mark Wielaard" 
> Cc: "Florian Weimer" , "gcc Mailing List" 
> 
> Subject: Re: Update to GCC copyright assignment policy
>
> On Wed, Jun 2, 2021 at 4:10 AM Mark Wielaard  wrote:
>
> > On Tue, Jun 01, 2021 at 11:05:24AM -0400, Richard Kenner wrote:
> > > > > What about the parts of GCC with FSF copyrights that are not covered
> > by
> > > > > the GPL, but the GPL with exceptions?  How is it possible to move
> > code
> > > > > between the parts if a contributor previously used DCO and thus gave
> > > > > only permission to license under the open source license "indicated
> > in
> > > > > the file"?
> > > >
> > > > Depends on which DCO you uses. Various project use the following DCO,
> > > > which makes clear you assign permissions under all applicable licenses
> > > > (this helps if the project uses more than one, possibly incompatible,
> > > > license and/or is dual licensed):
> > >
> > > See above.  The issue is if the project wants to change the status of
> > > a file from GPL to GPL plus exception.  It can't do that if there
> > > was a change to the file made by somebody who did't assign the copyright.
> > > What's said in the DCO you cite doesn't help.
> >
> > Right. The point wasn't so much as "here is the perfect DCO", but more
> > that the DCO as used for the linux kernel project might not be the
> > best for the GCC project given that GCC is not really a monolitic
> > project, but a collection of compiler/runtime modules each with their
> > own licence/exeception statements. So we might need tweaks for the
> > specific way we reuse code between modules. Or when using GPLed code
> > in the GFDLed manual.
> >
>
> This all seems much more of a theoretical issue than a practical one.  We
> don't reuse code between the compiler and the runtimes, and the runtimes
> are all either GPL3+GCC Runtime Exception or under a permissive license, so
> moving code between them isn't a problem.  As far as I know, we have never
> asked the FSF to relicense anything since the GPL3 move except for the
> target macro documentation strings, which are easily handled by changing
> them in both places at once.
>
> Jason

In my experience, the theoretical problem you claim is a real problem.  When
everything is assigned to the FSF any technical use problems (license 
compatibility)
could be legally solved very simply by re-licensing to whatever is appropriate
because the FSF owned the copyright.

With the change, contributors got to be extremely careful on how they use and
license code.  And it is very easy for people to screw things up for them and 
others.

Computer Science schools continue to produce graduates lacking practice 
competency and
new skills required in using legal instruments in the market economy.  And I 
have seen
lawyers that spent the bulk of their practice years with technology, yet 
continue
to suffer from hangovers that are the residual of a professional life spent 
primarily
among other lawyers who practiced in a different era.

Be prepared for a lot of trouble if you want developers to handle licensing 
independently.
My recommendation has been to continue with the current system of copyright 
assignment
to a single entity.  And only allow the use of additional contributions for 
unique and
special situations that arise.  Because there could be a time where you would 
not be
able to use that piece of code.  The biggest problem is loosing the right to 
distribution.
The distribution right is problematic in all sorts of ways.  You would then 
need to re-code
a lot of things again.  That has happened to me before.

So I would say that if you can transfer the copyright, do it.

- Christopher Dimech

Society has become too quick to pass judgement and declare someone
Persona Non-Grata, the most extreme form of censure a country can
bestow.

In a new era of destructive authoritarianism, I support Richard
Stallman.  Times of great crisis are also times of great
opportunity.  I call upon you to make this struggle yours as well !

https://stallmansupport.org/
https://www.fsf.org/ https://www.gnu.org/

Re: GCC documentation: porting to Sphinx

[Joel Sherrill]

For RTEMS, we switched from texinfo to Sphinx and the dependency
on Python3 for Sphinx has caused a bit of hassle. Is this going to be
an issue for GCC?

Also we rely on TexLive for PDF output and that's a bit of a pain to
install. Tex was incorrectly packaged on some RHEL/CentOS versions.

This ignores a couple of plugins we use that I don't expect GCC to use.

It works great but the host dependencies are sometimes a pain. We've
ended up writing host OS specific advice/howto's to address this. Any
expectations on host pain versus the pretty painless texinfo?

Thanks.

--joel
RTEMS

On Wed, Jun 2, 2021 at 2:37 AM Martin Liška  wrote:

> On 6/1/21 3:31 PM, Michael Matz wrote:
> > Hello,
> >
> > On Tue, 1 Jun 2021, Martin Liška wrote:
> >
> >> On 5/31/21 5:49 PM, Michael Matz wrote:
> >>> Hello Martin,
> >>>
> >>> On Mon, 31 May 2021, Martin Liška wrote:
> >>>
>  I've made quite some progress with the porting of the documentation
> and
>  I would like to present it to the community now:
>  https://splichal.eu/scripts/sphinx/
> Note the documentation is automatically ([1]) generated from
> texinfo with
>  a
>  GitHub workflow ([2]).
> >>>
> >>> One other thing I was recently thinking about, in the Spinx vs. texinfo
> >>> discussion: locally available documentation browsable/searchable in
> >>> terminal with info(1) (or equivalents).
> >>
> >> Yes, that's handy.
> >>
> >>> I think the above (i.e. generating .rst from the texinfo file) would
> >>> immediately nullify all my worries.  So, just to be extra sure: your
> >>> proposal now is to generate the .rst files, and that .texinfo remains
> >>> the maintained sources, right?
> >>
> >> No, .texinfo files will be gone. However, Sphinx can output to info
> >> format:
> >>
> https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M
> >
> > I see, that's good to hear.
> >
> >> And I've just added the generated Info pages here:
> >> https://splichal.eu/scripts/sphinx/
> >
> > Okay, but there's something amiss, just compare a local gcc.info with
> > that.  The sphinx generated one seems to only contain command line
> > options, but none of the other topics, in particular it seems to contain
> > the "Invoking GCC" chapter (and only that) as top-level, and all other
> > ones are missing (like "C implementation", "C++ implementation", "C
> > extension", and so on).
>
> You are right, I reduced that to 'Invoking GCC', which is simply what 'man
> gcc'
> presents. However, I moved that back to the entire GCC manual what you can
> see now in the info page.
>
> >
> > Looking at gccint.info I also seem quite some confusion, it's unclear to
> > me if content is missing or not.  But e.g. the top-level structure has a
> > different order (a less logical one, this one is btw. shared with the
> > order of the HTML generated docu, so it's probably specific to sphinx
> > setup or such).
>
> Yes, the organization was bad and I fixed that. Now it's much better.
>
> Martin
>
> >
> > Ignoring that missing content what is there right now does seem somewhat
> > acceptable for local use, though.
> >
> >
> > Ciao,
> > Michael.
> >
>
>

Re: Update to GCC copyright assignment policy

[Jason Merrill via Gcc]

On Wed, Jun 2, 2021 at 4:18 AM Mark Wielaard  wrote:

> Hi Thomas,
>
> On Tue, Jun 01, 2021 at 12:58:12PM -0700, Thomas Rodgers wrote:
> > On 2021-06-01 07:28, Mark Wielaard wrote:
> > > If we no longer want the FSF to be the legal guardian and copyright
> > > holder for GCC could we please find another legal entity that performs
> > > that role and helps us as a project with copyleft compliance?
> >
> > Personally, this would have been my preference.
> >
> > > I would be happy to setup a shared copyright pool under the Conservancy
> > > Copyleft Compliance project for example:
> > > https://sfconservancy.org/copyleft-compliance/
>
> It isn't too late to start discussing this as alternative. As far as I
> understand the SC hasn't talked to the Conservancy yet. But the
> Conservancy is happy to share their knowledge and discuss policy
> issues with the GCC community if we decide we want their input.
>

This seems to me a complement rather than an alternative; some Linux
developers use the Conservancy copyleft services while contributing under
the DCO, and some GCC developers could do the same.

Jason

Re: GCC documentation: porting to Sphinx

[Joseph Myers]

On Wed, 2 Jun 2021, Joel Sherrill wrote:

> For RTEMS, we switched from texinfo to Sphinx and the dependency
> on Python3 for Sphinx has caused a bit of hassle. Is this going to be
> an issue for GCC?

What Sphinx (and, thus, Python) versions does the GCC manual build work 
with?  Can it work with e.g. any Sphinx versions from the past five years, 
or are there newer Sphinx features that are critical for the GCC manuals?  
I've seen a need for frequent Sphinx updates being a pain when building 
other software using Sphinx for its manual.

> Also we rely on TexLive for PDF output and that's a bit of a pain to
> install. Tex was incorrectly packaged on some RHEL/CentOS versions.

This is nothing new, since building PDF manuals from Texinfo sources also 
needs TeX.

-- 
Joseph S. Myers
jos...@codesourcery.com

Re: GCC documentation: porting to Sphinx

[Joseph Myers]

On Mon, 31 May 2021, Martin Liška wrote:

> https://splichal.eu/scripts/sphinx/

Looking at some examples there:

https://splichal.eu/scripts/sphinx/gcc/_build/html/c-implementation-defined-behavior/preprocessing-directives.html
 
has some conversion problems:

* "See Implementation-defined behavior, for details of these aspects of 
implementation-defined behavior." is missing the link to the relevant 
section of the cpp manual that's present in the Texinfo source.

* "` character before the :samp:`" is a misconversion (whether from 
Texinfo to RST or from RST to HTML) of the Texinfo source

  @samp{\} character before the @samp{\}

which will need to be fixed.

* The corresponding PDF has the same issues as above (so probably they are 
issues with the conversion to RST, not with Sphinx itself).  In addition, 
the PDF manual ought to be using fixed-width fonts for literal code, 
command-line options, etc., just like the HTML manual, and the 
Texinfo-generated PDF manual, are.

https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/passing-options-to-the-assembler.html
 
shows headings such as "-Wa,option, -Wa".  The ", -Wa" doesn't make sense, 
this option is just "-Wa,option".

https://splichal.eu/scripts/sphinx/gcc/_build/html/gcov-a-test-coverage-program.html
 
has a hyphen between "gcov" and "a Test Coverage Program" in the heading.  
It should be an em dash, as in Texinfo.

https://splichal.eu/scripts/sphinx/gcc/_build/html/language-standards-supported-by-gcc/c%2B%2B-language.html
 
has doubled slashes in various URLs where the Texinfo source has /@/ 
(Texinfo @/ means "allow line break", it should not be translated to /).

https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/machine-dependent-options/aarch64-options.html
 
shows different formatting for the headings for "-mlow-precision-div, 
-mno-low-precision-div" and "-mtrack-speculation -mno-track-speculation".  
The formatting should be identical.  The only difference in the Texinfo 
source seems to be that the latter is missing @opindex directives.  And 
while it's a bug in the Texinfo source that those directives are missing, 
the presence or absence of index entries should not affect the formatting 
of the documentation for those options.

On that same page, the output for -march=name is broken, containing a 
literal :samp:{feature} (in general, checking for any places where RST 
directives such as :samp: appear in the HTML output might be a good idea 
to look for broken conversions).  The Texinfo source here has

@option{-march=@var{arch}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}

(where the use of @r{...} is to put the {}[]* characters in a 
variable-width font, since they are not literally part of the option, 
while the other characters that are literally part of the option should be 
in a variable-width font).

https://splichal.eu/scripts/sphinx/gcc/_build/html/language-standards-supported-by-gcc/references-for-other-languages.html
 
has literal unconverted "@c man" and "@include" and other Texinfo 
directives.  Searching for such things in the HTML output (or the RST 
sources) is a good idea, just like searching for literal RST directives in 
the HTML output, to find other such conversion bugs.

https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options.html 
says "See option-index", another case with a link that didn't get 
converted properly.  It also has raw :samp: uses indicating a 
misconversion.

I'm not sure how you're determining languages for code-block, but 
https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-control-diagnostic-messages-formatting.html
 
certainly shows some cases where they have been misidentified (e.g. random 
C++ keywords highlighted in the default GCC_COLORS, some JSON being 
highlighted as such but other JSON not).

> - a shared content is factored out ([4])
> - conditional build is fully supported (even for shared parts)
> - manual pages look reasonable well
> - folders are created for files which have >= 5 TOC tree entries
> - various formatting issues were resolved
> - baseconf.py reads BASE-VER, DEV-PHASE, .. files

Could you give more detailed descriptions of how each of the various 
issues I listed in 2015 are addressed here?

https://gcc.gnu.org/legacy-ml/gcc-patches/2015-11/msg01139.html

> I've got couple of questions:
> 
> 1) Do we have to you the following cover text?
>Copyright (c) 1988-2020 Free Software Foundation, Inc.
> 
>Permission is granted to copy, distribute and/or modify this document
> under the terms of the GNU Free Documentation License, Version 1.3 or any
> later version published by the Free Software Foundation; with the Invariant
> Sections being "GNU General Public
>License" and "Funding Free Software", the Front-Cover texts being (a)
> (see below), and with the Back-Cover Texts being (b) (see below).  A copy of
> the license is included in the gfdl(7) man page.
> 
>(a) The

Re: GCC documentation: porting to Sphinx

[Martin Sebor via Gcc]

On 5/31/21 7:25 AM, Martin Liška wrote:

Hello.

I've made quite some progress with the porting of the documentation and
I would like to present it to the community now:
https://splichal.eu/scripts/sphinx/


Just a few issues I noticed in the warnings section:

The headings of some warnings mention the same option twice (e.g.,
-Wabi, -Wabi, -Wno-abi;  -Wdouble-promotion, -Wdouble-promotion,
-Wno-double-promotion;  -Winit-self, -Winit-self, -Wno-init-self).
This looks like a pretty pervasive problem.

Mentioning the -Wno-xxx option is redundant in a heading for -Wxxx.

The headings of some other warnings also mention options that are
only remotely related to them.  E.g., -Wformat has all these:

  -Wformat, -Wno-format, -ffreestanding, -fno-builtin, -Wformat=

(I see the same problem in the attributes section where the headings
for some attributes include option names).

That seems quite puzzling.  I assume it's a consequence of having
index entries for the related options, but I don't think making
them visible in the headings is helfpful.

Headings that in the manual today include a level like

  -Wformat-overflow
  -Wformat-overflow=level

don't mention the level in the Spinx manual:

  -Wformat-overflow, -Wno-format-overflow

When the /level/ is then discussed in the rest of the text it's
not clear what it refers to.

Martin



Note the documentation is automatically ([1]) generated from texinfo 
with a GitHub workflow ([2]).
It's built on the devel/sphinx GCC branch which I periodically with the 
master branch. One can

see the current source .rst files here: [3].

Changes made since the last time:
- a shared content is factored out ([4])
- conditional build is fully supported (even for shared parts)
- manual pages look reasonable well
- folders are created for files which have >= 5 TOC tree entries
- various formatting issues were resolved
- baseconf.py reads BASE-VER, DEV-PHASE, .. files

I've got couple of questions:

1) Do we have to you the following cover text?
    Copyright (c) 1988-2020 Free Software Foundation, Inc.

    Permission is granted to copy, distribute and/or modify this 
document under the terms of the GNU Free Documentation License, Version 
1.3 or any later version published by the Free Software Foundation; with 
the Invariant Sections being "GNU General Public
    License" and "Funding Free Software", the Front-Cover texts 
being (a) (see below), and with the Back-Cover Texts being (b) (see 
below).  A copy of the license is included in the gfdl(7) man page.


    (a) The FSF's Front-Cover Text is:

     A GNU Manual

    (b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation 
raise

     funds for GNU development.

2) Do we want to generate fsf-funding, gpl and gfdl manual pages?
3) Do we want to preserve the current strange copy mechanism for 
./gcc/doc/tm.texi.in ?

4) Do we want a copyright header for the created .rst files?

Thoughts?
Thanks,
Martin

[1] https://github.com/davidmalcolm/texi2rst
[2] https://github.com/davidmalcolm/texi2rst/actions
[3] https://github.com/marxin/texi2rst-generated/tree/master/sphinx
[4] https://github.com/marxin/texi2rst-generated/tree/master/sphinx/share