Date:	Tue, 7 Jun 2016 11:36:33 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jani Nikula <jani.nikula@...el.com>
Cc:	Daniel Vetter <daniel.vetter@...ll.ch>,
	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


Am 07.06.2016 um 10:59 schrieb Jani Nikula <jani.nikula@...el.com>:

> 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.

see last mail 

>> 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.

see last mail

>> 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 tested the python version of the parser by running it over nearly
the whole kernel-tree .. yes this is not a side by side test, but I also
tested it by partial side by side comparing the output of [1]

[1] https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc 

I spend over a week in testing ... IMO in the meantime the quality
of the python parser is a bit over the perl one. But at the end,
I have never seen a "error free implementation". 


>> 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.

But they have read XML or compiled DocBook XML? ... Sphinx brings a
search engine with its html.

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

Chapters are breaking stories?

> 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.

Sorry but in IMO this suggestion is backward, if someone don't be able
to build HTML documents he should at least be able to use the
internet [1] :-o

[1] http://return42.github.io/sphkerneldoc/articles/books.html

> 
> BR,
> Jani.
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

Powered by blists - more mailing lists