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]
Message-Id: <C92884FB-9948-4CCF-9B58-7811691F6574@darmarit.de>
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 --

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