Should indenting be changed to 4 spaces?

[sypets]

Indenting is currently defined to be 3 spaces: https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/CodingGuidelines.html#whitespace-and-indenting

See discussions in Slack.

There have been requests to switch to 4 spaces per indent level.

Reasons for using 3 spaces

Martin Bless

As you can see I have set my tab width and indentation to 3 spaces (and I do not use tabs). This may seem a bit odd to you at first - trust me, it felt weird to me at first, too. But here's why:

Most of rst's syntax is based around so-called directives and these are always .. DIRECTIVE. So as you can see the two dots and the space add up to 3 characters which is why I set these strange values.

It increases readability by a huge margin.

https://docs.typo3.org/typo3cms/drafts/github/wmdbsystems/RSTingWithPhpStormGuide/PHPStorm/CodingStyle.html

More on using 3 for code as well: https://docs.typo3.org/typo3cms/Teams/T3DocTeam/PersonalNotes/Marble/IndentCodeByThree.html

Advantages of switching to 4?

• That way, indenting is consistent with code indenting in TYPO3. Currently, it is recommended to indent everything with 3 spaces in reST. That means, if you copy / paste code snippets from / to PHP you have different indenting.
• If you edit on GitHub, you can only select 2,4 and 8 spaces for indenting (for new files). If you edit existing files, it seems to work though. Supposedly GitHub should use .editorconfig, but this somehow does not seem to work for .rst files.

Disadvantages

• .editorconfig in doc and core repos would have to be changed
• most projects use current correct indenting of 3. Must be converted.

current situation

• some manuals use mixture of 3 and 4 spaces and tabs to indent:
  • core changelog

Migration tasks (if switch to 4)

• change all .editorconfig in documentation projects, change .editorconfig in core
• convert documentation projects (in order to prevent mixture of 3 and 4 spaces in future)
• convert sysext Documentation + core Changelog

[sypets]

I also created an Issue for the Forger reST Helper: https://forger.typo3.com/utility/rst, because it creates text indented with tabs.

Issue name: "TE-116 Forger reST Helper should use 3 spaces, not tabs to indent".

If indenting space number is to be changed, we should do it soon because otherwise there will be even more places that have to be changed.

[sypets]

I would like to reject and close this for these reasons:

• no one has responded to this issue, voted or commented or given reasons that support the change
• the 3 space indenting has been in place for documentation for several years now
• the .editorconfig in the core uses 3 spaces for reST for 3 years now: see git blame .editorconfig
• converting 3 to 4 would be a huge task.

Everyone: Please use documented and enforced by .editorconfig indenting of 3 spaces per indenting level for reST files in official manuals and Chagelog: CGL for reST: whitespace & indenting