Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues

["Rafael J. Wysocki" <rjw@rjwysocki.net>]

On Saturday, June 24, 2017 01:09:28 AM Rafael J. Wysocki wrote:
> On Friday, June 23, 2017 12:39:36 PM Jonathan Corbet wrote:
> > The docs pull for 4.13 will include the conversion of the last DocBook
> > template files, thanks mostly to Mauro.  That's the good news; the bad
> > news is that I get to explain a lot of merge conflicts to Linus, most of
> > which result from other trees reaching into Documentation/ and changing
> > files that have been converted.
> > 
> > I can continue in this mode, but I do wonder if there's a better way out
> > there somewhere.  So I think there would be value in a session on the
> > maintenance of "subsystems" that don't fit neatly into the kernel
> > source-tree hierarchy.
> > 
> > We could also talk about the state of the RST conversion and whether/how
> > we'd like it to continue.  Perhaps we would rather, as Peter recently
> > suggested, "just delete all that nonsense and go back to 80 column 7bit
> > ASCII"?  In general, what do the maintainers want from the documentation
> > subsystem, and how can we make it easy to continue improving our docs?
> 
> For one, I'm going to continue converting PM documentation to RST and I would
> not welcome deleting the existing .txt one until that is complete.
> 
> Same goes for ACPI, pretty much.
> 
> Also I don't expect too many documentation-related merge conflicts in the PM
> case going forward.

I should probably add that I find RST much more appealing than "80 column 7bit
ASCII" at least because of how it allows cross-references to be expressed if
nothing else.

Thanks,
Rafael