Announcement: Porting the Docs to Sphinx - 9. November 2022

[Joseph Myers]

On Thu, 20 Oct 2022, Martin Liška wrote:

> > Could generated man and info pages be provided as a tarball on
> > gcc.gnu.org or ftp.gnu.org?
> 
> Not planning doing that.

Release tarballs (but not snapshots) currently include the info files and 
man pages, via gcc_release running a build with 
--enable-generated-files-in-srcdir before building the tarball.

I think they should continue to do so.  This means:

(a) --enable-generated-files-in-srcdir needs to cause those files to be 
generated in the source directory, as it does at present.

(b) gcc_release, for building a release but not a snapshot, needs to give 
an error if Sphinx is missing or too old and so those files weren't built 
properly (and thus people running gcc_release to build a release tarball 
will need new-enough Sphinx).

(c) It needs to be verified that building and installing from such a 
release tarball works even if Sphinx is missing or too old - that is, that 
it installs the prebuilt info / man files rather than giving an error or 
failing to install them.

Also, but not strictly part of the release issue:

(d) Builds with missing or old Sphinx should work regardless of whether 
such files are in the source directory - but if they aren't in the source 
directory, the effect of missing or old Sphinx (detected at configure 
time) should be to disable building and installing documentation.

-- 
Joseph S. Myers
joseph@codesourcery.com