On Oct 17, 2025, at 2:14 PM, Denis Ovsienko <[email protected]> wrote:
> This is a side effect of stripping all style formatting from the source
> man page, which in both the man page viewer and the HTML rendering [1]
> uses italics for the placeholders.
Or, for the man command on at least some UN*Xes, uses underlining for the
placeholders, mapping italics to underlining.
At least with 1) mandoc's version of the man command and 2) the Terminal
terminal emulator on my Mac, *if* the man command is writing to the terminal,
it uses escape sequences to italicize by using underlining. I think some
versions of nroff could do the same.
If I send the output of man to a file, it uses underscore, backspace, character
to italicize the character. The Terminal app doesn't turn those into italics,
but the more command does.
So there's no guaranteed mechanism to man italics visible in plain text.
Part of the problem here is that the -man macro package doesn't have sufficient
semantic markup - there's no way to mark something as an argument to a command
or command-line flag (for programs) or to a function (for APIs). I think
Berkeley's -mdoc package does a better job; unfortunately, it's not as
universally available as -man, so using it isn't an option.
The original V7 man page for the ar command uses .I to italicize arguments (and
.B for literal text, such as command-line flag names). I don't know to what
extent the folks at Bell Labs used printing terminals, where
underscoring-for-italicizing (and multiple-overstriking-for-boldfacing) would
work.
The POSIX/SUS "Utility Argument Syntax" section cited in an earlier message is
oriented towards print and rich-text display forms, in which italic text and
fixed-width text are distinguishable from "normal" text. They do mention the
angle bracket convention for command-argument variables, which is a convention
that probably grew up as an alternative to italicizing for use in contexts
where you didn't have italicizing, or even underscoring-for-italicizing,
available.
> However, running "rpcapd -h" prints a usage message that follows a
> different convention for placeholders:
The angle-bracket convention is an appropriate convention when it's
overwhelmingly likely that you're printing to a terminal, but there's no
guaranteed way to get italics or boldface.
> This formatting convention works well for a portable (i.e. ASCII) usage
> message, it is also rather common and can be seen in usage messages of
> GCC, Clang, CMake and many other programs. That said, for the man
> pages and the online HTML documentation Clang and CMake use angle
> brackets, whilst GCC uses italics.
Perhaps Clang and CMake are out of step with the general man-page convention.
I've generally just seen italicization.
So, a convention survey on various UN*Xes I have available on VMs:
Ubuntu 24.04:
GNU ar - in the man page, italics for placeholders
in the help message, nothing for command argument
placeholders, angle brackets for placeholders for short options, capital
letters for placeholders for long options
GNU ls - in the man page, italicized capital letters for placeholders
in the help message, capital letters for placeholders,
italicized if they're for long option and are optional
OpenSSH ftp - in the man page, italics for placeholders
in the help message, nothing special for placeholders
So, not surprisingly, no consistency, given that commands come from various
projects.
I suspect the same will be true of the BSDs, including CupertinoBSD; all of
them have made some attempt to replace GPLed commands with more permissively
licensed equivalents.
Solaris 11:
ar - in the man page, italics? (inverse text) for placeholders
in the help message, nothing special for placeholders
ls - in the man page, italics? (inverse text) for placeholders
in the help message, nothing special for placeholders
and, for a commercial UNIZ with no x86 version (so not available in any of my
VMs):
> For reference, AIX 7.1 sed uses yet another convention for both the man
> page and the usage message:
>
> Usage: sed [-n] [-u] Script [File ...]
> sed [-n] [-u] [-e Script] ... [-f Script_file] ... [File ...]
AIX... is, once again, *different* here.
> This way, one problem is that libpcap, tcpdump and tcpslice do not
> format the usage messages consistently and unambiguously, the use of
> angled brackets or uppercase placeholders would solve that.
I'd vote for angle brackets; I've seen that more than uppercase.
> Another problem is that the placeholders do not survive stripping the style
> from
> the man pages.
I'd vote for italics, as that seems to be what most man pages do; losing that
when stripping style will affect plenty of other projects' man pages as well.
_______________________________________________
tcpdump-workers mailing list -- [email protected]
To unsubscribe send an email to [email protected]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
