On Fri, 10 Jun 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > Am 08.06.2016 um 21:49 schrieb Jonathan Corbet <corbet@xxxxxxx>: >> 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. > > I'am willing to contribute, but take my POV: I have finished all > including migration of **all** DocBook to reST, so why should I > throw it all away? Nobody is asking you to throw it away; we're asking you to rebase that work, with some modifications, on top of docs-next, which now has my work merged. > are your friends. You will see that all requirements to get > productive are well done. Within the next days I will > add more features, which has been requested on the ML. OTOH, if you do keep working on a baseline that no longer applies to docs-next, you will be wasting your efforts. > nevertheless which kind of implementation is used, the parsers are all > exchangeable. There is only the user interface which has to be stable > and this is the ".. kernel-doc:" directive. > > I implemented a python version of the kernel-doc parser with an (python) > API, so why should we fiddle with perl and pipes when implementing > a ".. kernel-doc:" directive? No matter how hacky the perl script seems, it has been used on the kernel sources for nearly two decades. Sure, it has accumulated more than a little cruft along the way, but also a lot of corner cases and gotchas have been ironed out. I wouldn't dream of replacing that until we've migrated a bunch of documents using it, and can confirm the replacement produces the same output. Also, there may still be users for the perl script outside of the Sphinx pipeline. I'd like to make sure we don't end up having to maintain *two* homebrew scripted C parsers before adding a new one. >> 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. > > Placing all DocBooks in one huge sphinx-project does not scales well > and brings to additional dependencies. To solve this problem > I use intersphinx and a index-page where all books are referred. On the modifications, I'll repeat that I strongly object to maintaining that arbitrary distinction between "books" and other files. We had that with DocBook, and we'd be more than happy to get rid of it. I object to adding a separate Sphinx project and duplicating a configuration file per document. I object to splitting the documents too much into small bits and pieces, for the reasons I explained in my earlier email [1]. If someone wants to have separate projects with dedicated configuration for special needs, they can add them. But I maintain that most documents do not have that need, and everything is simpler without. [1] http://mid.gmane.org/87wpm15q7q.fsf@xxxxxxxxx > Read chapter "Getting started with reST" from [1]. > [1] https://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO How about: 1) Write a file in rst, save it somewhere under Documentation. 2) Reference the file in Documentation/index.rst. 3) Be happy. I'll hand it to you that you have more experience in Sphinx than I do, but I like to think I know my fellow kernel developers better. The above is what they want to hear. They don't want a single hurdle more. 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
