Merge pull request #1264 from gracjan/pr-indent-region-noop

Document indent-region as a no-op

Author: gracjan

doc/haskell-mode.texi

@@ -511,6 +511,26 @@ selection mode (without redefining @kbd{C-x},@kbd{C-c},@kbd{C-v}, and
 @kbd{C-z}) by calling @kbd{M-x cua-selection-mode} (or adding
 @code{(cua-selection-mode nil)} to your @code{haskell-mode-hook}).
 
+@section Region indent is a no-op
+
+There is a @code{indent-region} function that supposedly could be used
+to indent code region without changing its semantics. Sadly it does not
+work that way because usual use case for @code{indent-region} is:
+
+@enumerate
+@item
+Alter first line of code in region.
+@item
+Call @code{indent-region} to fix indentation for remaining lines.
+@end enumerate
+
+Note that between 1 and 2 program is already semantically broken and
+knowing how to indent it preserving semantic from before step 1 would
+require time travel.
+
+To stay on the safe side @code{indent-region-function} is bound to a
+no-op in @code{haskell-mode}.
+
 @node External indentation
 @chapter Other ways to indent code