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

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

Hi Phong,

At 2026-07-22T14:33:33+0900, Nguy=E1=BB=85n Gia Phong wrote:
> On 2026-07-21 at 21:48-05:00, G. Branden Robinson wrote:
> > Ah.  In that case your build is neither fish nor fowl: neither a
> > build from 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?
>=20
> The rationals for avoiding the dist archives on Guix were discussed
> in the following thread.
>=20
> https://yhetil.org/guix-devel/[email protected]/T

Yes.  I see that's quite extensive.  But only from March of this year;
unless Guix moves super-fast, the project may still be finding its
direction in this area.  On the other hand, groff can be (and maybe is)
fairly deep in the dependency stack.  I've given consideration to
supporting a "bootstrapping profile" of groff that builds only what is
needed to generate, say, man pages for terminal viewing.  Not building
anything in contrib/, or anything written in Perl, would drop groff's
own build dependencies to something near minimal: C, C++, and their
standard libraries.

Probably some other stuff I'm not thinking of at the moment, but not a
great deal.  Over the years I've revised the configuration summary to
disclose the most prominent dependency issues.

Here's an example (don't look too close, it's from a failing build):

GNU roff version 1.25.0.rc1.23-3984c8 configuration summary
----------------------------------------------------------------------
 installation directory prefix    : /home/branden/groff-HEAD
 C++ compiler and options         : clang++ -std=3Dc++98 -g -O2
 C compiler and options           : clang -std=3Dc99 -std=3Dgnu11 -g -O2
 Perl interpreter version         : 5.32.1
 Ghostscript command              : gs
 URW fonts directory              : /usr/share/fonts/type1/urw-base35/
 gropdf service level             : full
 X11 support                      : enabled
 X11 app defaults directory       : /home/branden/groff-HEAD/lib/X11/app-de=
faults
 default paper format             : letter
 'groff -l' uses print spooler    : lpr
 preconv can use uchardet library : yes
 can build groff.{info,html,txt}  : yes
 can build groff.{dvi,pdf}        : yes
----------------------------------------------------------------------

Distributors routinely shut off X11 support, for example.  I think
Debian turns off the spooler support.  That or Colin Watson and I merely
discussed the possibility.

In the "bootstrapping profile" I envision, you could probably stop
reading after "C compiler and options".

I've done no work on this.  It's just a spitball idea.  No one's asked
for it.

> In brief, (1) generated configure and Makefile are considered
> build artifacts,

=46rom the thread I see that the ChangeLog often is too.  :-/

Not in groff's case.  Ours is hand-maintained.  And I mean to keep it
that way.  I need a place I can fix errors in the engineering log, and
"git log" is immutable so it is unsuitable.

> which goes against the principle of building from (and thus patching)
> the preferred form for modification,

