[TYPO3-core] Common reStructuredText mistakes in "core" Changelog

[François Suter]

Hi all,

Having toyed a bit with the documentation contained in the "core" 
sysext, I realized that it totalled 216 errors when its reST markup was 
rendered to HTML. I went ahead and checked all files, resulting in a 
cleanup that I just merged [1].

I wanted to give you some feedback here about the most common mistakes 
that I found, so that you can avoid them in the future:

-- there must be a blank line after a ".. code-block::" directive
-- don't use arbitrary text roles like ":php:" or ":javascript". This is 
not recognized. Simply use ":code:".
-- don't put white spaces before list markers, i.e. don't do:

  - a
  - b

but:

- a
- b

Lines starting with arbitrary white spaces will be rendered as block quotes.

-- _ccc_ not valid inline markup. Use :code:`ccc` for code or *ccc* for 
emphasis


And now some best practices used by the Documentation Team:

-- avoid using "::" for code blocks, better use the ".. code-block::" 
directive, because you can define the language for syntax highlighting. 
And BTW, there's no ".." after the code block.
-- don't wrap lines inside code blocks. Let the rendering manage it.
-- for lists, we use "-" instead of "*", although the latter works fine too.

And one piece of information: if you want to write a simple asterisk, 
you need to escape it: \*

Happy documenting!

-- 

Francois Suter

Work: Cobweb Development Sarl - http://www.cobweb.ch

TYPO3: Help the project! - http://typo3.org/contribute/

Appreciate my work? Support me -
http://www.monpetitcoin.com/en/francois/support-me/

[1] https://review.typo3.org/#/c/36174/