Re: [groff] 22/127: [build]: Install PDF documents better.

[G. Branden Robinson]

Hi Colin,

At 2023-07-10T11:08:22+0100, Colin Watson wrote:
> On Mon, Jul 10, 2023 at 04:30:24AM -0400, G. Branden Robinson wrote:
> > commit 838a36711cff1daff2ac01abf0462b3d24a74aac
> > Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> > AuthorDate: Mon Apr 3 23:23:24 2023 -0500
> > 
> >     [build]: Install PDF documents better.
> >     
> >     Ship only one copy of "automake.pdf", and install it and the new
> >     "groff-man-pages.pdf" in the "pdf/" subdirectory of the
> >     destination "doc" directory.
> 
> This is belated, but does it actually make sense to install
> automake.pdf at all?

I could make a (feeble?) defense of it as...uh...yet another example of
how to write nice looking documents using the mom package.  Yeah, that's
the ticket!

> It seems to be entirely aimed at people working on the groff code base
> itself; I can't see any reason it would be interesting to include it
> in "make install".

The reason is pretty much because GNU Automake infrastructure for
managing documentation is baroque.  Automake regards documentation as
"special" in ways that don't apply to other sorts of build artifacts.
(One of the aspects most annoying to me is that there's a separate
"install-doc" target that emplaces things not handled by "install".  I
find this offensively wrong-headed.)  Part of the rococo architecture,
as far as I can tell, is due to its assumption that Texinfo will be
responsible for generating documentation files (except for man pages,
which I reckon it utterly ignored for many years as a matter of high
principle).[1]  This is a problem for us because we want to generate
many of the same output formats that Texinfo does, and treat them as
package documentation, but _not_ employ the built-in rules that Automake
provides for generating such formats with Texinfo.

Ingo and I both fought ferociously with these issues over the course of
the 1.23.0 release cycle;

  $ git diff 1.22.4 1.23.0 doc/doc.am

is somewhat revealing of this, and

  $ git log -p 1.22.4..1.23.0 doc/doc.am

exposes the full horror.  And as can be seen in the batch of commits to
which you're replying, things still weren't perfect.

So, other things being equal, I'd kind of prefer to leave automake.pdf
resting delicately where it is.  Two installed copies of it is too much
to tolerate, hence the subject of this mail.  But one?  That won't
_kill_ any users, will it?  ;-)

That said, if someone has an easy and _well-tested_ patch (esp. WRT
both in-tree and out-of-tree build configurations) that stops
automake.pdf from being shipped without disrupting installation of our
other PDF documentation, I'd be fine with that.

Regards,
Branden

[1] 
https://web.archive.org/web/20041029135801/https://www.gnu.org/prep/standards/html_node/Man-Pages.html

signature.asc
Description: PGP signature