From: Keith Marshall <keith.d.marshall@ntlworld.com>
To: linux-man@vger.kernel.org, Alejandro Colomar <alx@kernel.org>
Subject: man page style conventions
Date: Sat, 13 Apr 2024 13:22:01 +0100 [thread overview]
Message-ID: <bcc2e2ec-32af-4254-a2c9-1884f28af407@ntlworld.com> (raw)
Hello,
In the man-pages(7) document, as rendered at:
http://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#man-pages.7
under the section heading "FORMATTING AND WORDING CONVENTIONS", and
subsection "Formatting conventions (general)", close to the bottom of
page 9, I see:
> Any reference to another man page should be written with the name in
> bold, always followed by the section number, formatted in Roman
> (normal) font, without any separating spaces (e.g., intro(2)). The
> preferred way to write this in the source file is:
>
> .BR intro (2)
I have noticed that, as of groff-1.23, both groff_man(7), and the macro
package which it documents, flagrantly ignore, and indeed violate this
convention. I further notice that man-pages(7) document, from which I
have quoted, above, appears to have been formatted using that very
version of groff_man(7), perhaps with the intro(2) reference, within the
quoted paragraph, having been formatted using:
.MR intro 2
rather than the recommended:
.BR intro (2)
This leads to a glaring anomaly, within the quoted paragraph; rather
than the topic name "intro" being set in bold, as the convention
demands, it is set in (non-bold) italics!
In my personal opinion, FWIW, the use of italics in this context is just
plain ugly. Opinion aside, it does not conform to the convention, as it
is stated in man-pages(7) -- either the convention needs to be changed,
by common consent, or groff_man(7) needs to be brought to heel.
--
Regards,
Keith.
next reply other threads:[~2024-04-13 12:45 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-13 12:22 Keith Marshall [this message]
2024-04-13 14:01 ` man page style conventions G. Branden Robinson
2024-04-13 18:39 ` Alejandro Colomar
2024-04-14 13:51 ` Lennart Jablonka
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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=bcc2e2ec-32af-4254-a2c9-1884f28af407@ntlworld.com \
--to=keith.d.marshall@ntlworld.com \
--cc=alx@kernel.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* 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 read-only IMAP folder(s) and NNTP newsgroup(s).