man page, usage text and filter expression formatting

[Denis Ovsienko <denis () ovsienko info>]

Hello all.

Last year Francois-Xavier made a point that rpcapd man page and usage
message mix two formatting conventions for command-line option
arguments.  The man page, when formatted as plain text, does not make
it clear that "address", "port", etc. are placeholders, also known as
meta-variables:

       rpcapd [ -b address ] [ -p port ] [ -t data_port ] [ -4 ] ...

       -b address
              Bind to the IP address specified by address ...

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.  The latter is the recommended
formatting convention for man pages, also the same can be seen in the
POSIX specification, as well as in the classic UNIX and Linux System
Administration Handbook, as well as in the Advanced Bash Scripting
Guide.  This seems a good style as far as typographic conventions go.

However, running "rpcapd -h" prints a usage message that follows a
different convention for placeholders:

USAGE: rpcapd [-b <address>] [-p <port>] [-t <data_port>] [-4] ...

  -b <address>    the address to bind to (either numeric or literal).

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.

Yet another portable convention is to format placeholders in uppercase,
as can be seen in GNU tar:

Usage: tar [OPTION...] [FILE]...

      --level=NUMBER         dump level for created listed-incremental
      archive

The same stands for GNU Autoconf:

       -W, --warnings=CATEGORY
              report the warnings falling in CATEGORY [syntax]

The same can be seen in Python programs that use the built-in argparse
library.  GNU sed almost (note the "input-file") follows the same
convention:

Usage: sed [OPTION]... {script-only-if-no-other-script} [input-file]...

  -i[SUFFIX], --in-place[=SUFFIX]

Anyway, let's say rpcapd now implements the same as GCC: angle brackets
for the usage message and italics for the man page.  tcpdump and
tcpslice also use italics for the man pages, but, inconsistently, no
formatting for the usage message:

Usage: tcpdump [-AbdDefhHIJKlLnNOpqStuUvxX#] [ -B size ] [ -c count ]

Usage: tcpslice [-DdhlRrtv] [-w file]

This is exactly the same as what NetBSD sed does:

Usage:  sed [-aEGglnru] command [file ...]
        sed [-aEGglnru] [-e command] [-f command_file] [-I[extension]]
            [-i[extension]] [file ...]

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 ...]

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.  Another
problem is that the placeholders do not survive stripping the style from
the man pages.  But these problems are neither big nor urgent, so I
suggested to think about it before changing anything.

Meanwhile I have also been working on the pcap-filter(7) man page [2],
and at some point I realised it belongs to the same problem space.
Consider, for example, the following:

       gateway host
              True  if the packet used host as a gateway.  I.e., the

Here the source man page applies bold to "gateway" and italics to
"host", which shows that the former is a keyword and the latter is a
placeholder.  The typographic convention makes as much sense in the
HTML page as in a book or a PDF document.  But as soon as you copy it
to a media that discards the style (as can be seen just above in this
plain text e-mail), it no longer works as intended.

One way to solve this problem would be using "keyword <arg>" or
"keyword ARG" or even "keyword <ARG>" syntax for all filter primitives.
Note that this would not conflict with the use of italics: for example,
if you consider GNU tar man page, both the "ARCHIVE", the "OPTIONS" and
the "FILE" are in italics (that is, underlined in most cases, unless the
session is cleverly configured to use the capabilities of modern
terminals):

       tar -c [-f ARCHIVE] [OPTIONS] [FILE...]

(GNU Autoconf man pages and the HTML/PDF manual implement the same.)

Whichever potential new convention for pcap-filter(7), if it could
work better with and without formatting, it would be useful to apply it
consistently to the command-line options as well and to make it the
house style.  Does anybody have an opinion, a preference or anything
else to say about to such a change?

1: https://www.tcpdump.org/manpages/rpcapd.8.html
2: https://www.tcpdump.org/manpages/pcap-filter.7.html

-- 
    Denis Ovsienko
_______________________________________________
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