[Bug 1279] New: manpage documentation inconsistencies

[bugzilla-daemon at netfilter.org]

https://bugzilla.netfilter.org/show_bug.cgi?id=1279

            Bug ID: 1279
           Summary: manpage documentation inconsistencies
           Product: nftables
           Version: unspecified
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P5
         Component: nft
          Assignee: pablo at netfilter.org
          Reporter: mqus at disroot.org

I have multiple small(ish) issues with the documentation, mainly the man page
and the output on nft --help:

1: nft --help lists the -j switch to format the output in json. this is both
not working (e.g. "nft list table inet filter -j" doesn't output things in
json) and documented in the man page, so this should be reflected in the --help
output

2: the nft man page describes 'nft export' as supporting json and xml formats.
If I try this on my machine (archlinux, nft v0.9.0), it supports neither, and
if I try 'nft export' it suggests to use 'nft export vm' and 'nft export vm
json' successively, with the last one actually outputting json. Why are xml and
json documented in the manpage but not supported in the tool, and why is 'vm'
(what does that mean, anyway?) supported but not documented? 
The solution here would be to document the export better, e.g. mention that
perhaps json and xml support have to be enabled on build time (see 2.1) and
maybe mention vm (even if only as deprecated/unsupported/internal, because one
would eventually stumble on it with the 'expecting  [...]' error messages)

2.1: related to 2: where is mentioned that jansson is needed for displaying
json? 
 I only found it out by looking through the build files/source code, but
looking at https://netfilter.org/projects/nftables/index.html (which lists the
neccessary libraries), https://git.netfilter.org/nftables/tree/INSTALL (which
lists install dependencies) and
https://wiki.nftables.org/wiki-nftables/index.php?title=Special%3ASearch&search=jansson&go=Go
I can't find any way a packager or user would find out about it. The same goes
for xml output (didn't look up the specific library).

3: nft list tables
This is a command I find most useful but is actually not listed in the man
page. Are there more commands like this which output a space-separated table?
This is really useful for scripting.

3.1 nft list meter
This is part of an example on the set statement in the manpage. But apart from
that, meters are not documented at all. Are they the same as 'counter' or
'quota'?

4: handles
The handle concept could be explained better in the manpage (e.g. Is there a
reason I should delete sets/chains/tables/... by their handle and not by their
name?)

5: meta expressions (manpage)
It is explained that there are unqualified and qualified meta expressions, but
as I'm a noob I can't understand what qualified and unqualified actually means.
Is the only difference the 'meta' keyword or is there a difference in meaning?
I don't think that I'm the only one wondering about this and therefore think
this should be explained.

6: fib expressions
The only thing I don't understand here is the syntax of the expression
notation. The nested curly braces are not really intuitive.

7: nft add rule 
This part of the manpage mentions that a rule consists of one or multiple
statements. but the way statements are defined below (only actions), the actual
rule consisting of expressions (and how these can be combined/composed) is not
explained at all.

I'm currently working on a zsh completion script for nft and these things are
important to me as I'm practically adding another small subset of documentation
to the completion script.

-- 
You are receiving this mail because:
You are watching all bug changes.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.netfilter.org/pipermail/netfilter-buglog/attachments/20180906/5241a14a/attachment.html>