On Tue, Apr 16 2019 at 10:00am -0400, Jonathan Corbet <corbet@xxxxxxx> wrote: > On Tue, 16 Apr 2019 09:28:52 -0400 > Mike Snitzer <snitzer@xxxxxxxxxx> wrote: > > > Can you help me understand why this is the direction text based > > Documenation is taking in the Linux kernel? All I see is markup, and > > escaping of characters, that is a chore to administer over time. > > This is a discussion that was mostly resolved some years ago... > > Classic Documentation/ is a jumbled collection of unorganized text files, > some of which contain highly useful information and others of which > haven't had much to offer since about 1996. We are working to turn it > into an organized collection where, hopefully, some thought has actually > been given to the people who will be reading it. > > The ReST conversion, in particular, allows us to link documents into a > larger structure, create indexes and cross references, and produce output > in formats like HTML and PDF. It lets us present the documentation like > this: > > https://www.kernel.org/doc/html/latest/ > > Among other things, making the documentation more accessible in this way > makes it easier and more rewarding for developers to improve it, and I > believe we are seeing the results of that. Linus called out the > documentation work in the 5.1-rc1 announcement, for example. > > Nobody has complained about the maintenance burden of RST docs - so far as > I have heard, anyway. Things do break occasionally, but problems in the > docs build almost always result from code changes that mess up the > kerneldoc comments rather than RST changes, and it's been that way for as > long as I've been paying attention. Thanks for the context. I clearly just haven't followed the evolution. Certainly looks like a solid improvement. Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents? (apologies if this is all spelled out nicely in Documentation/ somewhere, but please help this man learn to fish). Thanks, Mike
