paredit.release

* Paredit Release Notes                                 -*- outline -*-

This file contains release notes for paredit, whose latest released
version is available at

  <http://mumble.net/~campbell/emacs/paredit.el>,

and whose latest beta version is available at

  <http://mumble.net/~campbell/emacs/paredit-beta.el>.

The latest version of this file is available at

  <http://mumble.net/~campbell/emacs/paredit.release>.

** Version 21 (RELEASE)

Paredit 21 no longer has a message releasing it into the public domain.
Instead it is copyright (C) 2008, Taylor R. Campbell, and available
under the terms of the 3-clause BSD licence.  See the paredit.el file
for details.

*** Style and Bugs

- Use of the terms `parenthesis', `bracket', and `delimiter' has been
  clarified throughout the file:

  . /Parentheses/ are nestable objects indicated by matching delimiter
    pairs.  For example, the text `(foo (bar baz) quux)' has two
    parentheses, `(foo ... quux)' and `(bar baz)'; each is delimited
    by matching round delimiters.

  . /Delimiters/ are the actual atomic objects that delimit
    parentheses.  They may be shaped differently; for example, `[' is
    an opening square delimiter, and `{' is an opening curly
    delimiter.

  . The terms `bracket', `brace', and `brocket' (the latter a
    misspelling of `broket', for `broken bracket') are eschewed.

  The names `paredit-open-parenthesis' &c. have been changed to
  `paredit-open-round' &c., and likewise with `bracket' -> `square',
  `brace' -> `curly', and `brocket' -> `angled'.  The old names with
  the morphemes `parenthesis' and `bracket' have been preserved so that
  users need not update initialization files immediately, but will
  instead be confused when a subsequent minor update breaks all their
  initialization files for no good reason.

- Some commands now check their context more strictly, so that they
  won't try to do anything in comments or strings.  Whether this is the
  right thing, I don't know.

- Several small elements of style were adjusted.  This should make no
  functional difference on the code.  (If it does, then I have made a
  mistake.)

- paredit.el no longer defines `kill-region-new'; the function is
  instead called `paredit-hack-kill-region', to reflect its hackish
  nature and to avoid name clashes.  I believe that the only name
  remaining defined by paredit.el without `paredit-' prefixed is
  `backward-down-list', whose definition is so obvious that it would be
  silly to define it any other way, so that any name conflict does not
  worry me.  (I suppose `kill-region-new' is obvious, too -- it is to
  `kill-region' as `kill-new' is to `kill'.  But the omission from a
  pattern isn't as clear as with `backward-down-list'.)

- `paredit-comment-dwim' should work in GNU Emacs 21 now, whose
  newcomment.el defines no `comment-or-uncomment-region'.  More and
  more ugly compatibility hacks are accruing in paredit.el as a
  consequence, to my dismay.  Oh well.

- The release notes are now formatted more legibly, paginated nicely,
  and organized with Outline Mode.  The gross discrepancy in writing
  style over the years has not changed.

- The introductory comments in the file are more clearly written now.

- Fixed a bug in S-expression slurpage with mixed delimiters.

*** Altered Behaviour

- The bindings for `)' and `M-)' have been exchanged: `)' is bound to
  `paredit-close-round' and `M-)' to `paredit-close-round-and-newline',
  so that you can now without any glaring exceptions type new code
  using the same keystrokes with and without Paredit Mode.  You can
  also now paste into Emacs through a terminal without leaving spurious
  blank lines in the buffer.  You are, of course, free to revert to the
  old behaviour in your .emacs file.

- `paredit-semicolon' is no more.  Now you may insert semicolons as
  you please without the infuriating escape of the following text on
  the line.

- `paredit-move-past-close-and-newline' will now leave comments on the
  same line only if they are margin comments and no S-expressions are
  intervening between the point and the comment; that is, only if it
  looks like the margin comment really pertains to the expression being
  closed will paredit leave it on the same line.

- `paredit-backward-delete', `paredit-forward-delete', and
  `paredit-kill' formerly accepted prefix arguments to run the basic
  `backward-delete-char', `delete-char', and `kill-line' commands
  instead, without regard for the value of the prefix argument.  Now
  `C-u' will run the basic commands, but

  . `paredit-kill' will pass a numeric argument on to `kill-line', and

  . `paredit-backward-delete' and `paredit-forward-delete' will both
    delete N characters if given a numeric prefix argument N.

  (`paredit-kill' should probably do the same, but repeating the
  command N times is probably not what you want -- what you probably
  want is to kill at most N *lines*, but `paredit-kill' N times might
  kill many more lines than that.  I don't know what the right thing is
  here, but I welcome feedback from users who want to do something like
  this.)

- With a `C-u' prefix argument, `paredit-wrap-sexp' now wraps all
  S-expressions following the point until the end of the buffer or a
  closing delimiter.

- `paredit-splice-sexp' with a `C-u' prefix argument (also known as
  `paredit-splice-sexp-killing-backward') will now kill from the point,
  rather than from the beginning of the next S-expression  (or, with
  `C-u C-u', from the end of the previous S-expression).  This means
  that it is more likely to do what you mean with

    (let ((a b) (c d))
      |;; I want to preserve this comment after `C-u M-s'.
      (foo bar baz))

- `paredit-splice-sexp' now splices strings, by removing backslash
  escapes, or signals an error if doing so would destroy the structure
  of the buffer.

- I have finally introduced the first bit of code to try to deal
  sensibly with broken buffers.  It will probably go only downhill from
  here, and continue in an interminable series of kludges to handle
  every possible way in which the buffer can go *wrong* (it's bad
  enough how many ways it can be *right*).  If you try type a closing
  delimiter from within a partial S-expression that has an opening
  delimiter but no closing delimiter, then it will honk at you and
  insert the closing delimiter -- or if what you typed doesn't match
  the opening delimiter, it will just honk and refuse to do anything.
  Also, `DEL' and `C-d' will delete spurious (but not [yet] mismatched)
  opening and closing delimiters, respectively.  (Thanks to John
  Wiegley for inspiring me to do these dreary deeds.)

*** New Commands

- New command `paredit-yank-pop' cooperates with `paredit-wrap-sexp' by
  behaving either like `yank' or like `yank-pop' if the previous
  command was `paredit-wrap-sexp' or `paredit-yank-pop', and with the
  added bonus of reindenting the newly wrapped form.  It is in need of
  a key to be bound to it; since it is different from both `yank' and
  `yank-pop', I decided not  to override `C-y' or `M-y', and I
  considered `C-c C-y', but I imagine that many major modes want to
  take that.

- New command `paredit-focus-on-defun' moves display to the top of the
  definition at the point.

- New command `paredit-reindent-defun', which `M-q' is bound to in
  Paredit Mode, indents the definition the point is on, or, if the
  point is in a string or comment, fills the paragraph instead.
  (Thanks to John Wiegley for the idea.)

- New variations on slurpage, barfage, and joinage.  I'm still looking
  for keys to bind to these commands.  Find them with the strings
  `add-to-{previous,next}-list' and `join-with-{previous,next}-list' in
  their names.  (Again, thanks to John Wiegley for the idea.)

- New command `paredit-convolute-sexp' performs the combined function
  of `paredit-splice-sexp-killing-backward', `paredit-wrap-sexp', and
  `yank'.  Example:

    (let ((foo bar))
      (let ((baz quux))
        |(zot mumble)
         (frotz))
      (gargle mumph))
  ->
    (let ((baz quux))
      (let ((foo bar))
        (zot mumble)
        (frotz)
        (gargle mumph)))

  This would otherwise have been done with the key sequence `C-u M-s
  C-M-u M-( C-y C-M-u C-M-q'.  `C-u M-s' could be `M-up', and `C-y
  C-M-u C-M-q' could be `C-c C-y' if that key is chosen for
  `paredit-yank-pop', making the sequence `M-up C-M-u M-( C-c C-y'.  If
  there is a good key for `paredit-convolute-sexp', it could be a nice
  improvement over even that terser sequence.  (Once again, this was
  inspired by John Wiegley's idea (and name).)

  [Observe, though, that the form (FROTZ) stuck with (ZOT MUMBLE) the
  whole time, and was not carried along as the `end' of the (LET ((BAZ
  QUUX)) ...) form.  Hence this is *not* the idea mentioned below by
  the name `paredit-interchange-sexps', but a simpler approximation of
  the idea.]

- `define-paredit-pair' now defines commands `paredit-wrap-...' for
  wrapping S-expressions with different delimiters, like
  `paredit-wrap-sexp'.  The function `paredit-wrap-sexp' now accepts
  optional arguments for the delimiters to insert; the new commands are
  defined in terms of the modified `paredit-wrap-sexp'.  `M-[' is now
  bound to `paredit-wrap-square'.

** Version 20

*** Preliminary Support For XEmacs

This version introduces preliminary support for XEmacs.  The changes
needed were:

- `check-parens' is called by the `paredit-mode' initialization only if
  it is fbound.

- The forward and backward deletion keys are specified differently in
  GNU Emacs and XEmacs.

- `paredit-forward' and `paredit-backward' use a "_" interactive
  specification in XEmacs in order to preserve the mark.

- `paredit-region-active-p' is just `region-active-p' in XEmacs.

- Some hair was needed to handle S-expression parse error conditions
  properly, and versions of XEmacs earlier than 21.5 may have obscure
  problems as a result.

*** Style and Bugs

- rxvt-specific terminal escape sequences are no longer bound to the
  commands that the keys those sequences denote are.  Set your
  environment variables correctly and keep your rxvt.el updated.
  (Aren't terminals fun?)

- HTML output is now properly quoted.  Some vestigial indirections in
  the tables have been removed.

- Yet *ANOTHER* `paredit-kill' bug is fixed.  I do not know what the
  bug is or why it happened, but it seems to be gone now.

- Improved robustness of `paredit-join-sexps' and `paredit-splice-sexp'
  with respect to their use in the middle of atoms, and made splicing
  within a string illegal.

- Fixed several bugs in the paredit word killing commands.  In the
  process, however, I encountered what seems to be a bug in Emacs's
  `parse-partial-sexp', which may mean bugs in other things...

- Eliminated dependency on `cl' feature.

- Fixed a bug in `paredit-backward-kill-word' that would cause deletion
  of the first double-quote in `(foo "|")'.

- Fixed a bug with `paredit-backward-kill-word' at the end of buffer.

- Fixed a bug with `paredit-backward-kill-word' before any words in a
  buffer.

*** Altered Behaviour and New Functionality

- `paredit-mode' now accepts a prefix argument to mean that it should
  not check the parentheses in the buffer first.  Supply the prefix
  argument with care; though it is useful for editing small parts of a
  buffer in Lisp when the rest is random, it might also screw the whole
  buffer up in unpredictable ways, because most of paredit doesn't
  even try to handle invalid structure.

- Parenthesis blinking is improved somewhat to better respect user
  customization of `blink-matching-paren'.

- The paredit minor mode no longer exchanges C-j & RET; following the
  GNU Emacs conventions, it now leaves RET alone and binds C-j to
  `paredit-newline'.  Those of you, such as me, who relied on the old
  exchange will have to update your .emacs files.

- C-left and C-right are now bound to paredit-forward-barf-sexp and
  paredit-forward-slurp-sexp, instead of M-left and M-right, whose word
  motion bindings are no longer shadowed.

- The behaviour of (, ", M-(, and M-" with respect to active regions
  and prefix arguments has been regularized:

  . With neither an active region, i.e. an active mark and
    transient-mark-mode, ( and " will insert a pair of delimiters at
    the point, and M-( and M-" will wrap the following expression with
    delimiters.

  . With an active region and no prefix argument, if and only if the
    region contains only balanced expressions, all four commands will
    wrap the region with the respective delimiters.

  . With a prefix argument N, all four commands will wrap the next N
    expressions with the commands' respective delimiters.

  " and M-", of course, escape any characters that need escaping first
  if they are used to wrap regions.

- Implemented slurpage into strings.

- Made `M-- M-s' equivalent to `M-- M-1 M-s'.

- Changed `paredit-insert-pair' so that it will not skip whitespace
  before inserting the pair.

- `paredit-splice-sexp' with a prefix argument and friends (i.e. `M-s',
  `M-<up>', and `M-<down>') now always create a new entry on the kill
  ring.

** Version 19

This version introduces support for delimiters other than round
brackets.  Previously, if the major mode's syntax table considered
square brackets (and curly braces, &c.) to be delimiters, since no
paredit commands would insert them balanced, deleting them would be
tricky: paredit's DEL & C-d bindings would refuse to delete them
because they would be imbalanced unless you manually type the closing
delimiter.

Now commands are defined for the opening and closing of parentheses
(round), brackets (square), braces (curly), and brockets (angled),
named `paredit-open-<type>', `paredit-close-<type>-and-newline', and
`paredit-close-<type>'; paredit-mode binds the opening and closing
square bracket keys to be `paredit-open-bracket' and `paredit-close-
bracket', respectively.  The rest you can bind yourself; this minimal
pair of bindings will, I think, account for accidental insertion,
elisp vectors, and (bletch) the equation of square and round brackets
as parentheses in some non-standard Scheme extensions.

Also now supported in this release is insertion of delimiter pairs
around active regions in transient-mark-mode.  If you mark a region
with transient-mark-mode enabled, you can use any of the delimiter
pair insertion keys (like opening round bracket, double-quote, &c.)
to insert a pair of delimiters around the region.  There are now two
ways to parenthesize lists of expressions with visual feedback: using
M-( (paredit-wrap-sexp) followed by C-) (paredit-forward-slurp-sexp)
until satisfied, and now C-M-SPC (mark-sexp) until you have marked
the desired expressions and then any of the delimiter pair insertion
keys to insert the delimiters.

** Version 18

*** Style and Bugs

- Corrected terminal arrow key sequences *again*.  M-left and M-right
  were backwards.

- Put the save-excursion back in paredit-recentre-on-sexp.  I don't
  remember why it was taken out in version 13.

- Fixed HTML output to stop producing spurious <tr> tags.

- Corrected a number of paredit command examples.

- Aesthetic changes to the code:

  . Regularized some aspects of code style.

  . Repaginated so that all pages are at most 80 lines long, and most
    are at least 40 lines.

  . Formatted headings for an outline regexp to match so that
    outline-minor-mode works nicely on paredit.el.

*** Altered Behaviour and New Functionality

- Implemented paredit-forward-kill-word & paredit-backward-kill-word,
  or M-d & M-DEL, which are like kill-word & backward-kill-word, but
  they will not kill parenthesis, string, or comment delimiters; they
  will preserve the structure of S-expressions, while the built-in
  Emacs word killing commands would destroy it.

- M-" is now bound to paredit-meta-doublequote, which has the old
  behaviour of paredit-close-string-and-newline if within a string,
  but which wraps the following S-expression (or N S-expressions) in
  double-quotes if without a string; paredit-doublequote does the
  same, but the default argument is 0, not 1.

- M-S (paredit-split-sexp) no longer deletes horizontal space in
  strings before splitting them into two.  The rationale, as
  suggested by Zbigniew Szadkowski, is that whitespace is usually
  significant in strings, while not in lists, and you can type M-\
  M-S if you really do want the horizontal space deleted anyway.

- Reintroduced paredit-join-sexps as M-J.  The implementation is now
  more robust: it ensures that the two S-expressions to join match --
  i.e. they are both lists, or they are both strings, or they are
  both symbols --, and it correctly handles the atom case now as
  well.

- Extended paredit command examples to allow multiple steps in
  succession of a single example.

** Version 17

*** Style and Bugs

- Rewrote all documentation strings to be in the imperative mood, per
  GNU Emacs's guidelines.  Some documentation strings may have been
  corrected, too, but I can't be bothered to grovel through the diff
  to pick out all changes to all documentation strings.

- Forced parenthesis flashing even with show-paren-mode enabled.

- Fixed bug in forward deletion within strings so that the empty
  string can be deleted.

- Simplified determination of whether the point is in a comment.

*** Altered Behaviour and New Functionality

- Eliminated paredit-terminal-mode.  All key bindings it had are now
  incorporated into paredit-mode's keymap.  I may have changed some
  keybindings, too, but I don't remember what they were if I did.  I
  think I fixed some of the keybindings in the terminal.

- Added examples to documentation of all paredit commands, as well as
  code to generate an HTML file containing the examples in nicely
  formatted tables (sorry, web purists).

- Made paredit-mode refuse to be enabled in a buffer with imbalanced
  parentheses.

- Updated documentary heading.  It now explains how to customize keys
  while still autoloading and how to make paredit's RET work nicely
  with SLIME's REPL.

- Improved semicolon insertion: (a) to accept a numeric prefix
  argument dictating a number of semicolons to insert, instead of a
  prefix argument that forces the insertion of a semicolon without a
  trailing newline, which can be effected with C-q anyway; and (b) to
  allow insertion of semicolons before existing comments without
  inserting a superfluous leading newline.  To comment out code, you
  must still use M-; or M-x comment-region.

** Version 16

- Introduced M-S (paredit-split-sexp) to split lists or strings from
  the middle.

- Fixed the definition of M-; to use (kbd "M-;") to correctly
  identify the key sequence meta-semicolon, not "M-;" for M hyphen
  semicolon.

** Version 15

Paredit version 15 release notes

- Rewrote comment insertion code.

- Implemented M-; (paredit-comment-dwim), which is like comment-dwim
  but inserts comments more appropriately with respect to paredit.

** Version 14

Version 14 introduced fancy comment handling:

- paredit-close-list-and-newline now refuses to move a margin comment
  to another line; instead it will help to preserve the column of the
  comment.

- The semicolon key is now bound to a command that will automatically
  move any code following the point onto the next line, so that you
  do not inadvertently comment out half expressions.  You can still
  use M-; (comment-dwim) to comment out specific regions that are not
  meant to be code (e.g., old comments that were accidentally
  uncommented) or whole S-expressions, usually in conjunction with
  C-M-SPC (mark-sexp).

** Version 13

- Removed M-\ (paredit-join-sexps), whose key binding conflicts with
  delete-horizontal-space and whose implementation was inadequate and
  led to general uselessness of the command.

- Improved RET (paredit-newline) so that it does not do anything
  fancy within strings and first tests whether the point is in a
  comment before checking whether it is in a character.

- Changed paredit-skip-whitespace from skip-syntax-{forward,backward}
  to skip-chars-{forward,backward}, because in the Lisp syntax table
  newlines are not considered whitespace -- rather, they are comment
  ends --, but we want to skip them nevertheless.

- Corrected paredit-kill in a way I don't understand.

- Minor code improvements, including:

  . Changed call to previous-line to use forward-line instead.
  . Removed unnecessary save-excursion in paredit-recentre-on-sexp.
  . IF indentation changes.

** Version 12

- Implemented M-r (paredit-raise-sexp), which raises a single
  S-expression up the tree, deleting all of its siblings and its
  enclosing list.

- Rearranged some arrow key bindings again.

- Made paredit-forward-delete and paredit-backward-delete check for
  buffer bounds and also matching of the delimiters of empty lists.

- Added a buffer bounds check to paredit-kill.

- Made backward barfing signal an error, not just a message.

** Version 11

- Changed the key for paredit-splice-sexp from M-/, which is by
  default the popular dabbrev-expand, to M-s, which I was surprised
  to find no existing binding for.

- Added a prefix argument to paredit-splice-sexp; see the command's
  documentation for details.  M-up is now equivalent to C-u M-s;
  M-down, to C-u C-u M-s.

- Fixed a lot of the terminal key sequences for the arrow key
  bindings in paredit-terminal-mode.

- Modified the behaviour of paredit-forward and paredit-backward to
  change only one level of nesting depth, not to repeat until there
  is a sibling S-expression to move across.

- Changed a lot of code to use character syntax, instead of exact
  character comparisons, for better generality.

- Rewrote much of paredit-kill, again.

** Version 10

- Introduced paredit-forward and paredit-backward, which are like
  forward-sexp and backward-sexp but which will also go up a nesting
  level if at the end of a list.

- Introduced C-c C-M-l (paredit-recentre-on-sexp), whose name is
  self-explanatory.

- Added support for numeric prefix arguments to paredit-open-list.

- Fixed paredit-kill so that it would correctly kill whitespace
  between parentheses, as in (   ).

- Changed suggestion of what to put in your .emacs from require to
  autoload.

** Version 9

- Introduced enable-paredit-mode and disable-paredit-mode to better
  choose which one to enable.

- Forced blinkage of matching parentheses in paredit-close-list and
  paredit-close-list-and-newline, even if show-paren-mode is enabled.

** Version 8

- Added paredit-terminal-mode, which is like paredit-mode but which
  provides key bindings that work in terminals, while paredit-mode
  contains many (such as controlled brackets) that do not work in
  terminals.  Thanks to Jorgen Schaefer for suggesting many of the
  terminal key bindings.

- Exchanged RET and C-j: RET now inserts the fancy newline with auto-
  indentation, while C-j inserts a literal line feed.  While this
  defies convention, and some people prefer not to do this, I have
  found that it is more convenient for RET to have the behaviour of
  the common case, where auto-indentation is desired, and for C-j to
  insert the uncommon exact, literal line feed.  You can always
  customize the key bindings yourself, of course.

- Rearranged arrow key bindings.

- Implemented paredit-close-list-and-newline, which is like
  paredit-close-list followed by RET (paredit-newline); and M-"
  (paredit-close-string-and-newline), which is similar but for
  strings.
  The closing round bracket character now inserts the newline, while
  the meta modifier inhibits this.

- Overhauled paredit-kill.

- Extended slurpage and barfage to permit their operation across
  arbitrary depth changes.

- Fixed bizarre bug with backward barfage.  I apologize for the
  alliteration.

- Fixed a number of other small bugs.

- Prefixed `paredit-' to the remaining functions defined in the file
  that did not already have the prefix.

- Defined backward-down-list, which for some reason is not provided
  by lisp.el, although up-list, down-list, & backward-up-list all
  are.  (This is the sole exception to the above item.  It deserves
  no prefix because it ought to be defined in lisp.el with this name
  anyway.)

** Version 7

- Changed paredit-open-list and paredit-close-list so that they will
  refuse to insert parentheses inside character literals.

- Substituted new code for GNU Emacs's move-past-close-and-reindent.
  I do not remember why now, and I no longer understand either code
  well enough to discern differences, other than that Emacs's
  m-p-c-a-r is probably faster because it incrementally parses each
  step of the way.  All I can see is that paredit.el's code now
  inserts indentation before the closing parenthesis while Emacs's
  m-p-c-a-r does not.

- Fixed bugs in deletion within character literals and strings.

** Versions 2--6

(I lost versions 2, 3, 4, & 5.)

- Flushed M-" (paredit-insert-doublequote), which was rather useless
  and which " (paredit-doublequote) now subsumes the functionality of.

- Added instrumented forward deletion as well as backward deletion,
  which now behave well inside strings.

- Flushed unnecessary individual round bracket insertion keys; use
  C-q instead.

- Added C-left & C-right: backward-sexp & forward-sexp, respectively.

- Fixed the test of whether the point is in a character literal.

- Modified " (paredit-doublequote) to insert escaped double-quote if
  in the middle of the string, rather than to jump past the string's
  closing delimiter.

- Introduced bogus backslash escaping mechanism.

- Introduced new command for breaking the line and indenting, and
  bound C-j, rather than RET, to it, according to convention.

- Improved C-k (paredit-kill), particularly in strings where it will
  no longer kill the closing delimiter of the string.

- Changed the splicage, joinage, slurpage, and barfage commands so
  that they will reindent only the modified list, not the whole
  definition.