Re: man page, usage text and filter expression formatting

[Vadim Goncharov <vadimnuclight () gmail com>]

On Mon, 20 Oct 2025 20:24:50 +0200
Francois via tcpdump-workers <tcpdump-workers () lists tcpdump org> wrote:

> On 20/10/2025 20:17, Denis Ovsienko wrote:
> > On Mon, 20 Oct 2025 11:43:27 -0400
> > enh via tcpdump-workers <tcpdump-workers () lists tcpdump org> wrote:
> >
> > > https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/basedefs/V1_chap12.html#tag_12_01
> > > is the canonical source for how to write your command synopses in a
> > > man page...
> >
> > Thank you for finding the reference.  Section 12.4.1 seems to mean that
> > angle brackets combined with italic font would be an acceptable style,
> > even though POSIX-1003.1-2024 itself uses this style only a few times,
> > and not for command-line arguments.  In any case, it would be one of the
> > well-known conventions.
> >
> > I wonder if there is a software project that has already identified the
> > best possible solution to this exact problem.
>
> I try the two changes.
> Angle brackets make texts difficult to read, especially with square brackets.
>
>        vlan [<vlan_id>]
>               True if the packet is an IEEE 802.1Q VLAN packet.   If  the
> op- tional  <vlan_id>  is specified, only true if the packet has the
>               specified <vlan_id>.  Note that the first vlan  keyword
> encoun- tered  in an expression changes the decoding offsets for the re-
>               mainder of the expression on the assumption that the packet is
> a VLAN  packet.   The  `vlan [<vlan_id>]` keyword may be used more
>               than once, to filter on VLAN hierarchies.  Each use of that
> key- word increments the filter offsets by 4.
>
>        vlan [VLAN_ID]
>               True if the packet is an IEEE 802.1Q VLAN packet.   If  the
> op- tional  VLAN_ID  is  specified,  only true if the packet has the
>               specified VLAN_ID.  Note that the first vlan keyword
> encountered in  an expression changes the decoding offsets for the remainder
>               of the expression on the assumption that the packet  is  a
> VLAN packet.   The  `vlan  [VLAN_ID]`  keyword  may be used more than
>               once, to filter on VLAN hierarchies.  Each use of  that
> keyword increments the filter offsets by 4.

Disagree. The bare uppercase makes it difficult to read when there are other
abbreviations near it, e.g. IEEE or VLAN itself in this example - too similar
to VLAN_ID, and examples in other parts may happen without easily-distinguishing
things like underscore here. Square brackets, on the other hand, are just two
symbols combined, which you easily get accustomed, especially if having an
experience with programming languages where more than two punctuation symbols
is very common (and even not-so-programming but e.g. web-design/HTML).

-- 
WBR, @nuclight
_______________________________________________
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