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

[Jonathan Corbet]

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 :)

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.

> 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