Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup

[Mauro Carvalho Chehab]

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