Task #90806
Updated by Sybille Peters about 4 years ago
Currently, there are no automatic checks to check for formatting errors in changelog.
* There are some checks though that check if the changelog complies to changelog conventions: Build/Scripts/validateRstFiles.php
* when building the docs, a Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt is created, but this does not include some formatting errors which go undetected. However, it will report some problems.
* there may be other 3rdparty tools available I am not aware of.
Possibly an additional script could be added to check the changelogs for formatting problems.
Apparently, the best practice is using PHP scripts, see Build/Scripts/validateRstFiles.php or ask on Slack.
h2. Problems with lists
Common problem is missing newline before the list. This will not get rendered correctly, see https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Lists.html
You can easily find these with the following command:
<pre><code class="text">
cd typo3/sysext/core/Documentation
grep -r -B 1 -E "^(\*|\-) " . | grep "rst-" | grep -v -E "rst-(\*|$| )"
grep -r -A 1 -E "^(\*|\-) " . | grep "rst-" | grep -v -E "rst-(\*|$| )"
</code></pre>
h2. More ...
see https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Index.html
h2. Indenting
An additional problem (that manifests itself since the new theme) is a problem with unnecessary indenting. This is currently not mentioned (yet) in the "Common Pitfalls" chapter.
If you indent where it is not necessary, the block will be rendered as a quote (which is not what you want in most cases unless you really are using a quote), see https://typo3.slack.com/archives/C028JEPJL/p1586958179204000