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

[Markus Klein]

Hi!

Thanks for caring about the documentation!

Do we already have an official place where the Core docs for 7.0 and master are rendered?

Kind regards
Markus

------------------------------------------------------------
Markus Klein
TYPO3 CMS Active Contributors Team Member

> -----Original Message-----
> From: typo3-team-core-bounces at lists.typo3.org [mailto:typo3-team-core-
> bounces at lists.typo3.org] On Behalf Of François Suter
> Sent: Thursday, January 22, 2015 2:21 PM
> To: typo3-team-core at lists.typo3.org
> Subject: [TYPO3-core] Common reStructuredText mistakes in "core"
> Changelog
> 
> 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