On Tue, 07 Jun 2016, Daniel Vetter <daniel.vetter@xxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
