archive mirror
 help / color / mirror / Atom feed
From: "G. Branden Robinson" <>
To: "Alejandro Colomar (man-pages)" <>
Cc: Jeremy Kerr <>,
	Michael Kerrisk <>,
Subject: Re: [PATCH v2] mctp.7: Add man page for Linux MCTP support
Date: Fri, 12 Nov 2021 20:35:38 +1100	[thread overview]
Message-ID: <20211112093536.hvifxgdtb2y6jzge@localhost.localdomain> (raw)
In-Reply-To: <>

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

Hi, Alex!

At 2021-11-11T22:38:43+0100, Alejandro Colomar (man-pages) wrote:
> > +Messages may be fragmented into packets before transmission, and reassembled at
> > +the remote endpoint.
> Break at the comma.

I use "/[;:,]." in vi(m) to help myself find these quickly (you can get
false positives in comments; a more sophisticated regex that one might
want to bind to a key can rule those out).  Breaking input lines after
commas, semicolons, and colons is considered good style by *roff
veterans going back to Kernighan in 1974[1].

"/[!?.][^\\]" is more important--it's an un-semantic-newline finder
(though again with some false positives).  Those have a real impact on
the resulting typography (due to inter-sentence spacing).

> Types should be in italics.
> Branden, I thought this was specified somewhere, but I can't find it.
> Do you know where it is?  Or maybe if your more up to date
> groff_man[_style](7) pages mention that?

Nope, apparently I never made a prescription in this area.  It's worth
making explicit note of, since it deviates from the "literal -> bold,
variable -> italics" mapping that people overgeneralize/overapply.

So I'll queue this up for my next revision of groff_man_style(7).  Thank
you for catching it!

> groff_man(7) (groff 1.22.4):
>               Use italics for
>               for  names of works of software (including
>               commands and functions, but excluding names of op-
>               erating  systems or their kernels),

As an FYI, I'm feeling an urge to drop the foregoing item of advice.
Exceptions are often also made for names of software packages (both in
the loose sense and the technical one--who italicizes "TeX", for
example?); usage is so inconsistent that I despair of providing
comprehensible guidance.

Now that groff man(7) has the 'MR' semantic macro for man page cross
references[2], most of the instances where people would fail to
italicize will be taken care of without the foregoing.

> Anyway, for you Jeremy, I have other pages to follow for consistency:
> For example, gettimeofday(2).
> > +Packets between a local and remote endpoint are identified by the source
> Break after "by" (or perhaps just before it).

Phrasal semantic newlines!  :D  This 180-proof Kernighan whiskey is a
stronger prescription than I would write (mainly because it requires
natural-language-aware grepping), but if your contributors don't rebel,
I think we will all ultimately see the benefits in diffs.

> Something similar might be good for this page.  Maybe "trailing fields
> may be added in the future to this structure.  The structure should be
> zeroed before use, so that future fields are zeroed" or something like
> that (I'm not very inspired for the wording, sorry :), and then remove
> the pad field.

The idiom is `memset(mystructp, 0, sizeof(struct mystruct));`, isn't it?
If so, then maybe the point doesn't need to be made.

> Only for Branden:  I just noticed a difference between man-pages(7)
> and groff_man(7) advise:  groff_man(7) advises to use italics for
> preprocessor constants, while man-pages(7) recommends bold:
> [
>        Special macros, which are usually in  uppercase,  are  in
>        bold (e.g., MAXINT).  Exception: don't boldface NULL.
> ]

That was a deliberate difference on my part, motivated partially by own
preference for reduction of what I regard as excessive use of bold in
man pages since the '90s, and partly due to precedent.  The 4.4BSD book
by McKusick, et al., for example, uses italicized small caps for some
things enumeration constants (like open(2) flags) and upright small caps
for others (like errno(3) values and signal names).  man(1) output to a
terminal just doesn't have enough typefaces to go around.

"If in any doubt, use bold" seems to have become the prevailing wisdom
in the 1990s due, as far as I can tell, to a historical accident
involving the (lack of) capability of VGA hardware and text mode console
drivers[3].  Some readers might remember the days when getting an X11
server working on your hardware was considered an achievement.

> I find it better with bold, since that differentiates variables from
> constants.

Would we then also bold constants that are C objects with the "const"
type qualifier rather than language literals emplaced by the

My intuition is that this distinction isn't worth making with a
typeface; the use of bold is not necessary to cue the user that they
should not redefine a symbol, since there are plenty of other things
set in italics that the user _also_ shouldn't (try to) redefine.

I'm certainly open to hammering out a reasoned basis for typeface
selections, though.  Much of current practice arose in an ad hoc way.


[3] Warning: lengthy.

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

  parent reply	other threads:[~2021-11-12  9:35 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-11-11  1:53 [PATCH v2] mctp.7: Add man page for Linux MCTP support Jeremy Kerr
2021-11-11 21:38 ` Alejandro Colomar (man-pages)
2021-11-12  1:12   ` Jeremy Kerr
2021-11-12 18:45     ` Alejandro Colomar (man-pages)
2021-11-12 19:40       ` G. Branden Robinson
2021-11-12 20:07         ` Alejandro Colomar (man-pages)
2021-11-12 20:07           ` Alejandro Colomar (man-pages)
2021-11-18  5:08       ` Jeremy Kerr
2021-11-22 16:35         ` Alejandro Colomar (man-pages)
2021-11-12  9:35   ` G. Branden Robinson [this message]
2021-11-12 19:50     ` Alejandro Colomar (man-pages)
2021-11-22  9:06       ` Bold and italics, semantics and constness (was: [PATCH v2] mctp.7: Add man page for Linux MCTP support) G. Branden Robinson
2021-11-22 11:50         ` Alejandro Colomar (man-pages)
2021-11-22 13:52           ` G. Branden Robinson
2021-11-22 16:00             ` Alejandro Colomar (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20211112093536.hvifxgdtb2y6jzge@localhost.localdomain \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).