Re: [nft PATCH 1/2] nft.8: Fix and enhance synopsis section

[Phil Sutter <phil@nwl.cc>]

Hi Pablo,

On Mon, Aug 28, 2017 at 06:58:53PM +0200, Pablo Neira Ayuso wrote:
> On Thu, Aug 17, 2017 at 03:38:59PM +0200, Phil Sutter wrote:
> > This patch addresses shortcomings in the main synopsis section
> > illustrating possible invocations of nft command:
> > 
> > - Fix font styles to correctly put options into bold font and meta
> >   characters (brackets, pipes) into normal font.
> > 
> > - Add missing options to synopsis line.
> > 
> > - Use curly braces where either one of the alternatives is required.
> > 
> > - Remove choice="opt" attribute since that is the default anyway.
> > 
> > - Note that --includepath option is allowed to be given multiple times.
> 
> I'm going to apply this.

Thanks!

> I'm undecided with 2/2,

>From my side, this is according to (the hidden) plan. :)

> I don't remember to have seen such indirections in other manpages?

>From iproute2 (as said, I'm biased), I'm used to stuff like this:
	
| nft [ OPTIONS ] ...
|
| OPTIONS := [ OPTIONS ] OPTION
| OPTION := [ -a | -e | -n ]

Maybe for others it's more of an obstacle to parse this recursive style,
it really seems intuitive to me at least. And it's a quite efficient way
to define the syntax in a very precise manner.

Of course it's nice to have some layer of abstraction to allow for
formatting into other markups, like HTML for example. So I'll have a
look at alternatives which will keep that flexibility yet allow for the
style I prefer (unless you consider it not much more readable than what
docbook offers).

Thanks, Phil