netfilter buglog - Sep 2018 - [Bug 1279] New: manpage documentation inconsistencies

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>

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

moe <netfilter.moschroe at xoxy.net> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |netfilter.moschroe at xoxy.net

-- 
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/20181214/3c31db41/attachment.html>

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

kfm at plushkava.net changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |kfm at plushkava.net

-- 
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/20200128/70faf829/attachment-0001.html>