Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next

[Markus Heiser]

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