lkml.org 
[lkml]   [2016]   [Jun]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next
From
Date
Hi Jonathan,

Am 29.06.2016 um 19:52 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Wed, 29 Jun 2016 19:35:46 +0200
> Markus Heiser <markus.heiser@darmarit.de> 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

\
 
 \ /
  Last update: 2016-06-30 11:21    [W:0.065 / U:0.016 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site