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

[Aske Ertmann]

Thanks for the tips, very useful :)

> On 22 Jan 2015, at 14:20, François Suter <fsu-lists at cobweb.ch> wrote:
> 
> 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/
> _______________________________________________
> Before posting to this list, please have a look to the posting rules
> on the following websites:
> 
> http://typo3.org/teams/core/core-mailinglist-rules/
> http://typo3.org/development/bug-fixing/diff-and-patch/
> _______________________________________________
> TYPO3-team-core mailing list
> TYPO3-team-core at lists.typo3.org
> http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-team-core