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