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

G. Branden Robinson
2020-09-28T13:41:14Z

[-- Attachment #1: Type: text/plain, Size: 2130 bytes --]

At 2020-09-28T15:29:59+0200, 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.

<laugh> Oh, dear.

The page source is interleaved with comments that illustrate
anti-patterns. You'll see that the second case is of the kind that Alex
just fixed.

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

I think that paragraph started life before I split off the
groff_man_style(7) page, and I was trying to keep things terse for the
benefit of people who wanted groff_man(7) to stay short.

The page is no longer being pulled in two directions, so I think this
material can be expanded out into real examples now.

I should probably move it later in the page, after the macros have been
fully introduced, and put a forward reference to it in the current
location.

Thanks for the critique.

With chagrinned regards,
Branden

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