gbranden pushed a commit to branch master
in repository groff.
commit addb8619890bc0c9cf11ac4c37f57164c195ef69
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Jul 3 00:17:07 2026 -0500
[doc,man]: Add line layout diagram.
* doc/line-layout.roff: New file uses pic(1) to replace ASCII art
diagram of *roff output line geometry.
* doc/doc.am: Define new macros `DOC_LINE_LAYOUT_EPS` and
`DOC_LINE_LAYOUT_PNG` to track names of rendered forms of the
foregoing pic(1) image. Clean these files from the build directory.
Add them as prerequisites to the `$(GROFF_DVI)` and `$(GROFF_PDF)`
targets, respectively. Add the new file and its rendered forms to the
`EXTRA_DIST` macro to ship them in our distribution archive.
($(GROFF_HTML)): Add `DOC_LINE_LAYOUT_PNG` as prerequisite. Copy that
file into the directory used by the split-by-node version of our
Texinfo manual in HTML form, as required for makeinfo(1) to generate a
non-broken "<img src>" element.
(maintainer-clean-local): Clean the rendered image files from the
build directory.
(install-html-local): Install the rendered image file where the
monolithic version of our Texinfo manual in HTML form can find it.
(dist-gnueps): XXX Drop apparently unneeded target, and `dist-hook`'s
use of it as a prerequisite.
($(DOC_LINE_LAYOUT_EPS)): New target rule renders the new file as
Encapsulated PostScript file using groff(1), gs(1) {Ghostscript}, and
sed(1), as documented in grops(1).
($(DOC_LINE_LAYOUT_PNG)): New target rule renders the new file as a
Portable Network Graphics file using convert(1) {ImageMagick}.
* doc/groff.texi.in (Line Layout): Inline image. Retain the ASCII art
version, but output it only `ifinfo`--rendering to a format that
doesn't support inline images.
* man/groff.7.man (Line layout): Inline aforementioned pic(1) document
with a `so` request, only if in troff mode. Otherwise, use the
existing ASCII art version. So that installed systems don't have to
manage the installation location of the file...
* Makefile.am: ...update `.man` suffix rule to depend on soelim(1), and
unconditionally run all man pages (which are generated files already
anyway) through soelim(1), literally inlining the pic(1) region. Pass
soelim(1) `-I` options so that the "line-layout.roff" file should be
found whether the build takes place inside or outside of the build
tree.
Thanks to Stefan Möding for the new diagram!
ANNOUNCE: Acknowledge Stefan.
---
ANNOUNCE | 1 +
ChangeLog | 46 +++++++++++++++++++++++++++++++
Makefile.am | 4 +--
doc/doc.am | 77 ++++++++++++++++++++++++++++++++++++----------------
doc/groff.texi.in | 3 ++
doc/line-layout.roff | 21 ++++++++++++++
man/groff.7.man | 6 ++++
7 files changed, 132 insertions(+), 26 deletions(-)
diff --git a/ANNOUNCE b/ANNOUNCE
index 3e339c1fb..5066145bf 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -226,4 +226,5 @@ Richard Purdie
Ross Burton
Russ Allbery
Santiago Vila
+Stefan Möding
Zack Weinberg
diff --git a/ChangeLog b/ChangeLog
index 187eedc93..17c4f44ad 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,49 @@
+2026-07-02 G. Branden Robinson <[email protected]>
+
+ [doc,man]: Add line layout diagram.
+
+ * doc/line-layout.roff: New file uses pic(1) to replace ASCII
+ art diagram of *roff output line geometry.
+ * doc/doc.am: Define new macros `DOC_LINE_LAYOUT_EPS` and
+ `DOC_LINE_LAYOUT_PNG` to track names of rendered forms of the
+ foregoing pic(1) image. Clean these files from the build
+ directory. Add them as prerequisites to the `$(GROFF_DVI)` and
+ `$(GROFF_PDF)` targets, respectively. Add the new file and its
+ rendered forms to the `EXTRA_DIST` macro to ship them in our
+ distribution archive.
+ ($(GROFF_HTML)): Add `DOC_LINE_LAYOUT_PNG` as prerequisite.
+ Copy that file into the directory used by the split-by-node
+ version of our Texinfo manual in HTML form, as required for
+ makeinfo(1) to generate a non-broken "<img src>" element.
+ (maintainer-clean-local): Clean the rendered image files from
+ the build directory.
+ (install-html-local): Install the rendered image file where the
+ monolithic version of our Texinfo manual in HTML form can find
+ it.
+ (dist-gnueps): XXX Drop apparently unneeded target, and
+ `dist-hook`'s use of it as a prerequisite.
+ ($(DOC_LINE_LAYOUT_EPS)): New target rule renders the new file
+ as Encapsulated PostScript file using groff(1), gs(1)
+ {Ghostscript}, and sed(1), as documented in grops(1).
+ ($(DOC_LINE_LAYOUT_PNG)): New target rule renders the new file
+ as a Portable Network Graphics file using convert(1)
+ {ImageMagick}.
+ * doc/groff.texi.in (Line Layout): Inline image. Retain the
+ ASCII art version, but output it only `ifinfo`--rendering to a
+ format that doesn't support inline images.
+ * man/groff.7.man (Line layout): Inline aforementioned pic(1)
+ document with a `so` request, only if in troff mode. Otherwise,
+ use the existing ASCII art version. So that installed systems
+ don't have to manage the installation location of the file...
+ * Makefile.am: ...update `.man` suffix rule to depend on
+ soelim(1), and unconditionally run all man pages (which are
+ generated files already anyway) through soelim(1), literally
+ inlining the pic(1) region. Pass soelim(1) `-I` options so that
+ the "line-layout.roff" file should be found whether the build
+ takes place inside or outside of the build tree.
+
+ Thanks to Stefan Möding for the new diagram!
+
2026-07-02 G. Branden Robinson <[email protected]>
* src/preproc/eqn/eqn.am:
diff --git a/Makefile.am b/Makefile.am
index 8d0968025..5f4b74b04 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -829,7 +829,7 @@ set-man-page-time-stamps:
makevarescape=$(top_srcdir)/makevarescape.sed
SUFFIXES += .man
-.man:
+.man: soelim
$(AM_V_GEN)$(MKDIR_P) `dirname $@` \
&& LC_ALL=C \
sed -e "s|[@]APPDEFDIR[@]|`echo $(appdefdir) | sed -f
$(makevarescape)`|g" \
@@ -864,7 +864,7 @@ SUFFIXES += .man
-e "s|[@]TMAC_MDIR[@]|`echo $(tmacdir) | sed -f
$(makevarescape)`/mm|g" \
-e "s|[@]TMAC_S_PREFIX[@]|\\\\%$(tmac_s_prefix)|g" \
-e "s|[@]VERSION[@]|$(VERSION)|g" \
- $< \
+ $< | soelim -I $(srcdir) -I $(builddir) \
>$@
# Version files - see script "build-aux/git-version-gen".
diff --git a/doc/doc.am b/doc/doc.am
index 5caed84cf..49321e3ed 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -59,9 +59,12 @@ DOC_PDFMOM = \
GROFF_BIN_PATH="$(GROFF_BIN_PATH)" \
$(PDFMOMBIN) $(MFLAG) $(FFLAG) -ww -b $(pdfmomoption) --roff
-# This image file is used by several documents in the groff source tree.
+# These images are used by several documents in the groff source tree.
DOC_GNU_EPS = doc/gnu.eps
DOC_GNU_PNG = doc/gnu.png
+DOC_LINE_LAYOUT_EPS = doc/line-layout.eps
+DOC_LINE_LAYOUT_PNG = doc/line-layout.png
+
DOC_GMP_COVER_PAGE = doc/groff-man-pages-cover.groff
# Other doc, installed in $(docdir)
@@ -430,7 +433,7 @@ doc/webpage.html: $(doc_srcdir)/webpage.ms
$(TMAC_PACKAGE_MS)
$(AM_V_at)mv [email protected] $@
# We remove groff.css, groff.{html,html.node,info,pdf,texi,txt}, and
-# gnu.png only from an out-of-source build tree.
+# {gnu,line-layout}.{eps,png} only from an out-of-source build tree.
mostlyclean-local: mostlyclean_doc
mostlyclean_doc:
$(RM) $(GROFF_DVI) $(PROCESSEDDOCFILES_PDF)
@@ -440,7 +443,9 @@ mostlyclean_doc:
$(GROFF_HTML) $(GROFF_INFO) $(GROFF_PDF) $(GROFF_TXT) \
doc/groff.texi \
$(top_builddir)/$(DOC_GNU_EPS) \
- $(top_builddir)/$(DOC_GNU_PNG); \
+ $(top_builddir)/$(DOC_GNU_PNG) \
+ $(top_builddir)/$(DOC_LINE_LAYOUT_EPS) \
+ $(top_builddir)/$(DOC_LINE_LAYOUT_PNG); \
$(RM) -r $(GROFF_HTML).node; \
fi
if HAVE_TEXI2DVI
@@ -601,8 +606,8 @@ GROFF_DVI = doc/groff.dvi
GROFF_PDF = doc/groff.pdf
endif # USE_TEX
-$(GROFF_DVI): $(DOC_GNU_EPS)
-$(GROFF_PDF): $(DOC_GNU_PNG)
+$(GROFF_DVI): $(DOC_GNU_EPS) $(DOC_LINE_LAYOUT_EPS)
+$(GROFF_PDF): $(DOC_GNU_PNG) $(DOC_LINE_LAYOUT_PNG)
# pdfTeX can find resources in a VPATH build when generating PDF (with
# pdfetex), but not when generating DVI (with etex). Steer the latter's
@@ -611,15 +616,17 @@ TEXINPUTS="$(doc_srcdir)$(PATH_SEPARATOR)$$TEXINPUTS"
# We also have to override Automake's built-in rule for generation of
# HTML from Texinfo to include our embedded images.
-$(GROFF_HTML): doc/groff.texi $(DOC_GNU_PNG)
+$(GROFF_HTML): doc/groff.texi $(DOC_GNU_PNG) $(DOC_LINE_LAYOUT_PNG)
$(AM_V_GEN)$(MKDIR_P) `dirname $@` \
&& LANG=C LC_ALL=C $(MAKEINFO) --html \
-I $(doc_builddir) -I $(doc_srcdir) \
-o $(GROFF_HTML).node $< \
&& if test -f "$(srcdir)/$(DOC_GNU_PNG)"; then \
- cp -f "$(srcdir)/$(DOC_GNU_PNG)" $(GROFF_HTML).node; \
+ cp -f "$(srcdir)/$(DOC_GNU_PNG)" \
+ "$(srcdir)/$(DOC_LINE_LAYOUT_PNG)" $(GROFF_HTML).node; \
else \
- cp "$(builddir)/$(DOC_GNU_PNG)" $(GROFF_HTML).node; \
+ cp -f "$(builddir)/$(DOC_GNU_PNG)" \
+ "$(builddir)/$(DOC_LINE_LAYOUT_PNG)" $(GROFF_HTML).node; \
fi \
&& LANG=C LC_ALL=C $(MAKEINFO) --html \
-I $(doc_builddir) -I $(doc_srcdir) \
@@ -733,6 +740,8 @@ install-doc: install-dvi install-html install-pdf
maintainer-clean-local:
$(RM) $(builddir)/$(DOC_GNU_EPS)
$(RM) $(builddir)/$(DOC_GNU_PNG)
+ $(RM) $(builddir)/$(DOC_LINE_LAYOUT_EPS)
+ $(RM) $(builddir)/$(DOC_LINE_LAYOUT_PNG)
$(RM) $(builddir)/$(GROFF_INFO)
$(RM) $(builddir)/$(GROFF_TXT)
$(RM) $(builddir)/$(GROFF_HTML)
@@ -800,7 +809,7 @@ install-html-local: $(GROFF_HTML)
|| $(mkinstalldirs) $(DESTDIR)$(htmldocdir)/groff.html.mono
for d in $(doc_builddir) $(doc_srcdir); do \
if [ -f "$$d"/groff.html ]; then \
- cp -r "$$d"/groff.html "$$d"/gnu.png \
+ cp -r "$$d"/groff.html "$$d"/gnu.png "$$d"/line-layout.png \
$(DESTDIR)$(htmldocdir)/groff.html.mono; \
cp -r "$$d"/groff.html.node \
$(DESTDIR)$(htmldocdir); \
@@ -830,10 +839,25 @@ uninstall-html:
uninstall-txt:
$(RM) $(DESTDIR)$(docdir)/groff.txt
-# An image of a gnu in encapsulated PostScript is generated during the
-# build process if necessary. Our configure script assumes pnmdepth is
-# available if xpmtoppm is (see macro "GROFF_PROG_XPMTOPPM").
-EXTRA_DIST += $(DOC_GNU_EPS) $(DOC_GNU_PNG) doc/gnu.xpm
+# Ship sources of images used variously by documentation and examples.
+#
+# We distribute image sources because groff is a copylefted project.
+#
+# We distribute image "binaries" to reduce build-time dependencies for
+# users of our distribution archive.
+#
+# Our "configure" script assumes pnmdepth is available if xpmtoppm is;
+# see macro "GROFF_PROG_XPMTOPPM" in "groff.m4".
+EXTRA_DIST += \
+ doc/gnu.xpm \
+ $(DOC_GNU_EPS) \
+ $(DOC_GNU_PNG) \
+ doc/line-layout.roff \
+ $(DOC_LINE_LAYOUT_EPS) \
+ $(DOC_LINE_LAYOUT_PNG)
+
+# maintainer mode targets
+
$(DOC_GNU_EPS): doc/gnu.xpm
$(AM_V_GEN)$(MKDIR_P) `dirname $@` \
&& if test "$(XPMTOPPM)" != found; then \
@@ -869,18 +893,23 @@ $(DOC_GNU_PNG): doc/gnu.xpm
fi; \
xpmtoppm $(top_srcdir)/doc/gnu.xpm | pnmtopng >$@
-# Provide a copy of the image in the distribution archive to accommodate
-# systems without a tool to generate it from an X pixmap.
-dist-hook: dist-gnueps
-dist-gnueps:
- chmod u+w $(distdir)/doc
- for d in $(doc_builddir) $(doc_srcdir); do \
- if [ -f "$$d"/$(DOC_GNU_EPS) ]; then \
- cp -f "$$d"/$(DOC_GNU_EPS) $(distdir)/doc; \
- break; \
- fi; \
- done
+# XXX: ugly, but DRY
+DOC_LL=line-layout
+$(DOC_LINE_LAYOUT_EPS): doc/line-layout.roff pic groff troff grops \
+ font/devps/stamp
+ $(AM_V_GEN)$(MKDIR_P) `dirname $@` \
+ && $(DOC_GROFF) -p -T ps -P -b16 $< >$(DOC_LL).ps \
+ && gs -q -dNOPAUSE -sDEVICE=bbox -- $(DOC_LL).ps \
+ 2> $(DOC_LL).bbox \
+ && sed -e '/^%%Orientation/r $(DOC_LL).bbox' \
+ -e '/^%!PS-Adobe-3.0/s/$$/ EPSF-3.0/' $(DOC_LL).ps >[email protected] \
+ && $(RM) $(DOC_LL).ps $(DOC_LL).bbox \
+ && mv [email protected] $@
+
+$(DOC_LINE_LAYOUT_PNG): $(DOC_LINE_LAYOUT_EPS)
+ $(AM_V_GEN)$(MKDIR_P) `dirname $@` \
+ && convert -density 300 $< PNG24:$@
# Local Variables:
# fill-column: 72
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 7e1c82b46..c390733f4 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -12089,6 +12089,8 @@ that the formatter uses to arrange a line of output on
the page.
Each dimension is labelled
with the name of the request that configures it.
+@center @image{line-layout,4in,,line layout diagram,.png}
+@ifinfo
@Example
-->| in |<--
|<-----------ll------------>|
@@ -12098,6 +12100,7 @@ with the name of the request that configures it.
-->| po |<--
|<--------paper width---------------->|
@endExample
+@end ifinfo
@noindent
The dimensions are defined as follows.
diff --git a/doc/line-layout.roff b/doc/line-layout.roff
new file mode 100644
index 000000000..b2404cfee
--- /dev/null
+++ b/doc/line-layout.roff
@@ -0,0 +1,21 @@
+.\" diagram Copyright 2026 Stefan Moeding
+.PS
+pw = 5;
+ll = pw - 1;
+po = 0.5;
+in = 0.5;
+#
+line down 2;
+move down 0.1; line <-> right pw "paper width" above; move up 0.1;
+line up 2;
+line left pw;
+#
+move right po down 0.5;
+line dashed right ll then down 1.25;
+move up 0.1; line <-> left ll "ll" above; move down 0.1;
+line dashed up 1.25;
+#
+move right in; line dotted down 0.5;
+move up 0.25; line <-> left in "in" above;
+move down 0.25; line <-> left po "po" below;
+.PE
diff --git a/man/groff.7.man b/man/groff.7.man
index 2c2688ce0..50d380290 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -727,6 +727,11 @@ with the name of the request that configures it.
.
.
.P
+.ie t \{\
+.\" Do not indent the next line! soelim(1) needs to see it.
+.so doc/line-layout.roff
+.\}
+.el \{\
.RS
.EX
-->| in |<--
@@ -738,6 +743,7 @@ with the name of the request that configures it.
|<--------paper width---------------->|
.EE
.RE
+.\}
.
.
.P
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
