Re: man page, usage text and filter expression formatting

[Denis Ovsienko <denis () ovsienko info>]

On Fri, 17 Oct 2025 22:14:58 +0100
Denis Ovsienko <denis () ovsienko info> wrote:

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

Forgot to mention another motivation for a better formatting
convention.  When pcap_compile() returns an error, sometimes the error
string would be much easier to relate with the filter expression if the
string included the offending primitive using just the right amount of
specificity.

For example, in this case the message includes the values that comprise
the ID, which is correct because the problem is with the values only:

$ filtertest RAW 'ip host 1.2.3.4 mask 255.255.0.0'
filtertest: non-network bits set in "1.2.3.4 mask 255.255.0.0"

However, in this case the ID is well-formed and the problem is the
semantics, but the message is a bit vague:

$ filtertest RAW 'ip host 1.2.0.0 mask 255.255.0.0'
filtertest: Mask syntax for networks only

Trying to produce a better message using the current format from the
man page could result in:

"'ip host netaddr mask netmask' is not a valid primitive"

which is not really readable.  However,

"'ip host <netaddr> mask <netmask>' is not a valid primitive"

or

"'ip host NETADDR mask NETMASK' is not a valid primitive"

would convey the meaning much better.  Arguably, for this primitive it
would be better to label the placeholders as <ipv4addr> and <ipv4mask>
because the primitive is IPv4-only.

But the main point is, sometimes it is appropriate to quote the ID
literally to indicate a problem with the value ("this particular
hostname failed to resolve"), and sometimes it is appropriate to use a
placeholder to convey the context more specifically on the one hand,
but not unnecessarily specifically on the other ("this primitive form,
which takes a hostname, is not valid with this qualifier or this DLT").

This is why it would be nice to have a means to spell placeholders in
the error messages (which are plain text) consistently with
pcap-filter(7) (which can be a proper man page, an HTML page or
sometimes even plain text).

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