[elpa] 179/299: Docs for paired braces feature.

[Stefan Monnier]

monnier pushed a commit to branch externals/auctex
in repository elpa.

commit 53532775f75ca10978a25c5d8f1a06048c62a51d
Author: Ikumi Keita <address@hidden>
Date:   Thu Oct 10 10:38:53 2013 +0200

    Docs for paired braces feature.
    
    * doc/changes.texi: Document enhanced paired braces feature.
    
    * doc/auctex.texi: Ditto.
    
    Signed-off-by: Tassilo Horn <address@hidden>
---
 ChangeLog        |    6 +++
 doc/auctex.texi  |  106 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/changes.texi |   18 +++++++++
 3 files changed, 129 insertions(+), 1 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1db1fb3..5132bb9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-10-10  Tassilo Horn  <address@hidden>
+
+       * doc/changes.texi: Document enhanced paired braces feature.
+
+       * doc/auctex.texi: Ditto.
+
 2013-10-06  Mos� Giordano  <address@hidden>
 
        * tex.el (TeX-insert-macro-default-style): Add new possible value
diff --git a/doc/auctex.texi b/doc/auctex.texi
index 052ca42..1338aed 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -315,7 +315,7 @@ entering more specialized sorts of text, for formatting the 
source by
 indenting and filling and for navigating through the document.
 
 @menu
-* Quotes::                      Inserting double quotes
+* Quotes::                      Inserting quotes, dollars, and braces
 * Font Specifiers::             Inserting Font Specifiers
 * Sectioning::                  Inserting chapters, sections, etc.
 * Environments::                Inserting Environment Templates
@@ -471,6 +471,110 @@ to type inside of them.  If there is an active region, 
put braces around
 it and leave point after the closing brace.
 @end deffn
 
+When writing complex math formulas in @LaTeX{} documents, you
+sometimes need to adjust the size of braces with pairs of macros like
address@hidden@samp{\right}, @address@hidden and so on.  You
+can avoid unbalanced pairs with the help of @code{TeX-insert-macro},
+bound to @kbd{C-c C-m} or @kbd{C-c @key{RET}} (@pxref{Completion}).
+If you insert left size adjusting macros such as @samp{\left},
address@hidden etc. with @code{TeX-insert-macro}, it asks for left brace
+to use and supplies automatically right size adjusting macros such as
address@hidden, @samp{\bigr} etc. and corresponding right brace in
+addtion to the intended left macro and left brace.
+
+The completion by @code{TeX-insert-macro} also applies when entering
+macros such as @samp{\langle}, @samp{\lfloor} and @samp{\lceil}, which
+produce the left part of the paired braces.  For example, inserting
address@hidden by @kbd{C-c C-m} is immediately followed by the
+insertion of @samp{\rfloor}.  In addition, if the point was located
+just after @samp{\left} or its friends, the corresponding
address@hidden etc. will be inserted in front of @samp{\rfloor}.
+In both cases, active region is honored.
+
+As a side effect, when @code{LaTeX-math-mode} (@pxref{Mathematics}) is
+on, just typing @kbd{`(} inserts not only @samp{\langle}, but also
address@hidden
+
+If you don't like such auto completion at all, it can be disabled by
+an user option.
+
address@hidden TeX-arg-right-insert-p
+If this option is turned off, the automatic supply of the right macros
+and braces is suppressed.
address@hidden defopt
+
+When you edit @LaTeX{} documents, you can enable automatic brace
+pairing when typing @kbd{(}, @address@hidden and @kbd{[}.
+
address@hidden LaTeX-electric-left-right-brace
+If this option is on, just typing @kbd{(}, @address@hidden or @kbd{[}
+immediately adds the corresponding right brace @samp{)}, @address@hidden or
address@hidden  The point is left after the opening brace.  If there is an
+active region, braces are put around it.
+
+They recognize the preceeding backslash or size adjusting macros such
+as @samp{\left}, @samp{\bigl} etc., so the following completions will
+occur:
address@hidden @bullet
+
address@hidden
+(when typing single left brace)
address@hidden @minus
+
address@hidden
address@hidden(} -> @samp{()}
+
address@hidden
address@hidden@{} -> @address@hidden@}}
+
address@hidden
address@hidden -> @samp{[]}
address@hidden itemize
+
address@hidden
+(when typing left brace just after a backslash)
address@hidden @minus
+
address@hidden
address@hidden(} -> @samp{\(\)}
+
address@hidden
address@hidden@{} -> @address@hidden@}}
+
address@hidden
address@hidden -> @samp{\[\]}
address@hidden itemize
+
address@hidden
+(when typing just after @samp{\left} or @samp{\bigl})
address@hidden @minus
+
address@hidden
address@hidden(} -> @samp{\left(\right)}
+
address@hidden
address@hidden -> @samp{\bigl[\bigr]}
address@hidden itemize
+
address@hidden
+(when typing just after @samp{\Bigl\})
address@hidden @minus
+
address@hidden
address@hidden@{} -> @address@hidden@}}
+
address@hidden itemize
+
address@hidden itemize
+
+This auto completion feature may be a bit annoying when editing an
+already existing @LaTeX{} document.  In that case, use @kbd{C-u 1} or
address@hidden before typing @kbd{(}, @address@hidden or @kbd{[}.  Then no
+completion is done and just a single left brace is inserted.  In fact,
+with optional prefix @var{arg}, just that many open braces are
+inserted without any completion.
address@hidden defopt
+
 @node Font Specifiers
 @section Inserting Font Specifiers
 
diff --git a/doc/changes.texi b/doc/changes.texi
index 183ff82..5cac301 100644
--- a/doc/changes.texi
+++ b/doc/changes.texi
@@ -48,6 +48,24 @@ environment is @samp{frame}, with @samp{letter} it is 
@samp{letter},
 with @samp{slides} it is @samp{slide}.
 
 @item
+Brace pairing feature was enhanced in @LaTeX{} documents.  Support for
address@hidden, @samp{\Bigl}, @samp{\biggl} and @samp{\Biggl}, the same
+as the one for @samp{\left}, was added to @code{TeX-insert-macro}.
+For example, @kbd{C-c @key{RET} bigl @key{RET} ( @key{RET}} inserts
address@hidden(\bigr)}.
+
+You can insert brace pair @samp{()}, @address@hidden@}} and @samp{[]} by typing
+a single left brace if the new user option
address@hidden is enabled.
+
+Macros @samp{\langle}, @samp{\lfloor} and @samp{\lceil}, which produce
+the left part of the paired braces, are treated similarly as @samp{(},
address@hidden@{} and @samp{[} during the course of @code{TeX-insert-macro}.
address@hidden rawfile
address@hidden, for details.
address@hidden ifclear
+
address@hidden
 Support for dozens of @LaTeX{} packages was added.
 @end itemize