[Emacs-diffs] trunk r116191: Some doc for cycle-spacing

[Glenn Morris]

------------------------------------------------------------
revno: 116191
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2014-01-29 00:27:55 -0800
message:
  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.
modified:
  doc/emacs/ChangeLog            changelog-20091113204419-o5vbwnq5f7feedwu-6227
  doc/emacs/killing.texi         
killing.texi-20091113204419-o5vbwnq5f7feedwu-6258
  doc/lispref/text.texi          text.texi-20091113204419-o5vbwnq5f7feedwu-6215
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/simple.el                 simple.el-20091113204419-o5vbwnq5f7feedwu-403

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2014-01-28 02:50:16 +0000
+++ b/doc/emacs/ChangeLog       2014-01-29 08:27:55 +0000
@@ -1,3 +1,7 @@
+2014-01-29  Glenn Morris  <address@hidden>
+
+       * killing.texi (Deletion): Mention cycle-spacing.
+
 2014-01-28  Glenn Morris  <address@hidden>
 
        * text.texi (Fill Commands): Mention fill-single-char-nobreak-p.

=== modified file 'doc/emacs/killing.texi'
--- a/doc/emacs/killing.texi    2014-01-26 01:10:18 +0000
+++ b/doc/emacs/killing.texi    2014-01-29 08:27:55 +0000
@@ -109,12 +109,11 @@
 delete all the text in the region if it is active (@pxref{Using
 Region}).
 
address@hidden FIXME: `cycle-spacing' should be documented, too.  (Maybe not in
address@hidden this node, tho.)  --xfq
 @kindex M-\
 @findex delete-horizontal-space
 @kindex M-SPC
 @findex just-one-space
address@hidden 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 @@
 (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

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2014-01-28 01:49:02 +0000
+++ b/doc/lispref/text.texi     2014-01-29 08:27:55 +0000
@@ -771,6 +771,9 @@
 @code{nil}.
 @end deffn
 
address@hidden There is also cycle-spacing, but I cannot see it being useful in
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-01-28 03:00:20 +0000
+++ b/etc/NEWS  2014-01-29 08:27:55 +0000
@@ -273,16 +273,14 @@
 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.
-
-+++
-*** `fill-single-char-nobreak-p' prevents fill from breaking a line after
-a one-letter word, which is an error according to some typographical
++++
+** 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.
+
++++
+** 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.
 
 +++

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-01-28 09:45:37 +0000
+++ b/lisp/ChangeLog    2014-01-29 08:27:55 +0000
@@ -1,3 +1,7 @@
+2014-01-29  Glenn Morris  <address@hidden>
+
+       * simple.el (just-one-space, cycle-spacing): Doc fixes.
+
 2014-01-28  Martin Rudalics  <address@hidden>
 
        * window.el (fit-frame-to-buffer): Fix calculations for margins and

=== modified file 'lisp/simple.el'
--- a/lisp/simple.el    2014-01-23 07:53:56 +0000
+++ b/lisp/simple.el    2014-01-29 08:27:55 +0000
@@ -794,7 +794,8 @@
 
 (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 @@
 variable.")
 
 (defun cycle-spacing (&optional n preserve-nl-back single-shot)
-  "Manipulate spaces around the point in a smart way.
-
-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:
-
-When run for the second time in a sequence, deletes all the
-spaces it has previously inserted.
-
-When run for the third time, returns the whitespace and point in
-a state encountered when it had been run for the first time.
-
-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."
+  "Manipulate whitespace around point in a smart way.
+In interactive use, this function behaves differently in successive
+consecutive calls.
+
+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.)
+
+The second call in a sequence (or the first call if the above does
+not result in any changes) deletes all spaces.
+
+The third call in a sequence restores the original whitespace (and point).
+
+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"))