TYPO3: Unify placeholder syntax

[alexander-nitsche]

Throughout the TYPO3 documentation there are some variants of declaring placeholders, which should be reduced to one. There are currently among other

• <placeholder>
• [placeholder]
• {placeholder}

A reason to not pick {placeholder} as default style is that curly braces have a meaning in reST directive :samp: (and maybe others?) and emphasize the part being wrapped by the braces.

The current proposal is to use <placeholder> as default placeholder style.

[mbrodala]

I'd vote for <placeholder> since it's standard in BNF.

Technically this could lead to misleading code when used in HTML snippets but these are IMO rather rare compared to the majority of PHP/SQL/YAML examples. Here [placeholder] would actually be misleading in PHP snippets and could be interpreted as array.

[alexander-nitsche]

Maybe we should already define an alternative placeholder style for XML / HTML ?

[mbrodala]

I think in this case a <!-- placeholder --> will be enough.

[sypets]

What do you mean by placeholder? I assume in the general sense something you use a generic placeholder to represent something specific (as in linux commands).

I don't understand why some of the changes were linked to this issue and have the commit "[TASK] Unify placeholder syntax" because they have nothing to do with placeholders and just replace HTTP URLs with HTTPS, add the :samp: textrole etc. but all have the commit message "[TASK] Unify placeholder syntax". In that case I would create separate commits and call the PR "Cleanup formatting" or something ... or create individual PR.

(It just makes it a little difficult and confusing to follow along, e.g. the first one I saw was this: https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-ContributionWorkflow/pull/226/files

[alexander-nitsche]

You are right, Sybille, the task has been shrinked and extended at the same time from

• reformat the placeholders in the TYPO3 documentation

to

1. reformat the placeholders in the URLs of the TYPO3 documentation
2. add :samp: where applicable
3. replace http with the https variant where applicable

The additional tasks slipped in during the scan of the URLs when i became aware that there are still many places, where URLs were encapsulated in backticks without :samp: and where URLs where outdated / linking to the http variant. So as i was scanning the URLs anyway i extended this task. I added (2) to the commit message, but not (3).

[alexander-nitsche]

and also

4. replace dummy domains by example.(org|com|net).

So i applied all TYPO3 documentation rules that we introduced lately related to URLs whenever i became aware of places which broke the rules.

[sypets]

The changes are of course cool, thanks.

The nitpicking of the commits - I am a bit sloppy myself but came to appreciate it more and more if it is clear and one change per commit - especially when browsing and searching for stuff later.

[alexander-nitsche]

The nitpicking of the commits - I am a bit sloppy myself but came to appreciate it more and more if it is clear and one change per commit - especially when browsing and searching for stuff later.

I agree in general. But i will not rename or split all commits in this run again. In case someone wants to do it, please do so.

[sypets]

@alexander-nitsche No, ok to leave it and don't want to stall work. Thanks.

[alexander-nitsche]

Done.