Re: [PATCH 1/2] system_data_types.7: srcfix

G. Branden Robinson
2020-09-30T10:12:21Z

[-- Attachment #1.1: Type: text/plain, Size: 1776 bytes --]

Hi Jakub and Michael,

At 2020-09-29T14:13:26+0200, Michael Kerrisk (man-pages) wrote:
> On 9/28/20 3:29 PM, Jakub Wilk wrote:
> > Hi Branden!
> >
> > In groff_man_style(7) you wrote:
> >> Unused macro arguments are more often simply omitted, or good style
> >> suggests that a more appropriate macro be chosen, that earlier
> >> arguments are more important than later ones, or that arguments
> >> have identical significance such that skipping any is superfluous.
> >
> > After 15 minutes of gawking at this sentence, I still don't
> > understand what are you trying to say here. The sentence should be
> > either thoroughly rephrased or removed.
>
> I must say that I too found it hard to parse. I presume, Branden,
> that you mean:
>
> [[
> Unused macro arguments are more often simply omitted, or good style
> suggests
> EITHER (1)
> that a more appropriate macro be chosen,
> (2)
> that earlier arguments are more important than later ones, or
> (3)
> that arguments have
> identical significance such that skipping any is superfluous.
> ]]

You got it. But it was too much work.

> But it takes a few scans to work that out. Perhaps break this into
> smaller pieces, or add some explicit structuring elements to the
> sentence?

I was trying to be comprehensive with respect to several anti-patterns I
had in mind. However, using the anti-patterns concretely is premature
at that point in the page. So I both expanded and relocated the
material.

I'm attaching what I've just committed to groff git.

Further feedback is welcome, of course; revision of documentation is a
process that is never completed, only abandoned. And I haven't given up
yet. :)

Thank you both for your reviews.

Regards,
Branden

[-- Attachment #1.2: excise_standardese.diff --]
[-- Type: text/x-diff, Size: 3858 bytes --]

commit dd2c4cf05a659ae7127e342924668ff0fa0deaa1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date: Wed Sep 30 19:56:38 2020 +1000

groff_man_style(7): Clarify empty macro arguments.

Rewrite some ersatz standardese I had managed to concoct regarding why
empty macro arguments are usually not needed. Put an expanded
discussion, with anti-patterns and remedies, in section "Notes", with
forward reference from subsection "Macro reference preliminaries".

Thanks to Jakub Wilk and Michael Kerrisk for the critique.

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index c62d97ba..b96cbaf4 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -281,23 +281,8 @@ but the
package is designed such that this should seldom be necessary.
_ifstyle()dnl
.
-Unused macro arguments are more often simply omitted,
-.\" antipattern: '.TP ""' (just '.TP' will do)
-or good style suggests that a more appropriate macro be chosen,
-.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
-that earlier arguments are more important than later ones,
-.\" antipattern: '.TH foo 1 "" "foo "1.2.3"' (don't skip the date!)
-.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
-or that arguments have identical significance such that skipping any is
-superfluous.
-.\" antipattern: '.B one two "" three' (pointless)
-.\" Technically, the above has a side-effect of additional space
-.\" between "two" and "three", but there are much more obvious ways of
-.\" getting it if desired.
-.\" .B "one two three"
-.\" .B one "two " three
-.\" .B one two " three"
-.\" .B one two\~ three
+See section \(lqNotes\(rq below for examples of cases where better
+alternatives to empty arguments in macro calls are available.
_endif()dnl
.
Most macro arguments are strings that will be output as text;
@@ -3235,6 +3220,63 @@ Some tips on troubleshooting your man pages follow.
.
.
.TP
+\(bu Do I ever need to use an empty macro argument ("")?
+Probably not.
+.
+When this seems necessary,
+often a shorter or clearer alternative is available.
+.
+.\" antipattern: '.TP ""' (just '.TP' will do)
+.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
+.\" antipattern: '.TH foo 1 "" "foo 1.2.3"' (don't skip the date!)
+.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
+.\" antipattern: '.B one two "" three' (pointless)
+.\" Technically, the above has a side-effect of additional space
+.\" between "two" and "three", but there are much more obvious ways of
+.\" getting it if desired.
+.\" .B "one two three"
+.\" .B one "two " three
+.\" .B one two " three"
+.\" .B one two\~ three
+.TS
+c c
+lfCB lfCB.
+Instead of.\|.\. .\|.\|.do this.
+_
+\&.TP \(dq\(dq .TP
+\&.BI \(dq\(dq italic-text bold-text .IB italic-text bold-text
+\&.TH foo 1 \(dq\(dq \(dqfoo 1.2.3\(dq .TH foo 1 \
+\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \(dqfoo 1.2.3\(dq
+\&.IP \(dq\(dq 4n .TP 4n
+\&.B one two \(dq\(dq three .B one two three
+.TE
+.
+.
+.IP
+In the title heading
+.RB ( .TH ),
+the date of the page's last revision is more important than packaging
+information;
+it should not be omitted.
+.
+Ideally,
+a page maintainer will keep both up to date.
+.
+.
+.IP
+In the last example,
+the empty argument does have a subtly different effect than its
+suggested replacement;
+the empty argument becomes an additional space character\(embut it is a
+regular breaking space,
+so it can be discarded at the end of an output line.
+.
+It is better not to be subtle,
+particularly with space,
+which can be overlooked in source and rendered forms.
+.
+.
+.TP
.RB \(bu " .RS" " doesn't indent relative to my indented paragraph"
The
.B .RS

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]