Re: man page, usage text and filter expression formatting

[Francois via tcpdump-workers <tcpdump-workers () lists tcpdump org>]

> --- Begin Message ---
>
>
> From: Francois <devel.fx.lebail () orange fr>
>
> Date: Mon, 20 Oct 2025 20:24:50 +0200
>
> 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.
>
>
>
> --- End Message ---
_______________________________________________
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