Em Tue, 16 Apr 2019 08:00:24 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > 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/ Just to mention, in the specific case of the device-mapper patch, this is the result of those changes (after renaming the files to .rst, and adding an index file): https://www.infradead.org/~mchehab/rst_conversion/device-mapper/index.html > > 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, > > jon Thanks, Mauro
