Git snapshot tarballs, multiple-pass formatting, and pdfmom (was: groff 1.25.0.rc1 testing)

--nreyxjtpaydztqxm
Content-Type: text/plain; protected-headers=v1; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
Subject: Git snapshot tarballs, multiple-pass formatting, and pdfmom (was:
 groff 1.25.0.rc1 testing)
MIME-Version: 1.0

Hi Phong,

At 2026-07-22T11:18:56+0900, Nguy=E1=BB=85n Gia Phong wrote:
> On 2026-07-21 at 02:00-05:00, G. Branden Robinson wrote:
> > At 2026-07-21T15:32:53+0900, Nguy=E1=BB=85n Gia Phong wrote:
> > > the .git directory shall be removed, hence the following won't
> > > work.
> > >
> > > On 2026-07-21 at 00:40-05:00, G. Branden Robinson wrote:
> > > > Earlier in the file.
> > > >
> > > > $ nl -ba Makefile.am | sed -n 509,509p
> > > >    509  # 'VERSION' is generated by gnulib script git-version-gen
> >
> > The .version file is not placed in the ".git" directory,
> > but the root of the build tree
>=20
> I was referring to the git-version-gen script, which needs .git to
> determine the current tag/commit.

Ah.  In that case your build is neither fish nor fowl: neither a build
=66rom a distribution archive, nor a build from a Git working copy,
because there is no working copy.

What is the rationale for this sort of build configuration?

We've had problems supporting that sort of thing in the past.

https://lists.gnu.org/archive/html/groff/2022-06/msg00001.html

The consensus at that time was not to support them, hence the disabled
"snapshot tarballs" via Savannah's cgit interface.

> On 2026-07-21 at 02:00-05:00, G. Branden Robinson wrote:
> > At 2026-07-21T15:32:53+0900, Nguy=E1=BB=85n Gia Phong wrote:
> > > I've resulted to writing to .tarball-version instead and the build
> > > and tests succeeded.  Please let me know if this has any
> > > unintended effect.
> >
> > None that I know of, but I'm nervous about the practice.  If your
> > build from the repository is failing to properly populate
> > ".version", I'm strongly interested to know the failure mode.
>=20
> IIUC, both .version and .tarball-version comes from $VERSION,
> which in turn is derived from the current Git HEAD in .git.

Ultimately, yes.

> TBH manually populating a version file is not unusual practice in
> Guix, though it'd be lovely if the configure script excepts a
> --version=3D...  override flag.  If that sounds good, I don't expect it
> in 1.25, and can offer a patch.

Hmm.  If it's that easy, why isn't this already standard practice in
projects using Autoconf?  Or is it, and I haven't noticed?

> On 2026-07-21 at 02:00-05:00, G. Branden Robinson wrote:
> Similar to Nix, Guix build things in isolated environment, so there
> would not be the host's roff unless it's absolutely necessary (e.g.
> compiler bootstrapping).

Yes, that's pretty common practice among distributors.  My usual build
environment is not especially lean, but I have one that is.  I don't use
it frequently, though, as we saw...  :-/

> Speaking of cross compilation, it has been broken since at most 1.24
> as pdfmom used to build doc/automake.pdf uses test-groff
> instead of GROFFBIN, I think:
>=20
>     $ make GROFF_BIN_PATH=3D... GROFFBIN=3D.../bin/groff
>     ...
>       GROFF    doc/automake.pdf
>     sh: line 1: test-groff: command not found
>     pdfmom: fatal error: test-groff exited with status 127
>     make[2]: *** [Makefile:19211: doc/automake.pdf] Error 1
>     ...
>     $ grep -r -B1 -A3 GROFF_COMMAND=3Dtest-groff
>     contrib/mom/mom.am-MOMPDFMOM =3D \
>     contrib/mom/mom.am:  GROFF_COMMAND=3Dtest-groff \
>     contrib/mom/mom.am-  GROFF_COMMAND_PREFIX=3D \
>     contrib/mom/mom.am-  GROFF_BIN_PATH=3D"$(GROFF_BIN_PATH)" \
>     contrib/mom/mom.am-  $(PDFMOMBIN) $(FFLAG) $(MFLAG) -M$(mom_srcdir) -=
K utf8 -p -e -t \
>     --
>     doc/doc.am-DOC_PDFMOM =3D \
>     doc/doc.am:  GROFF_COMMAND=3Dtest-groff \
>     doc/doc.am-  GROFF_COMMAND_PREFIX=3D \
>     doc/doc.am-  GROFF_BIN_PATH=3D"$(GROFF_BIN_PATH)" \
>     doc/doc.am-  $(PDFMOMBIN) $(MFLAG) $(FFLAG) -ww -b $(pdfmomoption) --=
roff

