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 for Android: free password hash cracker in your pocket

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

Message-ID: <87wpm15q7q.fsf@intel.com>
Date:	Tue, 07 Jun 2016 11:59:53 +0300
From:	Jani Nikula <jani.nikula@...el.com>
To:	Daniel Vetter <daniel.vetter@...ll.ch>,
	Markus Heiser <markus.heiser@...marit.de>
Cc:	Jonathan Corbet <corbet@....net>,
	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

On Tue, 07 Jun 2016, Daniel Vetter <daniel.vetter@...ll.ch> wrote:
> I think getting the flat-table directive landed would be great. We
> have a similarly annoying table in gpu.tmpl where the ascii-art tables
> fall short and are annoying. We want to split it up, but that's not a
> short-term solution suitable for conversion. Atm it's licensed under
> gplv3, which is incompatible with the kernel, so need to fix that.

Agreed.

> I'm still not sold on the vintage-kerneldoc idea. At least in my
> experience (after first converting to asciidoc and now to sphinx) this
> is a non-issue. Yes, there's the oddball misrendering, but that's no
> worse than the oddball typo. And a really good way for
> drive-by-contributors and newbies to send in a few useful patches.
> Personally I'm totally happy to have that bit of ugliness, same way I
> don't reject patches just because they trip over checkpatch.pl in some
> minor detail. The downside otoh means we'll have to forever maintain 2
> versions of kernel-doc, and I don't want that. Jani&me have already
> ripped out some of the more bonghits features of kernel-doc (like
> anything with a \w: is a heading and other nonsense like that). The
> only thing we really need to keep as special is the overall kerneldoc
> layout, and the special referencing using &, %, @ and friends.

Agreed.

> Reimplementing kernel-doc in python is also something Jani&I
> discussed. But I think it only makes sense if we go ahead and also
> modernize the parser, i.e. use something like python-clang to parse C,
> and build a modern parser-combinators thing for the kernel-doc itself.
> The regex state machinery is a horror show, whether it's written in
> cargo-culted perl or python.

I think the only sensible way to change the parser is to get everything
working using the perl version first, and then you can diff the results
against the python version. That's about the only validation of the new
parser that actually matters in the real world.

At this time, I'd put this way down in the list of priorities.

> I agree that we need to update the kernel-doc howto (and Jani's
> working on that already too), but I think there's no need to split up
> that finely. Maybe that's a bit against sphinx best practices, but
> right now we have rather large documents (both plain text and
> docbook). Splitting definitely makes sense in some cases (e.g.
> gpu.tmpl is only this large because we couldn't do cross-template
> referencing), but by-and-large I think the current splitting is mostly
> reasonable.

One of the key arguments against too much splitting that hasn't been
mentioned is that despite all the fine output Sphinx can produce, we
have plenty of people who couldn't care less about running Sphinx to get
readable documentation. They will grep and read the plain text files
directly, and that's a large part of the appeal of any lightweight
markup.

When you split up a file into snippets that no longer tell a coherent
story independently, you've failed.

For the .txt files under Documentation, we mostly do not want to split
them up any more if and when they're converted to rst. For the .tmpl
files under Documentation/DocBook, each rst file split off from there
should still be a sensible document on its own, with the filename
telling what it's about. This will be the main benefit of this whole
exercise for the people who do not care about Sphinx - instead of
reading (read: ignoring) DocBook XML, they can now read the rst files.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center