Improve docstring.

2 files changed, 33 insertions, 11 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5540f889a3..37f6d024fb 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2008-08-06  Vinicius Jose Latorre  <[email protected]>
+
+	* whitespace.el (whitespace-newline-mode)
+	(global-whitespace-newline-mode, whitespace-mode)
+	(global-whitespace-mode): Improve docstring.
+
 2008-08-05  Chong Yidong  <[email protected]>
 
 	* kmacro.el (kmacro-exec-ring-item): Add autoload.
diff --git a/lisp/whitespace.el b/lisp/whitespace.el
index 72501dfaf8..41f0af600d 100644
--- a/lisp/whitespace.el
+++ b/lisp/whitespace.el
@@ -161,10 +161,10 @@
 ;; There are also the following useful commands:
 ;;
 ;; `whitespace-newline-mode'
-;;    Toggle newline minor mode visualization ("nl" on modeline).
+;;    Toggle NEWLINE minor mode visualization ("nl" on modeline).
 ;;
 ;; `global-whitespace-newline-mode'
-;;    Toggle newline global minor mode visualization ("NL" on modeline).
+;;    Toggle NEWLINE global minor mode visualization ("NL" on modeline).
 ;;
 ;; `whitespace-report'
 ;;    Report some blank problems in buffer.
@@ -341,7 +341,7 @@
 ;; "long" lines.  See EightyColumnRule (EmacsWiki).
 ;;
 ;; Thanks to Yanghui Bian <[email protected]> for indicating a new
-;; newline character mapping.
+;; NEWLINE character mapping.
 ;;
 ;; Thanks to Pete Forman <[email protected]> for indicating
 ;; whitespace-mode.el on XEmacs.
@@ -1012,7 +1012,10 @@ Any other value is treated as nil."
 If ARG is null, toggle whitespace visualization.
 If ARG is a number greater than zero, turn on visualization;
 otherwise, turn off visualization.
-Only useful with a windowing system."
+Only useful with a windowing system.
+
+See also `whitespace-style', `whitespace-newline' and
+`whitespace-display-mappings'."
   :lighter    " ws"
   :init-value nil
   :global     nil
@@ -1029,14 +1032,19 @@ Only useful with a windowing system."
 
 ;;;###autoload
 (define-minor-mode whitespace-newline-mode
-  "Toggle newline minor mode visualization (\"nl\" on modeline).
+  "Toggle NEWLINE minor mode visualization (\"nl\" on modeline).
 
-If ARG is null, toggle newline visualization.
+If ARG is null, toggle NEWLINE visualization.
 If ARG is a number greater than zero, turn on visualization;
 otherwise, turn off visualization.
 Only useful with a windowing system.
 
-See also `whitespace-newline'."
+Use `whitespace-newline-mode' only for NEWLINE visualization
+exclusively.  For other visualizations, including NEWLINE
+visualization together with (HARD) SPACEs and/or TABs, please,
+use `whitespace-mode'.
+
+See also `whitespace-newline' and `whitespace-display-mappings'."
   :lighter    " nl"
   :init-value nil
   :global     nil
@@ -1058,7 +1066,10 @@ See also `whitespace-newline'."
 If ARG is null, toggle whitespace visualization.
 If ARG is a number greater than zero, turn on visualization;
 otherwise, turn off visualization.
-Only useful with a windowing system."
+Only useful with a windowing system.
+
+See also `whitespace-style', `whitespace-newline' and
+`whitespace-display-mappings'."
   :lighter    " WS"
   :init-value nil
   :global     t
@@ -1107,14 +1118,19 @@ Only useful with a windowing system."
 
 ;;;###autoload
 (define-minor-mode global-whitespace-newline-mode
-  "Toggle newline global minor mode visualization (\"NL\" on modeline).
+  "Toggle NEWLINE global minor mode visualization (\"NL\" on modeline).
 
-If ARG is null, toggle newline visualization.
+If ARG is null, toggle NEWLINE visualization.
 If ARG is a number greater than zero, turn on visualization;
 otherwise, turn off visualization.
 Only useful with a windowing system.
 
-See also `whitespace-newline'."
+Use `global-whitespace-newline-mode' only for NEWLINE
+visualization exclusively.  For other visualizations, including
+NEWLINE visualization together with (HARD) SPACEs and/or TABs,
+please, use `global-whitespace-mode'.
+
+See also `whitespace-newline' and `whitespace-display-mappings'."
   :lighter    " NL"
   :init-value nil
   :global     t