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

[Markus Heiser]

Am 29.06.2016 um 22:57 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>:

> Em Wed, 29 Jun 2016 11:52:09 -0600
> Jonathan Corbet <corbet@xxxxxxx> escreveu:
> 
>>> 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.
> 
> Yeah, going to each maintainer is the best way, as we're the ones
> that will be bothered if something goes wrong on the documentation
> (and code) that we maintain.

Later if I have more time, may I will pick up those books who need
only small correction e.g. "debugobjects" .. but when the time comes
I will contact the maintainer and Jon' first.

> In the specific case of media stuff, the first step is to get the
> flat-tree support and to put the migrated documentation on a separate
> directory. Unfortunately, I have two sets of topic branches for 4.8,
> and they both touch at the media docbook (and nothing prevents that
> similar things to happen on 4.9 or any other version).
> 
> So, my plan is to keep both reST and docbook on Kernel for a while,
> until be sure that everything is properly migrated.
> 
> Yet, I'm not sure if we should keep the migration scripts at the
> Kernel tree, or if the best is to keep them in separate, as I
> intend to not take more than one Kernel version to finish the
> conversion. At least for media docbook, this will be a one-time
> conversion.

If I understood you right: the scripts, which are made the
migration itself should not committed to the kernel tree (IMHO).
Currently the scripts are available at my POC, may I could
separate them into a python package which could be installed
via python's pip. So if one wants to use this procedure of
migration, he could install the package locally, make the
conversion and after finishing, he uninstall the package. 

> So, I really appreciate if you could send me the patches with
> the converted media documentation that you did. I'll merge it
> after Jonathan applies the flat-tree patch on his tree, and
> start reviewing and fixing the documentation over the main
> branch.

Yes, first flat-table to Jon', then the converted media book
to Mauro, after this the man-page builder to Jon ... as long
as there are no man-pages in media it should be smoothly.

But I need a bit time, hopefully, end next week you got the
media patch from me.

-- Markus --

> I'll need to track the topic branch changes at the
> Docbook, to apply them again at the master tree, once they
> gets merged during the 4.8 window. Thankfully, there aren't
> complex elements on such changes (as far as I remember).
> 
> If everything goes right, by -rc2 or -rc3 I'll likely be dropping
> the DocBook/media from my tree.
> 
> --  
> Thanks,
> Mauro