all: clarify that the "keep padding" formatting option is deprecated

Back in 2022 in #658 I already decided this option will be removed in v4
yet the documentation did not make this clear, so users could be
misled into thinking it's a good idea to use it today.

For #658.

cmd/shfmt/shfmt.1.scd

@@ -93,6 +93,9 @@ predictable. Some aspects of the format can be configured via printer flags.
 *-kp*, *--keep-padding*
 	Keep column alignment paddings.
 
+	This flag is *DEPRECATED* and will be removed in the next major version.
+	For more information, see: https://github.com/mvdan/sh/issues/658
+
 *-fn*, *--func-next-line*
 	Function opening braces are placed on a separate line.
 

syntax/printer.go

@@ -55,6 +55,11 @@ func SpaceRedirects(enabled bool) PrinterOption {
 // Note that this feature is best-effort and will only keep the
 // alignment stable, so it may need some human help the first time it is
 // run.
+//
+// Deprecated: this formatting option is flawed and buggy, and often does
+// not result in what the user wants when the code gets complex enough.
+// The next major version, v4, will remove this feature entirely.
+// See: https://github.com/mvdan/sh/issues/658
 func KeepPadding(enabled bool) PrinterOption {
 	return func(p *Printer) {
 		if enabled && !p.keepPadding {