Hi Jonathan, Am 29.06.2016 um 19:52 schrieb Jonathan Corbet <corbet@xxxxxxx>: > On Wed, 29 Jun 2016 19:35:46 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > >>> I would love it if you would take the flat-table and man-page work, >>> separate them out, and make them work with the *existing* Sphinx-based >>> scheme. If you can do it soon, we can maybe get it into 4.8. Can you >>> focus on that for now, please? >> >> Yes, I will send you flat-table request in the next days. > > I'm glad to hear that. One request: please post it as a patch, rather than > as a pull request; that makes it easier for everybody to review it. > >>> As for the rest, what we have now is certainly far from perfect; we're >>> figuring a lot of this out as we go. Incremental improvements are >>> welcome, and each will be evaluated independently. Please help us to >>> make the kernel's documentation better that way. >> >> I'am willing to do so, but I need some help / suggestions: >> >> 1. I have this extensions in the scripts/site-python/linuxdoc. >> What do you recommend, how could I split this up in a patch >> series which is more evaluated. >> >> .. I wrote to Jani, that my approach was chaotic in the past >> and I'am sorry for this. But now I'am sitting in front of this >> bulk of source and I'am bit helpless how to split ... I will >> try to make it more elaborate, but it will be helpfull if >> you point me the right direction ... > > Try to break it down as much as possible so that each patch represents a > single logical change. Each bit that you can break out reduces the problem > space a bit, and often helps with the rest. If possible, I'd like to > suggest starting with the man-page generation, since that's a hole in the > current system. I'll have to fill it if you don't :) Give me a bit time, I will do it. At first flat-table, then man-page. > Please note that I'd really like to see this stuff done without big changes > like the wholesale replacement of kernel-doc with a version in a different > language. Someday we might want to make a change like that, but one step > at a time. mmh, OK ... it will be "the long run" for me ... I will take it (again). The replacement makes many things much easier and has this big features; to parse only once (not on every kernel-doc directive / one error log, not n times same error messages) and a rich interface to control the reST output fine grained ( and Snippets, and a NullTranslator as a lint for free and .. and) ... it is a good working base ... no need for breadcrumbs or other tricky workarounds ... OK, I will start improving the perl script insofar it is needed (the reST out has to be more structural, you will see it / if it comes to the man-page builder) ... may be later I could persuade you, that it is a "dead end street" ... if the language python is the problem, I could maintain these modules (15 years practice). Regards --Markus-- >> 2. What is the best way to ship these migrations >> >> or better I asked, what is your recommendation for a >> migration strategy. Jani says, that this better belongs >> to authors, but I have a doubt that we end with the >> migration in the next years, if we wait about every author. >> I think, supporting both infrastructures - the xml and the >> reST - over a long period is not the best option. What is >> your recommendation on this? > > I think we need to give maintainers the first shot at doing the conversion; > in any case, I don't think we can just force it through without their > cooperation. And, honestly, while we're still groping around in this > space, I think it's fine if we don't have lots of conversions right away. > The ones that go more slowly will benefit from what we learn with the easy > ones. > > You could certainly talk to maintainers and see if they would like > assistance with specific books. Helping Mauro to get his tables done > without going totally nuts would be a great first step, IMO. > > That said, if you're wanting to convert documents, there is a set of older > ones in the docbook directory that have no current maintainer and will > never move over on their own. kernel-hacking.tmpl is an obvious example. > The problem with these, of course, is that they are *way* out of date in > general, and really need attention beyond just a format conversion. I > won't say one has to happen before the other, but I am unsure that we will > really benefit from convert-and-forget-again efforts. > > Thanks, > > jon -- 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
