Em Tue, 16 Apr 2019 11:48:59 -0400 Mike Snitzer <snitzer@xxxxxxxxxx> escreveu: > 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? I guess the main point is that, after writing a .rst file, run "make htmldocs" and see how it fits :-) As Jon mentioned, a large number of documents (even some written lots of years ago) already fits into ReST, and keeping it simpler makes easier for plain text file readers. We do have some documents (like the media book), were we use a lot of the markup stuff, as those documents came from DocBook and it is full of cross-references, complex tables, images, examples, etc, but for most subsystems, you're safe with the usual stuff. > > (apologies if this is all spelled out nicely in Documentation/ > somewhere, but please help this man learn to fish). A few tips if you want to write documents that are easy to read as text files and produce nice output after parsed: 1) it is written to document Python. So, it is indentation sensitive. Usually most of the fixes are just to properly indent things; 2) By default, it identifies line breaks with two \n. The exceptions are literal blocks like: :: foo bar and things like: foo bar (in this case, it will bold **foo**) Another trick that I use to avoid the need of adding an extra \n is to convert itemized lists into a table, with: === foo bar === 3) Things like "struct *foo" usually produces error, as a single * is interpreted as italic. The parser will look for another *. As it won't find, it will produce an error. So, this need to be escaped somehow. While you can escape such special characters like * and _ with an inverted bar, like "struct \*foo", that looks ugly for casual text file readers. Instead, I do either:: struct *foo or, if I want it in the middle of a text, I use `struct *foo`. IMO, placing it on a literal block (::) looks visually better for both text and html modes. Thanks, Mauro -- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
