Hi all, So sounds like moving ahead with rst/sphinx is the option that should allow us to address everyone's concerns eventually? Of course the first one won't have it all (media seems really tricky), but I'd like to get something awesome in this area closer to mainline. I'm stalling on typing more fancyful gpu docs right now (with tables, pictures and stuff) since that would require a pile of needless work to redo when we switch a few times more ;-) And Jani also wants to get this in, but he doesn't really want to spend more effort on a system that can't be merged. So sphinx/rst y/n? Jon, is that ok with you from the doc maintainer pov? Cheers, Daniel On Wed, Apr 27, 2016 at 4:28 PM, Grant Likely <grant.likely@xxxxxxxxxxxx> wrote: > On Tue, Apr 12, 2016 at 4:46 PM, Jonathan Corbet <corbet@xxxxxxx> wrote: >> On Fri, 8 Apr 2016 17:12:27 +0200 >> Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: >> >>> motivated by this MT, I implemented a toolchain to migrate the kernel’s >>> DocBook XML documentation to reST markup. >>> >>> It converts 99% of the docs well ... to gain an impression how >>> kernel-docs could benefit from, visit my sphkerneldoc project page >>> on github: >>> >>> http://return42.github.io/sphkerneldoc/ >> >> So I've obviously been pretty quiet on this recently. Apologies...I've >> been dealing with an extended death-in-the-family experience, and there is >> still a fair amount of cleanup to be done. >> >> Looking quickly at this work, it seems similar to the results I got. But >> there's a lot of code there that came from somewhere? I'd put together a >> fairly simple conversion using pandoc and a couple of short sed scripts; >> is there a reason for a more complex solution? >> >> Thanks for looking into this, anyway; I hope to be able to focus more on >> it shortly. > > Hi Jon, > > Thanks for digging into this. FWIW, here is my $0.02. I've been > working on restarting the devicetree specification, and after looking > at both reStructuredText and Asciidoc(tor) I thought I liked the > Asciidoc markup better, so chose that. I then proceeded to spend weeks > trying to get reasonable output from the toolchain. When I got fed up > and gave Sphinx a try, I was up and running with reasonable PDF and > HTML output in a day and a half. > > Honestly, in the end I think we could make either tool do what is > needed of it. However, my impression after trying to do a document > that needs to have nice publishable output with both tools is that > Sphinx is easier to work with, simpler to extend, better supported. My > vote is firmly behind Sphinx/reStructuredText. > > g. -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
