Re: man page, usage text and filter expression formatting

[Guy Harris <gharris () sonic net>]

On Oct 17, 2025, at 2:14 PM, Denis Ovsienko <denis () ovsienko info> 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 -- tcpdump-workers () lists tcpdump org
To unsubscribe send an email to tcpdump-workers-leave () lists tcpdump org
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s