I disagree with your (or whoever's) interpretation of this principle.

Copyleft requires the provision of the preferred form for modification
_as a sufficiency condition_.  It does _not_ forbid the distributor from
including auxiliary or supplementary materials that they think might be
of aid.  Under the foregoing interpretation, writing a helpful email to
accompany a GPLv3 section 6 source disclosure violates the principle.

I think such a claim would be absurd.

There are defensible _technical_ arguments for having "artifact-free"
source distributions.  If someone's venturing the notion, I ask you to
carry back to the Guix folks the proposition that padding their case
brief with a suggestion that supplementing source distributions with
artifacts violates the principle of copyleft (or the GPL itself) is a
terrible idea.

Full disclosure: I'm just some guy, but I'm some guy who served on GPLv3
Committee A.

https://web.archive.org/web/20220908213717/https://meetings-archive.debian.=
net/pub/debian-meetings/2006/debconf6/slides/GPLv3_and_Debian-Don_Armstrong=
/gplv3_talk_paper.pdf

> and (2) version-controled archives are more friendly to Software
> Heritage (content-addressed VCS archives).
>=20
> (Guix does have content-addressed file archives for tarballs, but our
> infra is limited, and the distro-agnostic one called ERIS is still
> under development.  Neither is publicly financed in long term like
> Software Heritage.)

I'll take your word for it.  This sounds like another crack at the
long-standing problem of the "software bill of materials", originally
pursued for license compliance (or avoidance) reasons.  But it largely
got shelved by the big firms that were working on it, I suppose because
(a) it was a cost, not a profit, center; (b) there was only one case
like FSF v. Linksys, and since others didn't materialize for several
years, firms decided that the downside risk of license noncompliance was
nearly zero; (c) technological efforts in this area were distorted by
companies like Black Duck that wanted to hype the fear of downside risk
in license noncompliance so as to draw revenue to themselves; and (d)
the Linux Foundation not very subtly suggested that no company ever had
to fear a lawsuit over GPL violations involving the Linux kernel as long
as said company ponied up an LF membership fee.  (Ah, the beauty of a
501(c)6 cartel.)

In turn, the rest of Big Software outside of the Linux kernel realized
there was no point messing with copylefts anymore at all--not even ones
"protected" from the GPL by incompatibility (see Netscape PL, Mozilla
PL, CDDL, IBMPL/Eclipse PL).  Just follow the Linux Foundation's example
by setting up a 501(c)6, establish a Contributor License Agreement (CLA)
such that anyone who doesn't pony up a membership fee retains no rights
in their work, and promulgate a Code of Conduct to silence and/or expel
anyone who complains or impertintently questions the way you do
business.

Such organizations get run with little accountability or transparency,
because they were never meant to be governed by their user, or even
developer enthusiast communities, but by insiders who hew closely to the
priorities of their employers, and conduct their business unminuted in
private Discord chats, Zoom calls, and similar.

This approach to governance is good for keeping project management
"lean", responsive to directives from platinum members' C-suites, and
untroubled by the concerns of the community one serves--a tedious
distraction from producing "value" for one's management chain--but also
tends to suffer from classic problems like the meeting's attendees
departing without a consensus understanding of just what was decided,
and moreover, without even being aware that consensus was lacking.

That's how you get debacles like the 2023 RustConf keynote talk that
didn't happen.

https://github.com/rust-lang/foundation-faq-2020/issues/12
https://www.sophiajt.com/why-i-left-rust/
https://blog.rust-lang.org/2023/05/29/RustConf/

> As for removing the .git directory, it is for the reproducibility
> of the checkout directory, as there can be new objects not relevant
> to the commit of interest in future clones.

That seems like a tautologous statement to me.  Any clone of a future
line of development is going to have new deltas (in old-fashioned
SCCS/RCS parlance) or content-addressable "blobs" (in Git parlance).

I don't claim there isn't a good reason for scrubbing ./.git, but what
you said was not intelligible to me.

> On 2026-07-21 at 21:48-05:00, G. Branden Robinson wrote:
> > 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.
> >
> > At 2026-07-22T11:18:56+0900, Nguy=E1=BB=85n Gia Phong wrote:
> > > 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?
>=20
> I don't know if it will be easy, I was offerring a hand
> understanding it is not a high priority for Groff.

I understand, and I appreciate it.  The only assessment of priority I
want to make at this time is to defer this problem for consideration for
the groff 1.25.0 release.  If I can.  The collective view of the
subscribers to this list might differ.

> From the linked thread, how about hardcoding in configure.ac the
> `build-aux/git-version-gen --fallback' version?  This can be done
> every time a new version number is added to the NEWS file.

That's not a bad idea.  We're down to only 2 places where a hand update
is required, and one of those is going to be essential anyway.  If I can
fix the other case, then we'd still be no worse off.

I seem to remember we fooled with `--fallback` in that 2022 groff
thread, though, and ran into problems.  Something to do with gnulib...??

> On 2026-07-21 at 21:48-05:00, G. Branden Robinson wrote:
> >  At 2026-07-22T11:18:56+0900, Nguy=E1=BB=85n Gia Phong wrote:
> > > 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:
[...]
> > 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. [...]
> >
> > 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.
>=20
> Thanks, am I understanding correctly that if multi-pass formatting
> (or any formatting at all) must be done to-be-built groff et al,
> it has to be disabled under cross-compilation?

I _think_ that's correct.  But the only reason, as far as I know, is
that we haven't written our tooling carefully enough to handle this
scenario.  As Ingo Schwarze likes to point out, groff manifests wrappers
upon wrappers.  The groff(1) command's whole point is to be one.

"nroff" wraps "groff".

"mmroff" wraps "groff".

"test-groff" wraps "groff".

"pdfmom" wraps "groff".

"groffer" used to wrap "groff", or maybe sometimes "pdfmom", or "should"
have, but I am relieved that we were able to dispose of groffer.

> I am guessing that it is okay to build the PROCESSEDDOCFILES with
> Groff of the same version (but different e.g. architecture),

Yes.  _Nothing_ about the translation of *roff input to
device-independent output ("grout") should be machine-dependent unless
the author of the input deliberately injects host-dependent data.

=2Epso cat /proc/cpuinfo

> so could GROFF_COMMAND within an invocation of make be ensured to be
> GROFFBIN _if_ the latter is provided?

I _think_ so.  `GROFF_COMMAND` is used only a few places, and in these
the oversight or neglect of considering cross-compilation scenarios
would be completely mine.

contrib/mom/mom.am:  GROFF_COMMAND=3Dtest-groff \
doc/doc.am:  GROFF_COMMAND=3Dtest-groff \
src/utils/pdfmom/pdfmom.pl:$groff=3D$ENV{GROFF_COMMAND} if exists ($ENV{GRO=
FF_COMMAND});
tmac/tests/an_MR-internal-hyperlinks-work-with-pdfmom.sh:  | GROFF_COMMAND=
=3D"$groff" "$pdfmom" --roff -rU1 -man -Z | nl -ba)
tmac/tests/andoc_internal-hyperlinks-work-with-pdfmom.sh:  | GROFF_COMMAND=
=3D"$groff" "$pdfmom" --roff -rU1 -mandoc -Z | nl -ba)
tmac/tests/andoc_internal-hyperlinks-work-with-pdfmom.sh:  | GROFF_COMMAND=
=3D"$groff" "$pdfmom" --roff -rU1 -mandoc -Z | nl -ba)
tmac/tests/doc_Xr-internal-hyperlinks-work-with-pdfmom.sh:  | GROFF_COMMAND=
=3D"$groff" "$pdfmom" --roff -rU1 -mdoc -Z | nl -ba)

Other hits for `\<GROFF_COMMAND\>` involve only logs or documentation.

At present, I don't think we have a way to inject `GROFFBIN` into test
scripts.  Solving that problem would enable us to attack another item on
my to-do list.

https://savannah.gnu.org/bugs/index.php?66682

_That_ would be a big lift, affecting practically all of the 360+ test
scripts we have.  But with patience I suspect it could be automated with
a carefully written sed(1) script.

> test-groff is obviously not executable under cross-build,

Well, "test-groff" _itself_ is.  It's just a shell script.  That fact
might enable some cleverness, or eliminate a barrier to a
straightforward solution.  I'd likely start with making `GROFF_BIN_PATH`
overridable--something like this?

$ git diff
diff --git a/test-groff.in b/test-groff.in
index a65898a77..a72c24fe8 100644
--- a/test-groff.in
+++ b/test-groff.in
@@ -23,7 +23,7 @@ SEP=3D'@PATH_SEPARATOR@'
 builddir=3D@abs_top_builddir@
 srcdir=3D@abs_top_srcdir@

-GROFF_BIN_PATH=3D$builddir
+: ${GROFF_BIN_PATH:=3D"$builddir"}

 XENVIRONMENT=3D$srcdir/src/devices/xditview/GXditview.ad
 export XENVIRONMENT

Steering that variable's nose to /usr/riscv64-unknown-elf/bin or the
moral equivalent should solve several problems.  Any command in groff,
the project, that must find our other commands searches `GROFF_BIN_PATH`
(if it is defined and non-empty) before `PATH`.

> so alternatively we could copy the host's groff doc files over instead
> of building them.

If _I_ were working on cross-compiling groff, that is not the solution I
would prefer--it doesn't "feel right"--but as a matter of generating
deliverable and acceptable artifacts, as noted above there should be no
difference and therefore no problem.

Regards,
Branden

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

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

iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmpgcq0ACgkQ0Z6cfXEm
bc7wzRAAibWJsHTblw7JlMiGUNLjkrWlnK7DM1zPW6+mHYq5hffbqwXuWbM5IZzZ
tCR86BNd7L6vzEgVY/Fp6HZ5o7WFY7x+dERLcXAWSkWUeHjaw0Gq5Qvv7lxC1zAc
z7/9a9nEvGH8JJ95AessD3/CILKHesrgylEx14qoh8xeVsAN7Jo/hpvB6fQjxVvV
90gD2RHLGI+myWVuO1LAHeBedWOjHMsiRCcTRBsJKpvjkBy93V9eQQ7RxOVXSXt6
oSxrO4NpX1Qk6SPfGwfQk5s2ZV70UROLaIx2AzIjMiIxUTgFL/YsVd9BuFTKt6eQ
xB9KxM5E4pegsh0gHyK6Z5cYrVRt0AhkPCFIiiubtu6Ye+V9WnkOOz7oNS19hm2l
y9s+g96uTcUuaetSiT4UIHP87tvmS6gO+GTuk+ue4OO46dNzwfdm5n4T3HT1gVtT
HrpLDx/dgrg6c+9KIo4ejKJMKpuPBOrE+1dSfJdIQOgfrMw55s3A8HVqovbEtCuF
1ULcjJZhm+X1yLPDe9xyyvd4ucWw4rhrRq6997AcXxuGcuMfxptptK/f8KG701NG
cJVEu8IhMO41GuZNREIlFZHt6GqY1wt0FsxhI6q7+AIKWW0277j8uRGMhqCTHvYx
0GQEBCRqjql/TfrHAOrMXJ+e8fxdlRPcaWQr7l8cvpsS83JH2WU=
=ijiW
-----END PGP SIGNATURE-----

--3awvh2l475p775vf--