[elpa] elpa 131c537 14/35: Document interaction with Ispell

[Tassilo Horn]

branch: elpa
commit 131c537405303345402365933361df3b7ee71d79
Author: Arash Esbati <address@hidden>
Commit: Arash Esbati <address@hidden>

    Document interaction with Ispell
    
    * doc/auctex.texi (Selecting a Command): Document interaction with Ispell.
---
 doc/auctex.texi |  120 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)

diff --git a/doc/auctex.texi b/doc/auctex.texi
index 13afe05..d286ccf 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -2876,6 +2876,126 @@ If nil, just check the current file.
 Used when checking if any files have changed.
 @end defopt
 
address@hidden ispell
+When performing spell checking on a document or a region (invoked
+through @AUCTeX{}'s @samp{Spell} command or @kbd{M-x ispell RET}), you
+want the spell checking program to skip certain macro arguments and
+environments, most notably the arguments of referencing macros and the
+contents of verbatim environments.  The skipped parts are controlled by
+variable @code{ispell-tex-skip-alists} provided by @file{ispell.el}.
address@hidden has a library which can be added to this variable depending on
+the value of @code{TeX-ispell-extend-skip-list} which is set to @code{t}
+by default.
+
address@hidden TeX-ispell-extend-skip-list
+This boolean option controls whether @AUCTeX{} activates its extension
+for skipping certain macro arguments and environments when spell
+checking.
+
+When address@hidden, @AUCTeX{} loads the file @file{tex-ispell.el} and
+adds its content to @code{ispell-tex-skip-alists}.  This library can and
+will never be complete, but the interface can be used to add selected
+and private macro names within your init file or on a file local basis.
+
address@hidden has the following structure:
address@hidden
+(defvar ispell-tex-skip-alists
+  '((;; First list
+     ("\\\\addcontentsline"         ispell-tex-arg-end 2)
+     ("\\\\\\([aA]lph\\|arabic\\)"  ispell-tex-arg-end)
+     ("\\\\makebox"                 ispell-tex-arg-end 0)
+     ("\\\\documentclass" . "address@hidden@}"))
+    (;; Second list
+     ("\\(figure\\|table\\)\\*?"  ispell-tex-arg-end 0)
+     ("list"                      ispell-tex-arg-end 2)
+     ("verbatim\\*?" . "address@hidden@}")))
+  "*Lists of regions to be skipped in TeX mode.
+First list is used raw.
+Second list has key placed inside address@hidden@}.")
address@hidden lisp
+Each item is an alist and the structure of it is described in
address@hidden:
address@hidden
+(defvar ispell-skip-region-alist
+  '((...))
+  "Alist expressing beginning and end of regions not to spell check.
+The alist key must be a regular expression.
+Valid forms include:
+  (KEY) - just skip the key.
+  (KEY . REGEXP) - skip to the end of REGEXP.
+                   REGEXP may be string or symbol.
+  (KEY REGEXP) - skip to end of REGEXP.  REGEXP must be a string.
+  (KEY FUNCTION ARGS) - FUNCTION called with ARGS
+                        returns end of region.")
address@hidden lisp
+
+Let's go through the first list of @code{ispell-tex-skip-alists} line by
+line:
address@hidden
+("\\\\addcontentsline"         ispell-tex-arg-end 2)
address@hidden lisp
address@hidden is the string @code{"\\\\addcontentsline"}, @code{FUNCTION}
+is @code{ispell-tex-arg-end} called with @code{ARGS}, here @code{2}.
address@hidden is a function provided by @file{ispell.el}
+which skips as many subsequent optional arguments in square brackets as
+it sees and then skips @code{ARGS} number of mandatory arguments in
+braces.  Omitting @code{ARGS} means skip @code{1} mandatory argument.
+In practice, when you have something like this in your document:
address@hidden
address@hidden@address@hidden@address@hidden address@hidden
address@hidden example
+The first two arguments are left out and @samp{Some text} will be spell
+checked.  For the next line
address@hidden
+("\\\\\\([aA]lph\\|arabic\\)"  ispell-tex-arg-end)
address@hidden lisp
+the name of the counter as argument is skipped.  Next line is
address@hidden
+("\\\\makebox"                 ispell-tex-arg-end 0)
address@hidden lisp
+where only optional arguments are skipped, the first mandatory argument
+is checked, e.g.
address@hidden
address@hidden address@hidden
address@hidden example
+Finally, the next line
address@hidden
+("\\\\documentclass" . "address@hidden@}"))
address@hidden lisp
+ensures that the entire preamble of a document is discarded.  Second
+list works the same; it is more convenient for environments since
address@hidden is wrapped inside @address@hidden@}}.
+
address@hidden provides two functions to add items to car and cdr of
address@hidden, namely @code{TeX-ispell-skip-setcar} and
address@hidden  The argument of these functions is
+exactly as in @code{ispell-tex-skip-alists}.  Additions can be done via
+init file, e.g.:
address@hidden
+(eval-after-load "tex-ispell"
+  '(progn
+     (TeX-ispell-skip-setcar
+      '(("\\\\mymacro" ispell-tex-arg-end)))
+     (TeX-ispell-skip-setcdr
+      '(("myverbatim" . "address@hidden@}")))))
address@hidden lisp
+Another possibility is to use file local additions at the end of your
address@hidden file, e.g.:
address@hidden
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% eval: (TeX-ispell-skip-setcar '(("\\\\mymacro" . "@address@hidden")))
+%%% End:
address@hidden example
+
address@hidden TeX-ispell-tex-arg-end
+Finally, @AUCTeX{} provides a function called
address@hidden which sees more arguments than
address@hidden  Refer to its doc string for more
+information.
address@hidden defopt
+
 @node Processor Options
 @subsection Options for @TeX{} Processors