linux-kernel - Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <20160608134954.10439cce@lwn.net>
Date:	Wed, 8 Jun 2016 13:49:54 -0600
From:	Jonathan Corbet <corbet@....net>
To:	Daniel Vetter <daniel.vetter@...ll.ch>
Cc:	Markus Heiser <markus.heiser@...marit.de>,
	Jani Nikula <jani.nikula@...el.com>,
	Grant Likely <grant.likely@...retlab.ca>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Keith Packard <keithp@...thp.com>,
	Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	linux-doc@...r.kernel.org, Hans Verkuil <hverkuil@...all.nl>
Subject: Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

So I've finally gotten a chance to make another pass over this stuff.

Markus, your enthusiasm is great; I'm hoping you'll do great things
helping us to improve the kernel's documentation toolchain.  But please,
at this point, let's build on Jani's work and go from there.  Things have
waited for long enough while we've gone around on this; I think what we
have is a good starting point.

On the specifics, Daniel already covered most of it pretty well.

On Tue, 7 Jun 2016 09:54:21 +0200
Daniel Vetter <daniel.vetter@...ll.ch> wrote:

> I think next steps would be:
> - rebase flat-table onto Jani's work and relicense under gplv2

This I would really like to see.

> - look into rewriting kernel-doc in python more as a long-term project

There is nobody who would like to dump the Perl kernel-doc more than I
would; it wasn't pretty to begin with and hasn't improved over the years.
I, too, had thought about redoing it, but I, too, concluded that it wasn't
the highest of priorities.

Please do keep this around, we may want it before too long.  I have some
sympathy for Daniel's suggestion to look into using LLVM; we could also
maybe stay a little closer to our roots and use the sparse library.  But
there might also be value in a Python version that doesn't add more
dependencies to the docs toolchain.  We need to think about this, but I
don't think we need to answer it now.

> - start converting docs instead - I really want to start reaping
> benefits of all this work as soon as possible.

Absolutely.

Along these lines, I don't currently have a strong opinion on the
big-files vs. little-files question.  I *do*, however, like the idea of
trying to create one coherent kernel document rather than perpetuation our
current collection of independent book silos.  Initially it will certainly
look like the LDP-based books that people used to duct-tape together back
in the 90's, but it should improve over time.

Thanks,

jon