Hi Michael and Alex!
I have some suggestions for the recent new "FORMATTING AND WORDING
CONVENTIONS" section of man-pages(7). As I have several unrelated
miscellaneous issues to report, and none should be challenging to
integrate, I am presenting a broken-up (annotated) diff inline with the
full patch attached, along with a demonstrator sample man page for one
of the issues I raise.
diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 7658ef33b..56d6f8b2b 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -511,7 +511,7 @@ However, blank lines (achieved using
.IR .PP )
may be added in the following cases:
.IP * 3
-to separate long lists of function prototypes ino relates groups
+to separate long lists of function prototypes into related groups
(see for example
.BR list (3));
.IP *
tfix (×2)
@@ -525,7 +525,8 @@ If there is a single such prototype that needs to be continued,
then align the continuation line so that when the page is
rendered on a fixed-width font device (e.g., on an xterm) the
continuation line starts just below the start of the argument
-list in the line above. (Exception: the indentation may be
+list in the line above.
+(Exception: the indentation may be
adjusted if necessary to prevent a very long continuation line
or a further continuation line where the function prototype is
very long.)
semantic newline
@@ -537,11 +538,12 @@ As an example:
.BI " const struct termios *" termios_p );
.fi
.RE
-.IP 2. 3
+.IP 2.
It is not necessary to repeat the indentation amount when the previous
one is being reused, and this man page otherwise does not indulge such
repetition when using .IP to set paragraph tags.
But, where multiple functions in the SYNOPSIS require
continuation lines, and the function names have different
lengths, then align all continuation lines to start in the
-same column. This provides a nicer rendering in PDF output
+same column.
+This provides a nicer rendering in PDF output
(because the SYNOPSIS uses a variable width font where
spaces render narrower than most characters).
As an example:
semantic newline
@@ -569,23 +571,25 @@ This wording is consistent with the wording used in both POSIX.1 and FreeBSD.
.\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf
Note the following:
.IP * 3
-Wrap the table in this section in a
-.IR ".ad\ l" / .ad
-pair to disable text filling and a
-.IR .nh / .hy
-pair to disable hyphenation.
-.IP *
Ensure that the table occupies the full page width through the use of an
-.I lbx
-description for one of the columns
+.I x
+modifier appended to one of the table column formats
A few issues here:
(1) In the groff man pages we do _not_ encourage wrapping tables with
.na/.ad pairs. (I do notice you said ".ad l/.ad" instead--I'll return
to that.) Quoting a commit to our tbl(1) man page from September[1]:
Stop advising people to use adjustment-altering requests to bracket
tables to cheaply set the alignment of text blocks ("T{", "T}") in
table entries. This is bad advice for man pages (it was overriding
-dAD=l to force full justification on after a table in groff_ms(7)).
Adjustment requests can be embedded inside text blocks anyway, and you
don't even have to remember to undo them.
The problem with .na before a table, which is the more popular approach,
and which you probably already discovered given that you're recommending
".ad l" instead, is that people who have found a way to force adjustment
off already will be angry with man pages taking your advice because
"full" adjustment (to both margins) will spring to life after the table.
People who _do_ like adjustment to both margins will also be angry with
your man pages because ".ad l" configures the adjustment mode to be
ragged-right, which means ".ad" afterwards is a no-op. You would need
to recommend ".ad l"/".ad b" instead (or ".ad l"/".ad n"--they're
synonymous).
".ad l" also defeats the mechanism, forthcoming in groff 1.23.0, to make
the default adjustment mode for man pages user-configurable with the AD
string.
In other words, in the next groff release you can pass "-dAD=l" to the
formatter (groff/troff/nroff) and force left-adjustment for _all_ man
pages, except those which are rude enough to use raw roff requests to
override it.
If you will relax this advice in favor of my suggestion below, it will
keep man pages rendering nicely while also respecting user rendering
preferences.
(2) I don't encourage bracketing tables with .nh/.hy either. The
biggest problem is that .hy, despite a tempting analogy with .ad, does
not set the hyphenation mode to the previous default, but to the
formatter's hard-coded default, "1", which is not compatible with the
English hyphenation patterns GNU troff uses. I'll skip over the history
of this regrettable point and get to the good news. groff 1.23.0 will
also support a HY register allowing the user to specify a preference for
the default hyphenation mode when rendering man pages.
The above AD and HY features are already implemented, tested, and
documented[2].
(3) I would not use "lbx" as a blanket prescription for a table column.
I fear people cargo-culting it. This column descriptor means
"left-align, boldface, expand". Only the "x" character is motivated by
your advice, which I otherwise find sound.
(usually the first column,
though in some cases the last column if it contains a lot of text).
.IP *
Make free use of
.IR T{ / T}
-macro pairs to allow table cells to be broken over multiple lines
+pairs to allow table cells to be broken over multiple lines
s/macro//
T{ and T} are not *roff macros, but special tokens recognized by the
parser of the tbl preprocessor.
(also bearing in mind that pages may sometimes be rendered to a
width of less than 80 columns).
+When doing so,
+it may be necessary to turn off adjustment and hyphenation with
+.I .na
+and
+.I .nh
+requests,
+respectively.
+(Adjustment does not need to be restored.)
.PP
For examples of all of the above, see the source code of various pages.
.SH STYLE GUIDE
Instead of bracketing a table with .na/.ad and .nh/.hy requests, one can
put .na and .nh requests in individual text blocks. Better still, you
don't even have to remember to turn adjustment back on--tbl takes care
of that for you.
I wish I could say the same thing about hyphenation. .nh does work, but
tbl forgets to turn hyphenation back on after the table. This is a bug
with a long beard--both groff tbl and Heirloom Doctools tbl misbehave
this way, and due to the latter I suspect it of being true of Version 7
Unix tbl as well[3]. Lesk's 1979 tbl manual says nothing about it. It
is hard to rationalize as a deliberate choice, given the behavior of
adjustment. I just learned about this in the course of composing this
mail and it's my intention to fix it in groff for 1.23.0.
People who hate hyphenation anyway--and there seem to be many--probably
won't mind if you forget to advise writers to re-enable it, so maybe you
can omit my suggested parenthetical with a clear conscience.
What about adjustment and hyphenation in table cells that aren't text
blocks? The answer is simple--they don't happen. Text blocks are
called that because tbl arranges for them to be laid out like miniature
pieces of the main document. Ordinary table cells are handled using
roff's tab and field mechanisms, which don't enclose line breaks. That
means they're not subject to hyphenation or adjustment.
I'm happy to prepare fresh patch(es) of any of the above items you
approve. Let me know.
As always, I'm open to any readers' feedback, questions, and thundering
denunciations.
Regards,
Branden
[1] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=550ab5338e04e54539214997315f451c89ac25e6
[2] https://man7.org/linux/man-pages/man7/groff_man.7.html#Options
[3] TUHS doesn't have V7 tbl's source code, and firing up a PDP-11 in
SIMH to key in a document with ed so I can test the behavior of its
executable requires a lot of patience.
diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 7658ef33b..ea63b5c6f 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -511,7 +511,7 @@ However, blank lines (achieved using
.IR .PP )
may be added in the following cases:
.IP * 3
-to separate long lists of function prototypes ino relates groups
+to separate long lists of function prototypes into related groups
(see for example
.BR list (3));
.IP *
@@ -525,7 +525,8 @@ If there is a single such prototype that needs to be continued,
then align the continuation line so that when the page is
rendered on a fixed-width font device (e.g., on an xterm) the
continuation line starts just below the start of the argument
-list in the line above. (Exception: the indentation may be
+list in the line above.
+(Exception: the indentation may be
adjusted if necessary to prevent a very long continuation line
or a further continuation line where the function prototype is
very long.)
@@ -537,11 +538,12 @@ As an example:
.BI " const struct termios *" termios_p );
.fi
.RE
-.IP 2. 3
+.IP 2.
But, where multiple functions in the SYNOPSIS require
continuation lines, and the function names have different
lengths, then align all continuation lines to start in the
-same column. This provides a nicer rendering in PDF output
+same column.
+This provides a nicer rendering in PDF output
(because the SYNOPSIS uses a variable width font where
spaces render narrower than most characters).
As an example:
@@ -569,23 +571,25 @@ This wording is consistent with the wording used in both POSIX.1 and FreeBSD.
.\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf
Note the following:
.IP * 3
-Wrap the table in this section in a
-.IR ".ad\ l" / .ad
-pair to disable text filling and a
-.IR .nh / .hy
-pair to disable hyphenation.
-.IP *
Ensure that the table occupies the full page width through the use of an
-.I lbx
-description for one of the columns
+.I x
+modifier appended to one of the table column formats
(usually the first column,
though in some cases the last column if it contains a lot of text).
.IP *
Make free use of
.IR T{ / T}
-macro pairs to allow table cells to be broken over multiple lines
+pairs to allow table cells to be broken over multiple lines
(also bearing in mind that pages may sometimes be rendered to a
width of less than 80 columns).
+When doing so,
+it may be necessary to turn off adjustment and hyphenation with
+.I .na
+and
+.I .nh
+requests,
+respectively.
+(Adjustment does not need to be restored.)
.PP
For examples of all of the above, see the source code of various pages.
.SH STYLE GUIDE
Attachment:
man-table-na-nh.man
Description: Unix manual page
Attachment:
signature.asc
Description: PGP signature
