netdev - Re: [PATCH net-next 2/2] tools: bpf: add bpftool

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Wed, 27 Sep 2017 13:49:58 +0200
From:   Markus Heiser <markus.heiser@...marit.de>
To:     Jesper Dangaard Brouer <brouer@...hat.com>,
        Jonathan Corbet <corbet@....net>
Cc:     Jakub Kicinski <jakub.kicinski@...ronome.com>,
        Alexei Starovoitov <alexei.starovoitov@...il.com>,
        netdev@...r.kernel.org, daniel@...earbox.net, davem@...emloft.net,
        hannes@...essinduktion.org, dsahern@...il.com,
        oss-drivers@...ronome.com,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Subject: Re: [PATCH net-next 2/2] tools: bpf: add bpftool

> Am 27.09.2017 um 13:19 schrieb Jesper Dangaard Brouer <brouer@...hat.com>:
[...]
>>> I would prefer adding a README.rst file, in RST-format, as the rest of
>>> the kernel documentation is moving in that direction[1] (your github
>>> version is in README.md format).  A man page will always be
>>> out-of-sync, and even out-of-sync on different distros.
>>> 
>>> See[1]: https://www.kernel.org/doc/html/latest/
>>> 
>>> And then I would find some place in Documentation/admin-guide/ and
>>> include the README.rst file, so it shows up at [1].
>>> 
>>> RST have an include method like:
>>> 
>>> .. include:: ../../tools/bpf/bpftool/README.rst  
>> 
>> Can the docs in new format be rendered into a man page?  Call me old
>> fashioned but I think we should provide some form of a man page.. :)
> 
> Yes, simply create the man page like:
> 
> rst2man README.rst README.man
> You can add this to your local makefile.

Hm ... this will work only for simple reST files.

FYI: Sphinx is build up on top of docutils extending the reST markup. Tools
like rst2man are from docutils and do not cover the markup extensions
from Sphinx. Since Sphinx has its own builder for man pages, generating
man pages is not the problem ...

> The standard sphinx build can also generate man-pages, but it have been
> removed from the kernel makefile targets:
> 
> Documentation targets:
> Linux kernel internal documentation in different formats from ReST:
> htmldocs        - HTML
> latexdocs       - LaTeX
> pdfdocs         - PDF
> epubdocs        - EPUB
> xmldocs         - XML
> linkcheckdocs   - check for broken external links (will connect to external hosts)
> cleandocs       - clean all generated files

The reason why we have no man page target is, that we have not yet
evaluated a concept, how we can manage the 'build man pages' task in
the kernel build.

Beside what you find in the kernel-source tree I'am working on such
a concept (adapted man page builder for the Kernel) [1].

IMO: Even if we merge the builder from [1] or implement something different,
we have to touch the current kernel-doc parser. I guess that and the absence
of a handy concept is the reason why we are dangling with a 'man' target.

Anyway, these are my estimations, it might be better if we hear what
Jon think about a man page builder (concept).

[1] https://return42.github.io/linuxdoc/linuxdoc-howto/man-pages.html

-- Markus --