Re: [nft PATCH RFC] Convert man page source to asciidoc

[Phil Sutter <phil@nwl.cc>]

Hi Arturo,

On Wed, Sep 06, 2017 at 11:56:37AM +0200, Arturo Borrero Gonzalez wrote:
> On 6 September 2017 at 10:41, Phil Sutter <phil@nwl.cc> wrote:
> > Beware: The conversion is incomplete and merely serves as base for
> > discussion.
> >
> > This patch converts nft.xml into asciidoc markup, top down until (and
> > including) stateful objects description. I stopped there because it's
> > the first chance of demonstrating my idea of splitting the documentation
> > into smaller pieces for convenience and maintainability.
> >
> > Regarding package dependencies, this "just" exchanges docbook with
> > asciidoc - dblatex is still required for PDF creation.
> >
> 
> Hi Phil,
> 
> thanks for your initiative and hard work, it's really appreciated :-)

Thanks!

> Regarding the change, why asciidoc? why not markdown, or org-mode or
> reStructuredText?

Well, asciidoc is basicaly markdown on steroids, I fear we'll soon miss
features if we stuck to plain markdown. Also see this URL for a
comparison: [1].

I tend to ignore org-mode because I'm not an emacs user, and I guess
about 50% of (potential) nftables contributors feel the same about that.
:)

Regarding reStructuredText, did you look at how tables are written
there? If not, see here[2]. I really think that speaks for itself.

> There are many markup languages, it reminds me to xkcd #927 [0].

Well, the difference here is that I'm not inventing anything new but
search for better options amongst the existing solutions. :P

> I would prefer if we stick to groff, which seems to be the standard in Linux.

Yes, this is the very basic alternative but as said I think providing
users with an easier to use markup makes sense.

> Regarding the separation of text in different includes, why not
> creating different manpages?
> Netfilter did this in the past with iptables(8) and iptables-extensions(8).
> 
> Brainstorming:
> * nft(8) <-- main document, general info
> * nft-ct(8) <-- concrete info for ct objects
> * nft-counter(8) <-- concrete info for counter objets
> * nft-flowtables(8) <-- about flow tables
> * nft-quota(8) <--- concrete info for quotas
> * nft-performance(8) <--- concrete info about nftables sets, maps,
> dicts, concatenations, etc.
> * nft-ha(8) <--- for HA environments, loadbalancing etc

Well, I don't think nft.8's current size requires to split it into
smaller files at this point.

Cheers, Phil

[1] https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/asciidoc-vs-markdown.adoc
[2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables