Define general guidelines for formatting in ViewHelper comments

[sypets]

Goal: Make it as easy as possible for contributors.

This should probably be defined separately for

• the TYPO3 core
• for Fluid

And I guess it would be best to put it in the Contribution Guide for the core and CONTRIBUTING guidelines in fluid (for standalone version).

Before people use various kinds of markup or despair at the difficulties of which markup to use, it might be a good idea to give general guidelines for markup.

Additionally, it might be helpful to use only a small subset of markup, maybe even one that is very similar for reStructuredText and Markdown.

See "Common markup for Markdown and reStructuredText"

Related: PR #2

[sypets]

Formatting should be defined in TYPO3 core.

[alexander-nitsche]

You have to know your rendering toolchain if you want to know which markup language you can use in the comments. Safest bet is to use no markup.

If in TYPO3 Core context or if rendered for docs.typo3.org with the official toolchain, you can use the reST markup that is supported by the toolchain (see h2document).

If rendered with a different toolchain for a different domain it might support a different markup language. For example the VHS extension documentation, published at https://viewhelpers.fluidtypo3.org/fluidtypo3/vhs/, supports Markdown.

In the end it might be safe to add a page in the h2document area that defines explicitly that the Fluid ViewHelper documentation should be written in reST if published at docs.typo3.org and list some example source and rendered files.

[linawolf]

This is a topic for the Core or the Fluid standalone package, not something we can solve here.