[PATCH 10/42] locate.1: improve table formatting

"G. Branden Robinson" <[email protected]> Tue, 18 Nov 2025 21:45:31 -0600
Newsgroups	gmane.comp.gnu.findutils.bugs
Message-ID	<20251119034531.xbed6halaxbqddyj@illithid>
* Use paragraphing macro to put vertical space above the table so that
  it looks more like a typographical "display".[1]
* Set table cells that overset the line on AT&T nroff (where the line
  length is 65n) using text blocks.
* Issue `na` request in these text blocks to prevent the cell contents
  from adjusting in the event the formatter/package/user has configured
  man pages to employ adjustment by default.  (Practices vary; it's a
  long story.[2])
* Remove spaces around the configured tbl(1) tab character of `|`.  This
  certainly does make the table uglier in source form.  Unfortunately,
  AT&T tbl(1) takes those spaces deadly seriously and they impact the
  computed cell (and therefore column) widths.  GNU tbl has for decades
  supported a "nospaces" region option to address precisely this
  problem; unfortunately it is not portable to DWB 3.3, Plan 9, or
  Solaris 10 troffs, and I suspect not to _any_ surviving System V
  troff.

Fixes warning from tbl(1) in groff 1.23.0:

locate/locate.1:289: warning: table wider than line length minus indentation

[1] man(7) implementations are historically inconsistent with respect to
    whether a `TS` macro call should put any vertical space on the
    output, and compositional practices on the part of man page authors
    have thus been, to quote Ingo Schwarze, "wildly inconsistent".

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

[2] "Some people do hate adjustment of nroff output, though, which is
    why I added a feature to groff man(7) to support disabling it.

    The history of this practice is inconsistent.  Seventh Edition Unix
    (1979) disabled adjustment of man pages when rendering in nroff
    mode,[3] and BSD retained that disablement until death.  SunOS
    commented it as early as SunOS 2.0 (1985), thus restoring adjustment
    in nroff mode, and retained that all the way through Solaris 10
    (2005).  When James Clark wrote groff starting in about 1989, his
    man(7) implementation closely emulated SunOS.  With the Solaris 11
    release in 2010, Oracle discarded its AT&T-descended troff in favor
    of the then-current groff release.  [That's not quite true--see
    below.]  They're still on groff 1.22.2 (2013) today, and so they've
    been adjusting their man pages in nroff mode for at least 40 years,
    as has groff for about 35[].  I don't know what other System V
    Unices did."

    https://lists.gnu.org/archive/html/groff/2025-05/msg00001.html

    (I made an incorrect claim in the foregoing; Solaris 11 still has
    its AT&T troff around, but its man page rendering is now performed
    by [an old version of] groff.)
---
 locate/locate.1 | 36 +++++++++++++++++++++++-------------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/locate/locate.1 b/locate/locate.1
index 3ba6d362..9efc9e36 100644
--- a/locate/locate.1
+++ b/locate/locate.1
@@ -292,22 +292,32 @@ .SH "HISTORY"
 Significant changes to
 .B locate
 in reverse order:
+.P
 .TS
 tab(|);
 LL.
-4.3.7 | Byte-order independent support for old database format
-4.3.3 | locate \fI\-i\fR supports multi-byte characters correctly
-      | Introduced \fI\-\-max_db_age\fR
-4.3.2 | Support for the slocate database format
-4.2.22| Introduced the \fI\-\-all\fR option
-4.2.15| Introduced the \fI\-\-regex\fR option
-4.2.14| Introduced options \fI\-L, \-P, \-H\fR
-4.2.12| Empty items in \fBLOCATE_PATH\fR now indicate the default database
-4.2.11| Introduced the \fI\-\-statistics\fR option
-4.2.4 | Introduced \fI\-\-count\fR and \fI\-\-limit\fR
-4.2.0 | Glob characters cause matching against the whole file name
-4.0   | Introduced the LOCATE02 database format
-3.7   | Locate can search multiple databases
+4.3.7|T{
+.na
+Byte-order independent support for old database format
+T}
+4.3.3|locate \fI\-i\fR supports multi-byte characters correctly
+\^|Introduced \fI\-\-max_db_age\fR
+4.3.2|Support for the slocate database format
+4.2.22|Introduced the \fI\-\-all\fR option
+4.2.15|Introduced the \fI\-\-regex\fR option
+4.2.14|Introduced options \fI\-L, \-P, \-H\fR
+4.2.12|T{
+.na
+Empty items in \fBLOCATE_PATH\fR now indicate the default database
+T}
+4.2.11|Introduced the \fI\-\-statistics\fR option
+4.2.4|Introduced \fI\-\-count\fR and \fI\-\-limit\fR
+4.2.0|T{
+.na
+Glob characters cause matching against the whole file name
+T}
+4.0|Introduced the LOCATE02 database format
+3.7|Locate can search multiple databases
 .TE
 .
 .SH "BUGS"
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)