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

[Mauro Carvalho Chehab]

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.

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.

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. 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