Re: RFC: Synopsis syntax change in nft.8

[Florian Westphal <fw@strlen.de>]

Phil Sutter <phil@nwl.cc> wrote:
> When looking at nft man page for the first time, I remember finding the
> synopsis for individual commands (e.g. 'add table') rather misleading. I
> am biased, but the (BNF style) syntax used in the various iproute2 man
> pages is much more precise, so I would like to copy that for nft.8. The
> actual SYNOPSIS section at the top gets is quite right, BTW (apart from
> some minor flaws in font styles).

I have no objections.

> With no prior knowlege of how this syntax works, we start parsing the
> line from left to right and find out that something like:
> 
> | {foo | bar}
> 
> probably means "either 'foo' or 'bar'", no big deal. Next comes 'table'
> in bold font. What does bold mean? Looking at some examples, table seems
> to be a keyword ('terminal' in BNF-speak). But so are 'add', 'delete',
> 'list' and 'flush', so why are they in normal font?

Probably just because there are different authors...

[..]

 
> normal font: meta info (as above)
> bold font: keywords (as above)
> italics UPPERCASE: non-terminals, followed by a definition
> italics lowercase: non-terminals, not followed by a definition

LGTM.

> I am not overly familiar with docbook, so that might use other font
> styles for the different kinds we need. Also, I like to use the same
> font style when referring to elements in prose, which nicely draws
> readers attention while skimming through the text searching for
> explanations of things. Though I have no idea whether docbook allows for
> that without hacks.

FWIW I am not a docbook fan so I would not mind if we switch to
another markup system.