Closed brotkrueml closed 1 year ago
Sometimes it is not clear where the directive ends and a "normal" paragraph starts:
I agree. I think it is a good idea to generally have it in some kind of a box visually separated, whether that is a frame or with a border on the left side, I don't care much as long as it is obvious.
To deal with that issue: Can you come up with a list of links to usecase which you would consider 'sub-optimal'? Then we can check whether this is best be solved by writing the RST source differently or by tweaking the theme.
This one for example: https://docs.typo3.org/m/typo3/reference-coreapi/12.4/en-us/Configuration/ConfigurationFiles.html?highlight=localconfiguration#migration
It is not clear where the "changed" ends.
Also for this PR with a mix of different hints: https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/3157/files It is hard to grasp where they real text starts and what are just annotations.
Another example: Where ends the new note and starts the real text? https://docs.typo3.org/m/typo3/reference-coreapi/12.4/en-us/ApiOverview/Events/Events/Frontend/AfterCacheableContentIsGeneratedEvent.html
And even better: the new note spans three paragraphs: https://docs.typo3.org/m/typo3/reference-coreapi/12.4/en-us/ApiOverview/Events/Events/Frontend/AfterLinkIsGeneratedEvent.html
Looks like this is easy to do. What about this:
In an extreme demo case this looks like:
Not bad, I'd say.
Fine for me, it has now a clear separation to the surrounding text.
@linawolf What do you think?
We use the directives "versionadded", "versionchanged" and "deprecated" quite often in the docs - often also with mulitple paragraphos or in combination with a list. Sometimes it is not clear where the directive ends and a "normal" paragraph starts:
One solution might be to add a left border to clamp them:
Another solution might be to set a background colour:
Personally, I like the left border more because the background color is used by admonitions and sometimes admontition and those version directives follow in the text.
Also a single directive without additional text should be considered: