On Mon, 20 Oct 2025 20:24:50 +0200 Francois via tcpdump-workers <[email protected]> wrote:
> On 20/10/2025 20:17, Denis Ovsienko wrote: > > On Mon, 20 Oct 2025 11:43:27 -0400 > > enh via tcpdump-workers <[email protected]> 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 -- [email protected] To unsubscribe send an email to [email protected] %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
