indent and tab settings, recommendations, comments, style

[bugsbugsbux]

Please do not set user preferences like shiftwidth at all.
There is a clear vim policy against doing that:
https://github.com/vim/vim/blob/master/runtime/ftplugin/README.txt

Please do not enable recommendations by default;
this also follows from the policy to not set user preferences.
Maybe send a notification how to enable them (let g:markdown_recommended_style=1)
and how to disable the notification (could be setting g:markdown_recommended_style to anything)

Please add comments to every setting you make, to explain why.

Why do you set softtabstop? It leads to mixed indents which I believe are undesirable.
However, it should not even have any effect here because you also set expandtab.
Why do you set both?

Why do you place indent settings in ftplugin/ and not indent/ ?

Please use long option-names for clarity.

[tpope]

Please do not set user preferences like shiftwidth at all. There is a clear vim policy against doing that: https://github.com/vim/vim/blob/master/runtime/ftplugin/README.txt

This doc is 22 years old and does not reflect the reality of the situation. (Edit: That's actually the commit date for the version in Git. It's older than that.) By my count 38 filetype plugins set shiftwidth.

A common practice that has emerged is when a language has a clear front runner, the ftplugin can provide shiftwidth, with a recommended_style option to turn it off.

Please do not enable recommendations by default; this also follows from the policy to not set user preferences. Maybe send a notification how to enable them (let g:markdown_recommended_style=1) and how to disable the notification (could be setting g:markdown_recommended_style to anything)

I don't know what you mean by notification.

Why do you set softtabstop? It leads to mixed indents which I believe are undesirable. However, it should not even have any effect here because you also set expandtab.

This option controls the behavior of the tab key. It has nothing to do with mixing indents. You can get mixed indents regardless of this setting.

Why do you set both?

Because it makes the tab key behave like users expect when smarttab is off (this used to be the default).

Why do you place indent settings in ftplugin/ and not indent/ ?

Because that's the convention. Indent plugins contain the logic of indenting (mostly indentexpr these days), not every setting related to indenting.

[bugsbugsbux]

I don't know what you mean by notification.

vim.notify with a level of vim.log.levels.INFO; i guess :echo in legacy vim.

sts does not matter for leading tabs i guess, but it absolutely matters for all other tabs, which now behave unpredictably because they might insert real tabs or spaces or a mixture or undo your spaces and replace them with a real tab. this is hardly what most people expect when hitting the tab key. if you want to indent/align something, you have to either use all spaces or all tabs, but never a mixture. therefore it should only be set by the user himself