Some doc for cycle-spacing

* lisp/simple.el (just-one-space, cycle-spacing): Doc fixes.

* doc/emacs/killing.texi (Deletion): Mention cycle-spacing.

* doc/lispref/text.texi: Comment.

* etc/NEWS: Related edits.

doc/emacs/ChangeLog

@@ -1,3 +1,7 @@
+2014-01-29  Glenn Morris  <rgm@gnu.org>
+
+	* killing.texi (Deletion): Mention cycle-spacing.
+
 2014-01-28  Glenn Morris  <rgm@gnu.org>
 
 	* text.texi (Fill Commands): Mention fill-single-char-nobreak-p.

doc/emacs/killing.texi

@@ -109,12 +109,11 @@ number of characters.  If the numeric argument is omitted or one, they
 delete all the text in the region if it is active (@pxref{Using
 Region}).
 
-@c FIXME: `cycle-spacing' should be documented, too.  (Maybe not in
-@c this node, tho.)  --xfq
 @kindex M-\
 @findex delete-horizontal-space
 @kindex M-SPC
 @findex just-one-space
+@findex cycle-spacing
   The other delete commands are those that delete only whitespace
 characters: spaces, tabs and newlines.  @kbd{M-\}
 (@code{delete-horizontal-space}) deletes all the spaces and tab
@@ -125,7 +124,11 @@ point, regardless of the number of spaces that existed previously
 (even if there were none before).  With a numeric argument @var{n}, it
 leaves @var{n} spaces before point if @var{n} is positive; if @var{n}
 is negative, it deletes newlines in addition to spaces and tabs,
-leaving @var{-n} spaces before point.
+leaving @var{-n} spaces before point.  The command @code{cycle-spacing}
+acts like a more flexible version of @code{just-one-space}.  It
+does different things if you call it repeatedly in succession.
+The first call acts like @code{just-one-space}, the next removes
+all whitespace, and a third call restores the original whitespace.
 
   @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines
 after the current line.  If the current line is blank, it deletes all

doc/lispref/text.texi

@@ -771,6 +771,9 @@ space, or @var{n} spaces if @var{n} is specified.  It returns
 @code{nil}.
 @end deffn
 
+@c There is also cycle-spacing, but I cannot see it being useful in
+@c Lisp programs, so it is not mentioned here.
+
 @deffn Command delete-blank-lines
 This function deletes blank lines surrounding point.  If point is on a
 blank line with one or more blank lines before or after it, then all but

etc/NEWS

@@ -273,16 +273,14 @@ normal editing behavior.
 the last step.  Its default value is changed to nil, which means a tab
 stop every `tab-width' columns.
 
-** Filling changes
-
-*** New command `cycle-spacing' cycles between spacing conventions:
-having just one space, no spaces, or reverting to the original
-spacing.  Like `just-one-space', it can handle or ignore newlines and
-leave different number of spaces.
++++
+** New command `cycle-spacing' acts like a smarter `just-one-space'.
+When called in succession, it cycles between spacing conventions:
+one space, no spaces, original spacing.
 
 +++
-*** `fill-single-char-nobreak-p' prevents fill from breaking a line after
-a one-letter word, which is an error according to some typographical
+** The new function `fill-single-char-nobreak-p' can stop fill from breaking
+a line after a one-letter word, which is an error in some typographical
 conventions.  To use it, add it to the `fill-nobreak-predicate' hook.
 
 +++

lisp/ChangeLog

@@ -1,3 +1,7 @@
+2014-01-29  Glenn Morris  <rgm@gnu.org>
+
+	* simple.el (just-one-space, cycle-spacing): Doc fixes.
+
 2014-01-28  Martin Rudalics  <rudalics@gmx.at>
 
 	* window.el (fit-frame-to-buffer): Fix calculations for margins and

lisp/simple.el

@@ -794,7 +794,8 @@ If BACKWARD-ONLY is non-nil, only delete them before point."
 
 (defun just-one-space (&optional n)
   "Delete all spaces and tabs around point, leaving one space (or N spaces).
-If N is negative, delete newlines as well, leaving -N spaces."
+If N is negative, delete newlines as well, leaving -N spaces.
+See also `cycle-spacing'."
   (interactive "*p")
   (cycle-spacing n nil t))
 
@@ -805,31 +806,22 @@ position and original spacing around the point in this
 variable.")
 
 (defun cycle-spacing (&optional n preserve-nl-back single-shot)
-  "Manipulate spaces around the point in a smart way.
+  "Manipulate whitespace around point in a smart way.
+In interactive use, this function behaves differently in successive
+consecutive calls.
 
-When run as an interactive command, the first time it's called
-in a sequence, deletes all spaces and tabs around point leaving
-one (or N spaces).  If this does not change content of the
-buffer, skips to the second step:
+The first call in a sequence acts like `just-one-space'.
+It deletes all spaces and tabs around point, leaving one space
+\(or N spaces).  N is the prefix argument.  If N is negative,
+it deletes newlines as well, leaving -N spaces.
+\(If PRESERVE-NL-BACK is non-nil, it does not delete newlines before point.)
 
-When run for the second time in a sequence, deletes all the
-spaces it has previously inserted.
+The second call in a sequence (or the first call if the above does
+not result in any changes) deletes all spaces.
 
-When run for the third time, returns the whitespace and point in
-a state encountered when it had been run for the first time.
+The third call in a sequence restores the original whitespace (and point).
 
-For example, if buffer contains \"foo ^ bar\" with \"^\" denoting the
-point, calling `cycle-spacing' command will replace two spaces with
-a single space, calling it again immediately after, will remove all
-spaces, and calling it for the third time will bring two spaces back
-together.
-
-If N is negative, delete newlines as well.  However, if
-PRESERVE-NL-BACK is t new line characters prior to the point
-won't be removed.
-
-If SINGLE-SHOT is non-nil, will only perform the first step.  In
-other words, it will work just like `just-one-space' command."
+If SINGLE-SHOT is non-nil, it only performs the first step in the sequence."
   (interactive "*p")
   (let ((orig-pos	 (point))
 	(skip-characters (if (and n (< n 0)) " \t\n\r" " \t"))