+2010-12-07 Stefan Monnier <monnier@iro.umontreal.ca>
+
+ * modes.texi (Auto-Indentation): New section to document SMIE.
+ (Major Mode Conventions):
+ * text.texi (Mode-Specific Indent): Refer to it.
+
2010-12-04 Eli Zaretskii <eliz@gnu.org>
* display.texi (Other Display Specs): Document left-fringe and
2010-11-21 Chong Yidong <cyd@stupidchicken.com>
- * nonascii.texi (Converting Representations): Document
- byte-to-string.
+ * nonascii.texi (Converting Representations):
+ Document byte-to-string.
* strings.texi (Creating Strings): Don't mention semi-obsolete
function char-to-string.
* customize.texi (Composite Types): Lower-case index entry.
- * loading.texi (How Programs Do Loading): Document
- load-file-name. (Bug#7346)
+ * loading.texi (How Programs Do Loading):
+ Document load-file-name. (Bug#7346)
2010-11-10 Glenn Morris <rgm@gnu.org>
* keymaps.texi (Menu Bar): Document :advertised-binding property.
- * functions.texi (Obsolete Functions): Document
- set-advertised-calling-convention.
+ * functions.texi (Obsolete Functions):
+ Document set-advertised-calling-convention.
* minibuf.texi (Basic Completion): Document completion-in-region.
(Programmed Completion): Document completion-annotate-function.
* minibuf.texi (Basic Completion): 4th arg to all-completions is
obsolete.
- * processes.texi (Process Buffers): Document
- process-kill-buffer-query-function.
+ * processes.texi (Process Buffers):
+ Document process-kill-buffer-query-function.
2009-12-05 Glenn Morris <rgm@gnu.org>
(Suspending Emacs): Mark suspend-emacs as a command.
(Processor Run Time): Mark emacs-uptime and emacs-init-time as
commands.
- (Terminal Output): Remove obsolete function baud-rate. Document
- TERMINAL arg for send-string-to-terminal.
+ (Terminal Output): Remove obsolete function baud-rate.
+ Document TERMINAL arg for send-string-to-terminal.
* nonascii.texi (Terminal I/O Encoding): Document TERMINAL arg for
terminal-coding-system and set-terminal-coding-system.
2009-05-09 Eli Zaretskii <eliz@gnu.org>
* nonascii.texi (Default Coding Systems): Document
- find-auto-coding, set-auto-coding, and auto-coding-alist. Add
- indexing.
+ find-auto-coding, set-auto-coding, and auto-coding-alist.
+ Add indexing.
(Lisp and Coding Systems): Add index entries.
2009-05-09 Martin Rudalics <rudalics@gmx.at>
2009-04-22 Chong Yidong <cyd@stupidchicken.com>
- * os.texi (Command-Line Arguments): Document
- command-line-args-left.
+ * os.texi (Command-Line Arguments):
+ Document command-line-args-left.
(Suspending Emacs): Adapt text to multi-tty case. Document use of
terminal objects for tty arguments.
(Startup Summary): Add xref to Session Management.
2009-04-09 Chong Yidong <cyd@stupidchicken.com>
* text.texi (Yank Commands): Note that yank uses push-mark.
- (Filling): Clarify REGION argument of fill-paragraph. Document
- fill-forward-paragraph-function.
+ (Filling): Clarify REGION argument of fill-paragraph.
+ Document fill-forward-paragraph-function.
(Special Properties): Remove "new in Emacs 22" declaration.
(Clickable Text): Merge with Links and Mouse-1 node.
- * display.texi (Button Properties, Button Buffer Commands): Change
- xref to Clickable Text.
+ * display.texi (Button Properties, Button Buffer Commands):
+ Change xref to Clickable Text.
* tips.texi (Key Binding Conventions): Change xref to Clickable
Text.
2009-03-29 Chong Yidong <cyd@stupidchicken.com>
- * help.texi (Accessing Documentation, Help Functions): Remove
- information about long-obsolete Emacs versions.
+ * help.texi (Accessing Documentation, Help Functions):
+ Remove information about long-obsolete Emacs versions.
* modes.texi (Mode Line Variables): The default values of the mode
line variables are now more complicated.
2009-03-23 Chong Yidong <cyd@stupidchicken.com>
* minibuf.texi (Intro to Minibuffers): Remove long-obsolete info
- about minibuffers in old Emacs versions. Copyedits. Emphasize
- that enable-recursive-minibuffers defaults to nil.
+ about minibuffers in old Emacs versions. Copyedits.
+ Emphasize that enable-recursive-minibuffers defaults to nil.
(Text from Minibuffer): Simplify introduction.
2009-03-22 Alan Mackenzie <acm@muc.de>
* customize.texi (Common Keywords): It's not necessary to use :tag
to remove hyphens, as custom-unlispify-tag-name does it
automatically.
- (Variable Definitions): Link to File Local Variables. Document
- customized-value symbol property.
+ (Variable Definitions): Link to File Local Variables.
+ Document customized-value symbol property.
(Customization Types): Move menu to end of node.
2009-03-10 Chong Yidong <cyd@stupidchicken.com>
* text.texi (Commands for Insertion):
* commands.texi (Event Mod):
* keymaps.texi (Searching Keymaps):
- * nonascii.texi (Translation of Characters): Reinstate
- documentation of translation-table-for-input.
+ * nonascii.texi (Translation of Characters):
+ Reinstate documentation of translation-table-for-input.
(Explicit Encoding): Document the `charset' text property produced
by decode-coding-region and decode-coding-string.
2009-01-22 Chong Yidong <cyd@stupidchicken.com>
* files.texi (Format Conversion Piecemeal): Clarify behavior of
- write-region-annotate-functions. Document
- write-region-post-annotation-function.
+ write-region-annotate-functions.
+ Document write-region-post-annotation-function.
2009-01-19 Chong Yidong <cyd@stupidchicken.com>
* processes.texi (Serial Ports): Improve wording, suggested by RMS.
- * nonascii.texi (Lisp and Coding Systems): Document
- inhibit-null-byte-detection and inhibit-iso-escape-detection.
+ * nonascii.texi (Lisp and Coding Systems):
+ Document inhibit-null-byte-detection and inhibit-iso-escape-detection.
(Character Properties): Improve wording.
2009-01-09 Chong Yidong <cyd@stupidchicken.com>
* display.texi (Font Lookup): Remove obsolete function
x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax.
(Low-Level Font): Rename from Fonts, move to end of Faces section.
- (Font Selection): Reorder order of variable descriptions. Minor
- clarifications.
+ (Font Selection): Reorder order of variable descriptions.
+ Minor clarifications.
* elisp.texi (Top): Update node listing.
* elisp.texi: Update node listing.
* display.texi (Faces): Put Font Selection node after Auto Faces.
- (Face Attributes): Don't link to Font Lookup. Document
- font-family-list.
+ (Face Attributes): Don't link to Font Lookup.
+ Document font-family-list.
(Fonts): New node.
2009-01-08 Jason Rumney <jasonr@gnu.org>
* windows.texi (Window Hooks): Remove *-end-trigger-functions
vars, which are obsolete. Mention jit-lock-register.
- * modes.texi (Other Font Lock Variables): Document
- jit-lock-register and jit-lock-unregister.
+ * modes.texi (Other Font Lock Variables):
+ Document jit-lock-register and jit-lock-unregister.
* frames.texi (Color Parameters): Document alpha parameter.
2008-11-01 Eli Zaretskii <eliz@gnu.org>
* nonascii.texi (Text Representations): Rewrite to make consistent
- with Emacs 23 internal representation of characters. Document
- `unibyte-string'.
+ with Emacs 23 internal representation of characters.
+ Document `unibyte-string'.
2008-10-28 Chong Yidong <cyd@stupidchicken.com>
* processes.texi (Synchronous Processes): Document `process-lines'.
- * customize.texi (Variable Definitions): Document
- `custom-reevaluate-setting'.
+ * customize.texi (Variable Definitions):
+ Document `custom-reevaluate-setting'.
2008-10-18 Martin Rudalics <rudalics@gmx.at>
* maps.texi (Standard Keymaps): Document `multi-query-replace-map'
and `search-map'.
- * searching.texi (Search and Replace): Document
- `replace-search-function' and `replace-re-search-function'.
+ * searching.texi (Search and Replace):
+ Document `replace-search-function' and `replace-re-search-function'.
Document `multi-query-replace-map'.
* minibuf.texi (Text from Minibuffer): Document `read-regexp'.
- (Completion Commands, Reading File Names): Rename
- `minibuffer-local-must-match-filename-map' to
+ (Completion Commands, Reading File Names):
+ Rename `minibuffer-local-must-match-filename-map' to
`minibuffer-local-filename-must-match-map'.
(Minibuffer Completion): The `require-match' argument to
`completing-read' can now have the value `confirm-only'.
2007-12-30 Richard Stallman <rms@gnu.org>
- * commands.texi (Accessing Mouse): Renamed from Accessing Events.
+ * commands.texi (Accessing Mouse): Rename from Accessing Events.
(Accessing Scroll): New node broken out of Accessing Mouse.
2007-12-28 Richard Stallman <rms@gnu.org>
2007-11-29 Glenn Morris <rgm@gnu.org>
- * functions.texi (Declaring Functions): Add findex. Mention
- `external' files.
+ * functions.texi (Declaring Functions): Add findex.
+ Mention `external' files.
2007-11-26 Juanma Barranquero <lekktu@gmail.com>
* display.texi (Display Property): Explain some display specs
don't let you move point in.
- * frames.texi (Cursor Parameters): Describe
- cursor-in-non-selected-windows here. Explain more values.
+ * frames.texi (Cursor Parameters):
+ Describe cursor-in-non-selected-windows here. Explain more values.
* windows.texi (Basic Windows): Don't describe
cursor-in-non-selected-windows here.
2007-08-16 Richard Stallman <rms@gnu.org>
- * processes.texi (Asynchronous Processes): Clarify
- doc of start-file-process.
+ * processes.texi (Asynchronous Processes):
+ Clarify doc of start-file-process.
2007-08-08 Martin Rudalics <rudalics@gmx.at>
2007-06-27 Richard Stallman <rms@gnu.org>
- * files.texi (Format Conversion Piecemeal): Clarify
- `after-insert-file-functions' calling convention.
+ * files.texi (Format Conversion Piecemeal):
+ Clarify `after-insert-file-functions' calling convention.
2007-06-27 Michael Albinus <michael.albinus@gmx.de>
2007-05-30 Nick Roberts <nickrob@snap.net.nz>
- * commands.texi (Click Events): Layout more logically. Describe
- width and height.
+ * commands.texi (Click Events): Layout more logically.
+ Describe width and height.
(Drag Events, Motion Events): Update to new format for position.
2007-06-02 Richard Stallman <rms@gnu.org>
2007-03-05 Richard Stallman <rms@gnu.org>
- * variables.texi (File Local Variables): Update
- enable-local-variables values.
+ * variables.texi (File Local Variables):
+ Update enable-local-variables values.
2007-03-04 Richard Stallman <rms@gnu.org>
2007-02-03 Eli Zaretskii <eliz@gnu.org>
* elisp.texi (Top): Make the detailed menu headers compliant with
- Texinfo guidelines and with what texnfo-upd.el expects. Add
- comments to prevent people from inadvertently modifying the key
+ Texinfo guidelines and with what texnfo-upd.el expects.
+ Add comments to prevent people from inadvertently modifying the key
parts needed by `texinfo-multiple-files-update'.
2007-02-02 Eli Zaretskii <eliz@gnu.org>
2006-12-24 Richard Stallman <rms@gnu.org>
- * customize.texi (Variable Definitions): Document
- new name custom-add-frequent-value.
+ * customize.texi (Variable Definitions):
+ Document new name custom-add-frequent-value.
2006-12-19 Kim F. Storm <storm@cua.dk>
2006-09-01 Chong Yidong <cyd@stupidchicken.com>
- * buffers.texi (Buffer Modification): Document
- buffer-chars-modified-tick.
+ * buffers.texi (Buffer Modification):
+ Document buffer-chars-modified-tick.
2006-08-31 Richard Stallman <rms@gnu.org>
2006-08-12 Chong Yidong <cyd@stupidchicken.com>
* text.texi (Near Point): Say "cursor" not "terminal cursor".
- (Commands for Insertion): Removed split-line since it's not
+ (Commands for Insertion): Remove split-line since it's not
relevant for Lisp programming.
(Yank Commands): Rewrite introduction.
(Undo): Clarify.
(Major Mode Basics): Mention define-derived-mode explicitly.
(Major Mode Conventions): Rebinding RET is OK for some modes.
Mention change-major-mode-hook and after-change-major-mode-hook.
- (Example Major Modes): Moved to end of Modes section.
+ (Example Major Modes): Move to end of Modes section.
(Mode Line Basics): Clarify.
(Mode Line Data): Mention help-echo and local-map in strings.
Explain reason for treatment of non-risky variables.
2006-05-25 Chong Yidong <cyd@stupidchicken.com>
- * keymaps.texi (Key Sequences): Renamed from Keymap Terminology.
+ * keymaps.texi (Key Sequences): Rename from Keymap Terminology.
Explain string and vector representations of key sequences.
* keymaps.texi (Changing Key Bindings):
2006-05-15 Oliver Scholz <epameinondas@gmx.de> (tiny change)
- * nonascii.texi (Explicit Encoding): Fix
- typo (encoding<->decoding).
+ * nonascii.texi (Explicit Encoding):
+ Fix typo (encoding<->decoding).
2006-05-14 Richard Stallman <rms@gnu.org>
2006-05-09 Richard Stallman <rms@gnu.org>
- * variables.texi (File Local Variables): Document
- safe-local-eval-forms and safe-local-eval-function.
+ * variables.texi (File Local Variables):
+ Document safe-local-eval-forms and safe-local-eval-function.
2006-05-07 Kim F. Storm <storm@cua.dk>
2005-12-03 Eli Zaretskii <eliz@gnu.org>
- * hooks.texi (Standard Hooks): Add index entries. Mention
- `compilation-finish-functions'.
+ * hooks.texi (Standard Hooks): Add index entries.
+ Mention `compilation-finish-functions'.
2005-11-27 Richard M. Stallman <rms@gnu.org>
buffer-local.
(Undo): Note that buffer-undo-list is buffer-local.
- * windows.texi (Buffers and Windows): Document
- buffer-display-count.
+ * windows.texi (Buffers and Windows):
+ Document buffer-display-count.
2005-09-06 Richard M. Stallman <rms@gnu.org>
* display.texi (Displaying Messages): New node, with most
of what was in The Echo Area.
- (Progress): Moved under The Echo Area.
+ (Progress): Move under The Echo Area.
(Logging Messages): New node with new text.
(Echo Area Customization): New node, the rest of what was
in The Echo Area. Document message-truncate-lines with @defvar.
(Scroll Bars): Add scroll-bar-mode and scroll-bar-width.
(Usual Display): Move tab-width up.
- * customize.texi (Variable Definitions): Replace
- show-paren-mode example with tooltip-mode.
+ * customize.texi (Variable Definitions):
+ Replace show-paren-mode example with tooltip-mode.
(Simple Types, Composite Types, Defining New Types):
Minor cleanups.
(Display Fringe Bitmaps): New node.
(Images): Add 'Image Slices' to menu.
(Image Descriptors): Add `:pointer' and `:map' properties.
- (Showing Images): Add slice arg to `insert-image'. Add
- 'insert-sliced-image'.
+ (Showing Images): Add slice arg to `insert-image'.
+ Add 'insert-sliced-image'.
2004-09-20 Richard M. Stallman <rms@gnu.org>
2004-09-07 Luc Teirlinck <teirllm@auburn.edu>
- * locals.texi (Standard Buffer-Local Variables): Add
- `buffer-auto-save-file-format'.
+ * locals.texi (Standard Buffer-Local Variables):
+ Add `buffer-auto-save-file-format'.
* internals.texi (Buffer Internals): Describe new
auto_save_file_format field of the buffer structure.
* files.texi (Format Conversion): `auto-save-file-format' has been
2004-04-05 Jesper Harder <harder@ifa.au.dk>
- * variables.texi (Variable Aliases): Mention
- cyclic-variable-indirection.
+ * variables.texi (Variable Aliases):
+ Mention cyclic-variable-indirection.
* errors.texi (Standard Errors): Ditto.
2004-02-07 Jan Djärv <jan.h.d@swipnet.se>
- * positions.texi (Text Lines): Added missing end defun.
+ * positions.texi (Text Lines): Add missing end defun.
2004-02-07 Kim F. Storm <storm@cua.dk>
read-minibuffer.
(Minibuffer History): Clarify description of cons values for
HISTORY arguments.
- (Basic Completion): Various corrections and clarifications. Add
- completion-regexp-list.
+ (Basic Completion): Various corrections and clarifications.
+ Add completion-regexp-list.
(Minibuffer Completion): Correct and clarify description of
completing-read.
- (Completion Commands): Mention Partial Completion mode. Various
- other minor changes.
+ (Completion Commands): Mention Partial Completion mode.
+ Various other minor changes.
(High-Level Completion): Various corrections and clarifications.
(Reading File Names): Ditto.
(Minibuffer Misc): Ditto.
* functions.texi: Various small changes in addition to the
following.
- (What Is a Function): `functionp' returns nil for macros. Clarify
- behavior of this and following functions for symbol arguments.
+ (What Is a Function): `functionp' returns nil for macros.
+ Clarify behavior of this and following functions for symbol arguments.
(Function Documentation): Add `\' in front of (fn @var{arglist})
and explain why.
(Defining Functions): Mention DOCSTRING argument to `defalias'.
2003-01-31 Joe Buehler <jhpb@draco.hekimian.com>
- * os.texi (System Environment): Added cygwin system-type.
+ * os.texi (System Environment): Add cygwin system-type.
2003-01-25 Richard M. Stallman <rms@gnu.org>
* README: Target for Info file is `make info'.
- * files.texi (File Name Components): Fixed typos in
+ * files.texi (File Name Components): Fix typos in
`file-name-sans-extension'.
(Magic File Names): Complete list of operations for magic file
name handlers.
2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk>
- * customize.texi (Splicing into Lists): Fixed example.
+ * customize.texi (Splicing into Lists): Fix example.
Reported by Fabrice Bauzac <fabrice.bauzac@wanadoo.fr>.
2002-06-17 Juanma Barranquero <lektu@terra.es>
2001-11-17 Eli Zaretskii <eliz@is.elta.co.il>
- * permute-index: Don't depend on csh-specific features. Replace
- the interpreter name with /bin/sh.
+ * permute-index: Don't depend on csh-specific features.
+ Replace the interpreter name with /bin/sh.
* two-volume-cross-refs.txt: New file.
* two.el: New file.
* numbers.texi (Integer Basics): Document CL style read syntax for
integers in bases other than 10.
- * positions.texi (List Motion): Document
- open-paren-in-column-0-is-defun-start.
+ * positions.texi (List Motion):
+ Document open-paren-in-column-0-is-defun-start.
* lists.texi (Sets And Lists): Document member-ignore-case.
1995-06-19 Richard Stallman <rms@mole.gnu.ai.mit.edu>
* Makefile (VERSION): Update version number.
- (maintainer-clean): Renamed from realclean.
+ (maintainer-clean): Rename from realclean.
1995-06-07 Karl Heuer <kwzh@nutrimat.gnu.ai.mit.edu>
1991-11-26 Richard Stallman (rms@mole.gnu.ai.mit.edu)
- * Makefile (srcs): Added index.perm.
+ * Makefile (srcs): Add index.perm.
(elisp.dvi): Remove erroneous shell comment.
Expect output of permute-index in permuted.fns.
Save old elisp.aux in elisp.oaux.
- (clean): Added index.texi to be deleted.
+ (clean): Add index.texi to be deleted.
1990-08-11 Richard Stallman (rms@sugar-bombs.ai.mit.edu)
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
-* Imenu:: How a mode can provide a menu
+* Imenu:: How a mode can provide a menu
of definitions in the buffer.
-* Font Lock Mode:: How modes can highlight text according to syntax.
-* Desktop Save Mode:: How modes can have buffer state saved between
+* Font Lock Mode:: How modes can highlight text according to syntax.
+* Auto-Indentation:: How to teach Emacs to indent for a major mode.
+* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
@end menu
programming language, indentation of text according to structure is
probably useful. So the mode should set @code{indent-line-function}
to a suitable function, and probably customize other variables
-for indentation.
+for indentation. @xref{Auto-Indentation}.
@item
@cindex keymaps in modes
reasonably fast.
@end defvar
+@node Auto-Indentation
+@section Auto-indention of code
+
+For programming languages, an important feature of a major mode is to
+provide automatic indentation. This is controlled in Emacs by
+@code{indent-line-function} (@pxref{Mode-Specific Indent}).
+Writing a good indentation function can be difficult and to a large
+extent it is still a black art.
+
+Many major mode authors will start by writing a simple indentation
+function that works for simple cases, for example by comparing with the
+indentation of the previous text line. For most programming languages
+that are not really line-based, this tends to scale very poorly:
+improving such a function to let it handle more diverse situations tends
+to become more and more difficult, resulting in the end with a large,
+complex, unmaintainable indentation function which nobody dares to touch.
+
+A good indentation function will usually need to actually parse the
+text, according to the syntax of the language. Luckily, it is not
+necessary to parse the text in as much detail as would be needed
+for a compiler, but on the other hand, the parser embedded in the
+indentation code will want to be somewhat friendly to syntactically
+incorrect code.
+
+Good maintainable indentation functions usually fall into 2 categories:
+either parsing forward from some ``safe'' starting point until the
+position of interest, or parsing backward from the position of interest.
+Neither of the two is a clearly better choice than the other: parsing
+backward is often more difficult than parsing forward because
+programming languages are designed to be parsed forward, but for the
+purpose of indentation it has the advantage of not needing to
+guess a ``safe'' starting point, and it generally enjoys the property
+that only a minimum of text will be analyzed to decide the indentation
+of a line, so indentation will tend to be unaffected by syntax errors in
+some earlier unrelated piece of code. Parsing forward on the other hand
+is usually easier and has the advantage of making it possible to
+reindent efficiently a whole region at a time, with a single parse.
+
+Rather than write your own indentation function from scratch, it is
+often preferable to try and reuse some existing ones or to rely
+on a generic indentation engine. There are sadly few such
+engines. The CC-mode indentation code (used with C, C++, Java, Awk
+and a few other such modes) has been made more generic over the years,
+so if your language seems somewhat similar to one of those languages,
+you might try to use that engine. @c FIXME: documentation?
+Another one is SMIE which takes an approach in the spirit
+of Lisp sexps and adapts it to non-Lisp languages.
+
+@menu
+* SMIE:: A simple minded indentation engine
+@end menu
+
+@node SMIE
+@subsection Simple Minded Indentation Engine
+
+SMIE is a package that provides a generic navigation and indentation
+engine. Based on a very simple parser using an ``operator precedence
+grammar'', it lets major modes extend the sexp-based navigation of Lisp
+to non-Lisp languages as well as provide a simple to use but reliable
+auto-indentation.
+
+Operator precedence grammar is a very primitive technology for parsing
+compared to some of the more common techniques used in compilers.
+It has the following characteristics: its parsing power is very limited,
+and it is largely unable to detect syntax errors, but it has the
+advantage of being algorithmically efficient and able to parse forward
+just as well as backward. In practice that means that SMIE can use it
+for indentation based on backward parsing, that it can provide both
+@code{forward-sexp} and @code{backward-sexp} functionality, and that it
+will naturally work on syntactically incorrect code without any extra
+effort. The downside is that it also means that most programming
+languages cannot be parsed correctly using SMIE, at least not without
+resorting to some special tricks (@pxref{SMIE Tricks}).
+
+@menu
+* SMIE setup:: SMIE setup and features
+* Operator Precedence Grammars:: A very simple parsing technique
+* SMIE Grammar:: Defining the grammar of a language
+* SMIE Lexer:: Defining tokens
+* SMIE Tricks:: Working around the parser's limitations
+* SMIE Indentation:: Specifying indentation rules
+* SMIE Indentation Helpers:: Helper functions for indentation rules
+* SMIE Indentation Example:: Sample indentation rules
+@end menu
+
+@node SMIE setup
+@subsubsection SMIE Setup and Features
+
+SMIE is meant to be a one-stop shop for structural navigation and
+various other features which rely on the syntactic structure of code, in
+particular automatic indentation. The main entry point is
+@code{smie-setup} which is a function typically called while setting
+up a major mode.
+
+@defun smie-setup grammar rules-function &rest keywords
+Setup SMIE navigation and indentation.
+@var{grammar} is a grammar table generated by @code{smie-prec2->grammar}.
+@var{rules-function} is a set of indentation rules for use on
+@code{smie-rules-function}.
+@var{keywords} are additional arguments, which can include the following
+keywords:
+@itemize
+@item
+@code{:forward-token} @var{fun}: Specify the forward lexer to use.
+@item
+@code{:backward-token} @var{fun}: Specify the backward lexer to use.
+@end itemize
+@end defun
+
+Calling this function is sufficient to make commands such as
+@code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be
+able to properly handle structural elements other than just the paired
+parentheses already handled by syntax tables. For example, if the
+provided grammar is precise enough, @code{transpose-sexps} can correctly
+transpose the two arguments of a @code{+} operator, taking into account
+the precedence rules of the language.
+
+Calling `smie-setup' is also sufficient to make TAB indentation work in
+the expected way, and provides some commands that you can bind in the
+major mode keymap.
+
+@deffn Command smie-close-block
+This command closes the most recently opened (and not yet closed) block.
+@end deffn
+
+@deffn Command smie-down-list &optional arg
+This command is like @code{down-list} but it also pays attention to
+nesting of tokens other than parentheses, such as @code{begin...end}.
+@end deffn
+
+@node Operator Precedence Grammars
+@subsubsection Operator Precedence Grammars
+
+SMIE's precedence grammars simply give to each token a pair of
+precedences: the left-precedence and the right-precedence. We say
+@code{T1 < T2} if the right-precedence of token @code{T1} is less than
+the left-precedence of token @code{T2}. A good way to read this
+@code{<} is as a kind of parenthesis: if we find @code{... T1 something
+T2 ...} then that should be parsed as @code{... T1 (something T2 ...}
+rather than as @code{... T1 something) T2 ...}. The latter
+interpretation would be the case if we had @code{T1 > T2}. If we have
+@code{T1 = T2}, it means that token T2 follows token T1 in the same
+syntactic construction, so typically we have @code{"begin" = "end"}.
+Such pairs of precedences are sufficient to express left-associativity
+or right-associativity of infix operators, nesting of tokens like
+parentheses and many other cases.
+
+@c ¡Let's leave this undocumented to leave it more open for change!
+@c @defvar smie-grammar
+@c The value of this variable is an alist specifying the left and right
+@c precedence of each token. It is meant to be initialized by using one of
+@c the functions below.
+@c @end defvar
+
+@defun smie-prec2->grammar table
+This function takes a @emph{prec2} grammar @var{table} and returns an
+alist suitable for use in @code{smie-setup}. The @emph{prec2}
+@var{table} is itself meant to be built by one of the functions below.
+@end defun
+
+@defun smie-merge-prec2s &rest tables
+This function takes several @emph{prec2} @var{tables} and merges them
+into a new @emph{prec2} table.
+@end defun
+
+@defun smie-precs->prec2 precs
+This function builds a @emph{prec2} table from a table of precedences
+@var{precs}. @var{precs} should be a list, sorted by precedence (for
+example @code{"+"} will come before @code{"*"}), of elements of the form
+@code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that
+acts as an operator; @var{assoc} is their associativity, which can be
+either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}.
+All operators in a given element share the same precedence level
+and associativity.
+@end defun
+
+@defun smie-bnf->prec2 bnf &rest resolvers
+This function lets you specify the grammar using a BNF notation.
+It accepts a @var{bnf} description of the grammar along with a set of
+conflict resolution rules @var{resolvers}, and
+returns a @emph{prec2} table.
+
+@var{bnf} is a list of nonterminal definitions of the form
+@code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs}
+is a (non-empty) list of terminals (aka tokens) or non-terminals.
+
+Not all grammars are accepted:
+@itemize
+@item
+An @var{rhs} cannot be an empty list (an empty list is never needed,
+since SMIE allows all non-terminals to match the empty string anyway).
+@item
+An @var{rhs} cannot have 2 consecutive non-terminals: each pair of
+non-terminals needs to be separated by a terminal (aka token).
+This is a fundamental limitation of operator precedence grammars.
+@end itemize
+
+Additionally, conflicts can occur:
+@itemize
+@item
+The returned @emph{prec2} table holds constraints between pairs of tokens, and
+for any given pair only one constraint can be present: T1 < T2,
+T1 = T2, or T1 > T2.
+@item
+A token can be an @code{opener} (something similar to an open-paren),
+a @code{closer} (like a close-paren), or @code{neither} of the two
+(e.g. an infix operator, or an inner token like @code{"else"}).
+@end itemize
+
+Precedence conflicts can be resolved via @var{resolvers}, which
+is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for
+each precedence conflict, if those @code{precs} tables
+specify a particular constraint, then the conflict is resolved by using
+this constraint instead, else a conflict is reported and one of the
+conflicting constraints is picked arbitrarily and the others are
+simply ignored.
+@end defun
+
+@node SMIE Grammar
+@subsubsection Defining the Grammar of a Language
+
+The usual way to define the SMIE grammar of a language is by
+defining a new global variable that holds the precedence table by
+giving a set of BNF rules.
+For example, the grammar definition for a small Pascal-like language
+could look like:
+@example
+@group
+(require 'smie)
+(defvar sample-smie-grammar
+ (smie-prec2->grammar
+ (smie-bnf->prec2
+@end group
+@group
+ '((id)
+ (inst ("begin" insts "end")
+ ("if" exp "then" inst "else" inst)
+ (id ":=" exp)
+ (exp))
+ (insts (insts ";" insts) (inst))
+ (exp (exp "+" exp)
+ (exp "*" exp)
+ ("(" exps ")"))
+ (exps (exps "," exps) (exp)))
+@end group
+@group
+ '((assoc ";"))
+ '((assoc ","))
+ '((assoc "+") (assoc "*")))))
+@end group
+@end example
+
+@noindent
+A few things to note:
+
+@itemize
+@item
+The above grammar does not explicitly mention the syntax of function
+calls: SMIE will automatically allow any sequence of sexps, such as
+identifiers, balanced parentheses, or @code{begin ... end} blocks
+to appear anywhere anyway.
+@item
+The grammar category @code{id} has no right hand side: this does not
+mean that it can match only the empty string, since as mentioned any
+sequence of sexps can appear anywhere anyway.
+@item
+Because non terminals cannot appear consecutively in the BNF grammar, it
+is difficult to correctly handle tokens that act as terminators, so the
+above grammar treats @code{";"} as a statement @emph{separator} instead,
+which SMIE can handle very well.
+@item
+Separators used in sequences (such as @code{","} and @code{";"} above)
+are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)}
+which generate precedence conflicts which are then resolved by giving
+them an explicit @code{(assoc "separator")}.
+@item
+The @code{("(" exps ")")} rule was not needed to pair up parens, since
+SMIE will pair up any characters that are marked as having paren syntax
+in the syntax table. What this rule does instead (together with the
+definition of @code{exps}) is to make it clear that @code{","} should
+not appear outside of parentheses.
+@item
+Rather than have a single @emph{precs} table to resolve conflicts, it is
+preferable to have several tables, so as to let the BNF part of the
+grammar specify relative precedences where possible.
+@item
+Unless there is a very good reason to prefer @code{left} or
+@code{right}, it is usually preferable to mark operators as associative,
+using @code{assoc}. For that reason @code{"+"} and @code{"*"} are
+defined above as @code{assoc}, although the language defines them
+formally as left associative.
+@end itemize
+
+@node SMIE Lexer
+@subsubsection Defining Tokens
+
+SMIE comes with a predefined lexical analyzer which uses syntax tables
+in the following way: any sequence of characters that have word or
+symbol syntax is considered a token, and so is any sequence of
+characters that have punctuation syntax. This default lexer is
+often a good starting point but is rarely actually correct for any given
+language. For example, it will consider @code{"2,+3"} to be composed
+of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}.
+
+To describe the lexing rules of your language to SMIE, you need
+2 functions, one to fetch the next token, and another to fetch the
+previous token. Those functions will usually first skip whitespace and
+comments and then look at the next chunk of text to see if it
+is a special token. If so it should skip the token and
+return a description of this token. Usually this is simply the string
+extracted from the buffer, but it can be anything you want.
+For example:
+@example
+@group
+(defvar sample-keywords-regexp
+ (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "=")))
+@end group
+@group
+(defun sample-smie-forward-token ()
+ (forward-comment (point-max))
+ (cond
+ ((looking-at sample-keywords-regexp)
+ (goto-char (match-end 0))
+ (match-string-no-properties 0))
+ (t (buffer-substring-no-properties
+ (point)
+ (progn (skip-syntax-forward "w_")
+ (point))))))
+@end group
+@group
+(defun sample-smie-backward-token ()
+ (forward-comment (- (point)))
+ (cond
+ ((looking-back sample-keywords-regexp (- (point) 2) t)
+ (goto-char (match-beginning 0))
+ (match-string-no-properties 0))
+ (t (buffer-substring-no-properties
+ (point)
+ (progn (skip-syntax-backward "w_")
+ (point))))))
+@end group
+@end example
+
+Notice how those lexers return the empty string when in front of
+parentheses. This is because SMIE automatically takes care of the
+parentheses defined in the syntax table. More specifically if the lexer
+returns nil or an empty string, SMIE tries to handle the corresponding
+text as a sexp according to syntax tables.
+
+@node SMIE Tricks
+@subsubsection Living With a Weak Parser
+
+The parsing technique used by SMIE does not allow tokens to behave
+differently in different contexts. For most programming languages, this
+manifests itself by precedence conflicts when converting the
+BNF grammar.
+
+Sometimes, those conflicts can be worked around by expressing the
+grammar slightly differently. For example, for Modula-2 it might seem
+natural to have a BNF grammar that looks like this:
+
+@example
+ ...
+ (inst ("IF" exp "THEN" insts "ELSE" insts "END")
+ ("CASE" exp "OF" cases "END")
+ ...)
+ (cases (cases "|" cases) (caselabel ":" insts) ("ELSE" insts))
+ ...
+@end example
+
+But this will create conflicts for @code{"ELSE"}: on the one hand, the
+IF rule implies (among many other things) that @code{"ELSE" = "END"};
+but on the other hand, since @code{"ELSE"} appears within @code{cases},
+which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}.
+We can solve the conflict either by using:
+@example
+ ...
+ (inst ("IF" exp "THEN" insts "ELSE" insts "END")
+ ("CASE" exp "OF" cases "END")
+ ("CASE" exp "OF" cases "ELSE" insts "END")
+ ...)
+ (cases (cases "|" cases) (caselabel ":" insts))
+ ...
+@end example
+or
+@example
+ ...
+ (inst ("IF" exp "THEN" else "END")
+ ("CASE" exp "OF" cases "END")
+ ...)
+ (else (insts "ELSE" insts))
+ (cases (cases "|" cases) (caselabel ":" insts) (else))
+ ...
+@end example
+
+Reworking the grammar to try and solve conflicts has its downsides, tho,
+because SMIE assumes that the grammar reflects the logical structure of
+the code, so it is preferable to keep the BNF closer to the intended
+abstract syntax tree.
+
+Other times, after careful consideration you may conclude that those
+conflicts are not serious and simply resolve them via the
+@var{resolvers} argument of @code{smie-bnf->prec2}. Usually this is
+because the grammar is simply ambiguous: the conflict does not affect
+the set of programs described by the grammar, but only the way those
+programs are parsed. This is typically the case for separators and
+associative infix operators, where you want to add a resolver like
+@code{'((assoc "|"))}. Another case where this can happen is for the
+classic @emph{dangling else} problem, where you will use @code{'((assoc
+"else" "then"))}. It can also happen for cases where the conflict is
+real and cannot really be resolved, but it is unlikely to pose a problem
+in practice.
+
+Finally, in many cases some conflicts will remain despite all efforts to
+restructure the grammar. Do not despair: while the parser cannot be
+made more clever, you can make the lexer as smart as you want. So, the
+solution is then to look at the tokens involved in the conflict and to
+split one of those tokens into 2 (or more) different tokens. E.g. if
+the grammar needs to distinguish between two incompatible uses of the
+token @code{"begin"}, make the lexer return different tokens (say
+@code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of
+@code{"begin"} it finds. This pushes the work of distinguishing the
+different cases to the lexer, which will thus have to look at the
+surrounding text to find ad-hoc clues.
+
+@node SMIE Indentation
+@subsubsection Specifying Indentation Rules
+
+Based on the provided grammar, SMIE will be able to provide automatic
+indentation without any extra effort. But in practice, this default
+indentation style will probably not be good enough. You will want to
+tweak it in many different cases.
+
+SMIE indentation is based on the idea that indentation rules should be
+as local as possible. To this end, it relies on the idea of
+@emph{virtual} indentation, which is the indentation that a particular
+program point would have if it were at the beginning of a line.
+Of course, if that program point is indeed at the beginning of a line,
+its virtual indentation is its current indentation. But if not, then
+SMIE uses the indentation algorithm to compute the virtual indentation
+of that point. Now in practice, the virtual indentation of a program
+point does not have to be identical to the indentation it would have if
+we inserted a newline before it. To see how this works, the SMIE rule
+for indentation after a @code{@{} in C does not care whether the
+@code{@{} is standing on a line of its own or is at the end of the
+preceding line. Instead, these different cases are handled in the
+indentation rule that decides how to indent before a @code{@{}.
+
+Another important concept is the notion of @emph{parent}: The
+@emph{parent} of a token, is the head token of the nearest enclosing
+syntactic construct. For example, the parent of an @code{else} is the
+@code{if} to which it belongs, and the parent of an @code{if}, in turn,
+is the lead token of the surrounding construct. The command
+@code{backward-sexp} jumps from a token to its parent, but there are
+some caveats: for @emph{openers} (tokens which start a construct, like
+@code{if}), you need to start with point before the token, while for
+others you need to start with point after the token.
+@code{backward-sexp} stops with point before the parent token if that is
+the @emph{opener} of the token of interest, and otherwise it stops with
+point after the parent token.
+
+SMIE indentation rules are specified using a function that takes two
+arguments @var{method} and @var{arg} where the meaning of @var{arg} and the
+expected return value depend on @var{method}.
+
+@var{method} can be:
+@itemize
+@item
+@code{:after}, in which case @var{arg} is a token and the function
+should return the @var{offset} to use for indentation after @var{arg}.
+@item
+@code{:before}, in which case @var{arg} is a token and the function
+should return the @var{offset} to use to indent @var{arg} itself.
+@item
+@code{:elem}, in which case the function should return either the offset
+to use to indent function arguments (if @var{arg} is the symbol
+@code{arg}) or the basic indentation step (if @var{arg} is the symbol
+@code{basic}).
+@item
+@code{:list-intro}, in which case @var{arg} is a token and the function
+should return non-@code{nil} if the token is followed by a list of
+expressions (not separated by any token) rather than an expression.
+@end itemize
+
+When @var{arg} is a token, the function is called with point just before
+that token. A return value of nil always means to fallback on the
+default behavior, so the function should return nil for arguments it
+does not expect.
+
+@var{offset} can be:
+@itemize
+@item
+@code{nil}: use the default indentation rule.
+@item
+@code{(column . @var{column})}: indent to column @var{column}.
+@item
+@var{number}: offset by @var{number}, relative to a base token which is
+the current token for @code{:after} and its parent for @code{:before}.
+@end itemize
+
+@node SMIE Indentation Helpers
+@subsubsection Helper Functions for Indentation Rules
+
+SMIE provides various functions designed specifically for use in the
+indentation rules function (several of those functions break if used in
+another context). These functions all start with the prefix
+@code{smie-rule-}.
+
+@defun smie-rule-bolp
+Return non-@code{nil} if the current token is the first on the line.
+@end defun
+
+@defun smie-rule-hanging-p
+Return non-@code{nil} if the current token is @emph{hanging}.
+A token is @emph{hanging} if it is the last token on the line
+and if it is preceded by other tokens: a lone token on a line is not
+hanging.
+@end defun
+
+@defun smie-rule-next-p &rest tokens
+Return non-@code{nil} if the next token is among @var{tokens}.
+@end defun
+
+@defun smie-rule-prev-p &rest tokens
+Return non-@code{nil} if the previous token is among @var{tokens}.
+@end defun
+
+@defun smie-rule-parent-p &rest parents
+Return non-@code{nil} if the current token's parent is among @var{parents}.
+@end defun
+
+@defun smie-rule-sibling-p
+Return non-nil if the current token's parent is actually a sibling.
+This is the case for example when the parent of a @code{","} is just the
+previous @code{","}.
+@end defun
+
+@defun smie-rule-parent &optional offset
+Return the proper offset to align the current token with the parent.
+If non-@code{nil}, @var{offset} should be an integer giving an
+additional offset to apply.
+@end defun
+
+@defun smie-rule-separator method
+Indent current token as a @emph{separator}.
+
+By @emph{separator}, we mean here a token whose sole purpose is to
+separate various elements within some enclosing syntactic construct, and
+which does not have any semantic significance in itself (i.e. it would
+typically not exist as a node in an abstract syntax tree).
+
+Such a token is expected to have an associative syntax and be closely
+tied to its syntactic parent. Typical examples are @code{","} in lists
+of arguments (enclosed inside parentheses), or @code{";"} in sequences
+of instructions (enclosed in a @code{@{...@}} or @code{begin...end}
+block).
+
+@var{method} should be the method name that was passed to
+`smie-rules-function'.
+@end defun
+
+@node SMIE Indentation Example
+@subsubsection Sample Indentation Rules
+
+Here is an example of an indentation function:
+
+@example
+(eval-when-compile (require 'cl)) ;For the `case' macro.
+(defun sample-smie-rules (kind token)
+ (case kind
+ (:elem (case token
+ (basic sample-indent-basic)))
+ (:after
+ (cond
+ ((equal token ",") (smie-rule-separator kind))
+ ((equal token ":=") sample-indent-basic)))
+ (:before
+ (cond
+ ((equal token ",") (smie-rule-separator kind))
+ ((member token '("begin" "(" "@{"))
+ (if (smie-rule-hanging-p) (smie-rule-parent)))
+ ((equal token "if")
+ (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
+ (smie-rule-parent)))))))
+@end example
+
+@noindent
+A few things to note:
+
+@itemize
+@item
+The first case indicates the basic indentation increment to use.
+If @code{sample-indent-basic} is nil, then SMIE uses the global
+setting @code{smie-indent-basic}. The major mode could have set
+@code{smie-indent-basic} buffer-locally instead, but that
+is discouraged.
+
+@item
+The two (identical) rules for the token @code{","} make SMIE try to be
+more clever when the comma separator is placed at the beginning of
+lines. It tries to outdent the separator so as to align the code after
+the comma; for example:
+
+@example
+x = longfunctionname (
+ arg1
+ , arg2
+ );
+@end example
+
+@item
+The rule for indentation after @code{":="} exists because otherwise
+SMIE would treat @code{":="} as an infix operator and would align the
+right argument with the left one.
+
+@item
+The rule for indentation before @code{"begin"} is an example of the use
+of virtual indentation: This rule is used only when @code{"begin"} is
+hanging, which can happen only when @code{"begin"} is not at the
+beginning of a line. So this is not used when indenting
+@code{"begin"} itself but only when indenting something relative to this
+@code{"begin"}. Concretely, this rule changes the indentation from:
+
+@example
+ if x > 0 then begin
+ dosomething(x);
+ end
+@end example
+to
+@example
+ if x > 0 then begin
+ dosomething(x);
+ end
+@end example
+
+@item
+The rule for indentation before @code{"if"} is similar to the one for
+@code{"begin"}, but where the purpose is to treat @code{"else if"}
+as a single unit, so as to align a sequence of tests rather than indent
+each test further to the right. This function does this only in the
+case where the @code{"if"} is not placed on a separate line, hence the
+@code{smie-rule-bolp} test.
+
+If we know that the @code{"else"} is always aligned with its @code{"if"}
+and is always at the beginning of a line, we can use a more efficient
+rule:
+@example
+((equal token "if")
+ (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
+ (save-excursion
+ (sample-smie-backward-token) ;Jump before the "else".
+ (cons 'column (current-column)))))
+@end example
+
+The advantage of this formulation is that it reuses the indentation of
+the previous @code{"else"}, rather than going all the way back to the
+first @code{"if"} of the sequence.
+@end itemize
+
@node Desktop Save Mode
@section Desktop Save Mode
@cindex desktop save mode