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, jon -- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
