Em Mon, 28 Nov 2016 11:20:09 +0100 Peter Zijlstra <peterz@xxxxxxxxxxxxx> escreveu: > On Mon, Nov 28, 2016 at 09:44:42AM +0100, Daniel Vetter wrote: > > > > > > > Why change them? What was wrong with txt to begin with? > > > > In my opinion good docs matter, and one of the key things is to be able to > > cross reference stuff. > > Well, good docs begin with useful content; and many docs lack that. > Fixing that would be a much more useful thing to do. > > In any case, I've never had any problems with typing things like: "go > read: Documentation/file.txt for more information.". > > Also, what text editor supports cross references at all then? With the > filename I can use 'gf' in vim to open it up in a new buffer and go read > that. > > > Another concern some core kernel folks raised is that the .rst markup was > > too heavy-handed, and makes the text much harder to read. Christoph called > > it "cat spew". That can be fixed with a much lighter-handed conversion > > (and 2nd patch iteration was acceptable for Christoph). > > Very much agreed, once a file is no longer readable with less or the > text editor of your choice, it as good doesn't exist at all. So I very > much worry about RST even supporting such heavy markup that the end > result is unreadable. > > Basically, if a file isn't usable from within a 'normal' text editor, it > doesn't exist. A file "converted" to ReST is still a text file. As Jani mentioned, you can keep doing your normal edit on them as text files, without even noticing that it follows the ReST notation. On most cases, all it takes to convert a file to ReST is: - adjust the chapter/section headers, as they all start on column 1, and all have a line below with a symbol (like "=", "-", "~", ...), E. g: Foo chapter =========== bar section ----------- It will automatically assign the first symbol to chapter, the next one to section and so on. - use *foo* (for italics) or **foo** (for bold) instead of _foo_; - if you need to use cross-references, use :ref:`name <id>`; The way I did cross-references on the documents I converted was to preserve the file name, plus adding a way for the ones reading the documentation in PDF or HTML to have the document cross-referenced. This way, we can still open the cross-referenced document with our favorite text editors, as the file name is there. E. g: :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` - if it contains source examples or ascii artwork diagrams, use "::" on the previous line to create a literal block, e. g.: this is an example:: // whatever I do here, Sphinx will display as-is foo(bar); - adjust whitespaces/new lines where needed, as Sphinx identifies continuation lines if the text is at the same column as the previous line, and blank lines break paragraphs. - if you have something that you want to use a monotonic font on PDF/LaTeX/HTML, use ``foo``. - if you use special characters like '*' in the middle of the text (outsize a literal block), prepend with a \ in order to escape parsing it. Silvio's patch was a little too intrusive, as it touched on block indentation and whitespaces without needing. It also used monotonic fonts for a lot more than it would be required. I'm pretty sure his patch could be reworked to be a lot less intrusive. Btw, a lot of editors recognize ReST files and are capable of parsing the ReST tags while displaying the file, including vim and emacs, using different colors and/or bold to display those tags. So, even for text-editing, converting to ReST brings improvements. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
