Re: webpage.html sometimes doesn't build out-of-tree? (was: error by compiling)

"G. Branden Robinson" <[email protected]> Sun, 22 Feb 2026 01:18:59 -0600
Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260222071859.xpexfir523agal4u@illithid>
At 2026-02-21T13:50:16+0000, Deri wrote:
> This is a strange one!! The error occurs if you don't have the file
> doc/ gnu.eps (because PSPIC can't find it). doc.am makes it (from
> doc/gnu.xpm) but in "out-of-tree" builds it ends up in
> build/doc/gnu.eps, and not found.
> 
> The regression was introduced by commit e9da162af80 (Feb 7, 2026),
> reverting fixes it.

I should point out that this is an incorrect, or at best incomplete,
analysis.

A bug (omission of an `-I $(doc_builddir)` argument to groff in
"doc/doc.am") had been in place for a long time, but was masked by the
fact that, for some years,[0] the recipe for creating "doc/webpage.html"
included a change of directory into `$(doc_builddir)`.  The reason it
had worked anyway arises from two overlapping contingencies, either of
which would result in "gnu.eps" being found: (1) a build where
`doc_builddir` equals `doc_srcdir` [what _I_ term an "in-tree" build];
or (2) a build where "gnu.eps" ends up in the current working directory,
which should always be true (due its own target rule) when the Makefile
target is changing directories _into_ the build directory.

https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am?h=1.24.0.rc4#n773
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am?h=1.24.0.rc2#n422

It's atypical for Makefile rules to change directories for the purpose
of generating targets.

So I took it out.[1]

And the problem that _should_ have been revealed was masked on my system
because of the lingering (and all but hidden by ".gitignore")
"doc/gnu.eps" file in my _source_ directory, which was (roughly) your
analysis.  But that was only one piece of the puzzle.

One might fairly ask, does the `PSPIC` macro really go around looking in
several directories for the argument that's passed to it?  How does it
know what the `-I` arguments to the formatter were?

No, and it doesn't know.  But what `PSPIC` _does_ do is use the
otherwise little-employed `psbb` request of GNU troff, which opens a
PostScript file and parses the bounding box out of it.  Being a
_request_ inside the formatter, it has access to the "inclusion file
search path" that one can augment with `-I` options, and within which
the current working directory (".") is always implicit.[2][3]

https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/pspic.tmac?h=1.24.0.rc4#n56
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/input.cpp?h=1.24.0.rc4#n7593

I'm exasperated by the haste with which people apply the label
"regression" and leap to advising the reversion of commits to resolve
perceived misbehavior.  Sometimes reversion is proper; sometimes not.

Such conclusions can be properly reached only as the _outcome_ of
analysis.  They must not substitute for analysis.

If you meant to suggest that made the change in commit e9da162af8 with
insufficient diligence as to its risks or consequences, then I ask you
to think again.  Again, see the commit log message.

Regards,
Branden

[0] Seems to date back to commit 86be72236e, 7 September 2014.

[1] Here's the full commit log message.

commit e9da162af80d53128990a6b19237d8c8d416582c
Author: G. Branden Robinson <[email protected]>
Date:   Sat Feb 7 17:04:54 2026 -0600

    [doc]: Simplify generation of HTML with groff.

    * doc/doc.am: Simplify generation of HTML documents with groff.

      (doc/pic.html, doc/webpage.html): Stop changing directories as part of
      the target receipe; instead, alter the argument to grohtml's `-j`
      option to include the name of the desired subdirectory.  Drop test for
      existence of separate image files afterward.  Since the fix for
      Savannah #67133 last May, we should be able to rely on groff to exit
      with a nonzero status if grohtml fails.  Tested with "make check" and
      "make distcheck" in four configurations: the Cartesian product of
      {BSD, GNU} make with {in-, out-of-}tree builds.

[2] troff(1):

     -I dir   Search the directory dir for files (those named on the
              command line; in psbb, so, and soquiet requests; and in
              “\X'ps: import'”, “\X'ps: file'”, and “\X'pdf: pdfpic'”
              device extension escape sequences).  -I may be specified
              more than once; each dir is searched in the given order.
              To search the current working directory before others, add
              “-I .” at the desired place; it is otherwise searched
              last.  -I works similarly to, and is named for, the
              “include” option of Unix C compilers.

[3] I've had a hankering to take the `psbb` request out of GNU troff and
    replace with a preprocessor or unsafe-mode macro.  Regardless, it
    doesn't seem crazy to me to expose the inclusion search path to
    macros, say via a string-valued register.  Because a search path
    (if any `-I` options are supplied) has separator characters--':' on
    Unix hosts, ';' on Windows--such a thing would be mightily tedious
    to work with at present.  It's yet another macro programming task
    that would become much easier if we had a string iteration request.

    https://savannah.gnu.org/bugs/?62264

    We could then use it to write an analogue to strtok(3).
signature.asc (application/pgp-signature, 833 B)