Yes.  Unfortunately the more places we interpose pdfmom in front of
groff, the more problems like this we have.

But if you're going to have forward references, there seems to be no
alternative at present.  It's not even a new problem; see mmroff(1).

Once upon a time I devised a script called "griddle"[1] to manage a
CMake-based project such that it kept re-running CMake's configuration
step until it stablized.  It worked, but it was one of several bad
tastes that CMake left in my mouth.

pdfmom(1) is growing increasingly poorly named in any event; it need not
format a mom(7) document, and the problem of forward references does not
uniquely afflict PDF generation, either.

Maybe we should reconsider the tool's scope and purpose, rename it, say,
"regroff", and supply a "test-regroff" script, generated at
configuration time as "test-groff" is.

(Once upon a time, Bjarni lobbied for a "test-nroff" script, but found
no one to second his motion.)

I'd like to avoid doing what TeX does (or what its usual front-end
does), and do what appears to be multi-pass formatting even when it's
not necessary.  Or maybe it _doesn't_ apply multiple passes
unnecessarily, but its ordinary operation is so garrulous that I
struggle to tell the difference.

In the short term, if "automake.mom" doesn't actually need multi-pass
formatting, then we should move it back to `GROFFBIN`.  I don't see any
forward references; the relocated table of contents in the PDF rendering
doesn't count, because that's achieved by PDF-level page resequencing
magic.

Regards,
Branden

[1] https://docs.sel4.systems/updates/buildsystem/11.0.x.html

    Good grief, that's a lot of typos.  I wonder what happened...

--nreyxjtpaydztqxm
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmpgL2AACgkQ0Z6cfXEm
bc5OjA//Vo103aj9sL71qpTBOpPksjyl3gCKbjQDJ0hgnURlZ97ClPtTu/cdMaXY
1DSciFI0PWbsZETwm/n4hgu+67LbaUkdvTdCJ9i5/wda3YI/W8TTLYwYlemthn8C
KBafmJwc5qRnFbRlX0g0KFfhp5MpjqcovhC0vLCmBSbgxLDyBsi2TJqYxDJXcQln
kiL83IzXkGqwWa24+31DrXx81P+or1emYf4LWsQ6OuSW93P8grMS5KUwSDnUIYSY
2MAmWfQ2WjhjMdM6AFVXuq8T2fFwE2Fkf03FSxxWmXbk1wUjH1bUvxC1YlkmMY8b
wQ0uxJCNGbZJAITGr2AxcELfwwS2A+cGEkqGIMBWEIfxjyhyt7G6b++YDESmpEHb
LPJwxRiImMBX/4apuaknEWiT2WMYDjn23RTeJuClWodOaU4g5/XFxJPMFHMOgk0M
dokbyO8AjtIFO+qaj9Ufe8jihA5m++uzRW55M82BjhD/7jK7a9rICRzEO+4eN2Eo
raLmY9dd6pJRe8+z83o+F6YSIooDFuCnymdRmy8aEPeIzil47u1hebBjMzdb/o75
wXB+6paPRExkrZOJ9Kfe8yMQ7Sxv9q0m7wyYzxHckZXDSUmvN+3PVnIclGMQNIFL
n8RtyuySofLH1lBTE1dkOphQ6bQcmoCj5bRs1AaDSflH7hR5bxE=
=z4t0
-----END PGP SIGNATURE-----

--nreyxjtpaydztqxm--