Phil Sutter <phil@xxxxxx> 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.
--
To unsubscribe from this list: send the line "unsubscribe netfilter-devel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
