RFC: Synopsis syntax change in nft.8

RFC: Synopsis syntax change in nft.8

[Phil Sutter]

Hi,

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

Let's look at an example:

| {add | delete | list | flush} \fBtable\fR [\fIfamily\fR] {\fItable\fR}

Since nobody wants HTML in emails, I used groff escape strings to
highlight the different font styles used:

\fB - start bold font
\fI - start italic font
\fR - start normal font

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? Anyway, next is
'family' in italic surrounded by brackets. The family is optional (says
the text below that line), so brackets are for optional things. They are
set in normal font style, so that style denotes meta info. What is
italic for then? Probably something which has to be replaced by
something else (read: 'non-terminal'). Sadly the synopsis doesn't
specify what the replacement might be, so there's a dead-end. Finally
there is 'table' in curly braces and italics. Curly braces around a
single item seems redundant (given the assumption made before), and
there is no explanation what 'table' has to be replaced with as well.
Looking at some examples again, 'family' and 'table' seem to stand for
single words one could fill in. Though for 'family' the choice is
limited (to known families) while 'table' allows a (nearly) arbitrary
string.

Sadly things get even more confusing when looking at the next synopsis,
namely that for chains. There e.g. 'priority' is not to be replaced by a
single word, but by 'priority <value>'. I guess you get the point.

In iproute2, there is an (unwritten) agreement to use the following
markups:

normal font: meta info (braces, pipes and the like)
bold font: things to be used literally ("keywords")
italic: non-terminals

Looking at ip.8 and ip-link.8, I notice that italic comes in lower- and
uppercase, and it's not clear which is what. And there are dead-ends as
well, sometimes intentional (things to be replaced by any string/number)
or unintentional to keep things sane (nobody needs a definition of how a
MAC address looks like).

For nft.8, I'd suggest the following:

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

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.

What do you think?

Cheers, Phil

Re: RFC: Synopsis syntax change in nft.8

[Florian Westphal]

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.

Re: RFC: Synopsis syntax change in nft.8

[Jan Engelhardt]

On Thursday 2017-08-10 20:29, Phil Sutter wrote:
>
>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?
>[...]
>
>In iproute2, there is an (unwritten) agreement to use the following
>markups:
>
>normal font: meta info (braces, pipes and the like)
>bold font: things to be used literally ("keywords")
>italic: non-terminals
>[...]
>
>What do you think?

The styling _is_ written down: The Linux man-pages project has, since Tue May
22 2007, a man-pages.7 file. It says: bold="as-is text", italic="replacable
arguments", talks about "[" "]" and "...", etc., just like you surmised.

Some history for the mail archives: {} is not specified, but follows from
prominent use of | inside [] and the desire to have some kind of grouping for
non-optional things. I will — cautiously — claim that {} was an idea of mine
(barring any fourth party uses in completely unrelated projects elsewhere that
I do not know of); commit iptables.git#a8ad34cf11540d147b8aded6826a1452841d2aa7
was the first to use '{}'.


So yes, consider any bugs you find to be unfortunate omissions in the
respective manpages' markup. Few people will probably remember ever having seen
man-pages.7.


>Looking at ip.8 and ip-link.8, I notice that italic comes in lower- and
>uppercase, and it's not clear which is what.

The iproute manpages could use some cleanup as well. Especially since "ersion"
is not something one should replace with something else like "abc".

 \fIOPTIONS\fP := { \fB-V\fP[\fIersion\fP] ...

should really be:

            ...   { \fB-V\fP[\fBe\fP[\fBr\fP[\fBs\fP[\fBi\fP[\fBo\fP[\fBn\fP]]]]]]

but that's ridiculous - writing

                  {\fB-V\fP|\fB-Version\fP}

is probably sufficient to get the idea across.

Re: RFC: Synopsis syntax change in nft.8

[Jan Engelhardt]

On Friday 2017-08-11 00:44, Jan Engelhardt wrote:
>Some history for the mail archives: {} is not specified, but follows from
>prominent use of | inside [] and the desire to have some kind of grouping for
>non-optional things. I will — cautiously — claim that {} was an idea of mine
>(barring any fourth party uses in completely unrelated projects elsewhere that
>I do not know of); commit iptables.git#a8ad34cf11540d147b8aded6826a1452841d2aa7
>was the first to use '{}'.

Ohwell, notsomuch. I found some {} in
iproute2#985794ad38a55b214fae1c51058a81febef1941b dated 2004, so that is
probably where I might have got the idea from. Credit where credit is due!

Re: RFC: Synopsis syntax change in nft.8

[Phil Sutter]

On Thu, Aug 10, 2017 at 11:55:03PM +0200, Florian Westphal wrote:
> FWIW I am not a docbook fan so I would not mind if we switch to
> another markup system.

I'd prefer to write directly in roff as well. Doing so would also
eliminate the dependency to docbook (which I had problems with when
packaging for RHEL).

Pablo, any last word on this? :)

Thanks, Phil

Re: RFC: Synopsis syntax change in nft.8

[Phil Sutter]

On Fri, Aug 11, 2017 at 12:44:25AM +0200, Jan Engelhardt wrote:
> On Thursday 2017-08-10 20:29, Phil Sutter wrote:
[...]
> >What do you think?
> 
> The styling _is_ written down: The Linux man-pages project has, since Tue May
> 22 2007, a man-pages.7 file. It says: bold="as-is text", italic="replacable
> arguments", talks about "[" "]" and "...", etc., just like you surmised.

Ah, indeed. Thanks for the reminder, this man page has served as good
guidance for me in the past already.

> Some history for the mail archives: {} is not specified, but follows from
> prominent use of | inside [] and the desire to have some kind of grouping for
> non-optional things. I will — cautiously — claim that {} was an idea of mine
> (barring any fourth party uses in completely unrelated projects elsewhere that
> I do not know of); commit iptables.git#a8ad34cf11540d147b8aded6826a1452841d2aa7
> was the first to use '{}'.

I guess it's just a short-cut and not really required. Obviously it
helps to separate the list of choices from the rest, for instance:

| nft add | delete ...

Which could be interpreted as "nft add" or "delete". But one could just
use a recursive approach instead of curly braces:

| nft COMMAND ...
| COMMAND := add | delete

In case one wonders what happens if that is consequently overdone, I
suggest having a look at ip-route(8) and trying to quickly figure what
options are available when adding a route. :)

[...]
> >Looking at ip.8 and ip-link.8, I notice that italic comes in lower- and
> >uppercase, and it's not clear which is what.
> 
> The iproute manpages could use some cleanup as well. Especially since "ersion"
> is not something one should replace with something else like "abc".

Hehe, yes. I consider iproute2 man pages a moving target in between
syntax fixes and enhancements with broken syntax ...

>  \fIOPTIONS\fP := { \fB-V\fP[\fIersion\fP] ...
> 
> should really be:
> 
>             ...   { \fB-V\fP[\fBe\fP[\fBr\fP[\fBs\fP[\fBi\fP[\fBo\fP[\fBn\fP]]]]]]
> 
> but that's ridiculous - writing
> 
>                   {\fB-V\fP|\fB-Version\fP}
> 
> is probably sufficient to get the idea across.

FWIW, there are cases where it matters: 'ip link s' completes to 'set',
not 'show'. That though is not covered by synopsis section of ip-link(8).

Thanks, Phil