From: Lars Ingebrigtsen Date: Wed, 9 Oct 2019 18:07:56 +0000 (+0200) Subject: Move the "Skeleton Language" node to later in the manual X-Git-Tag: emacs-27.0.90~1181 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b16f19626c468647de570e43c9b18db5bd5e7638;p=emacs.git Move the "Skeleton Language" node to later in the manual * doc/misc/autotype.texi (Skeleton Language): Move this low-level node to after the more user-facing nodes (bug#20780). --- diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index a354383cc9f..89cba183a25 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -86,7 +86,6 @@ completions and expansions of text at point. * Using Skeletons:: How to insert a skeleton into your text. * Wrapping Skeletons:: Putting existing text within a skeleton. * Skeletons as Abbrevs:: An alternative for issuing skeleton commands. -* Skeleton Language:: Making skeleton commands insert what you want. * Inserting Pairs:: Typing one character and getting another after point. * Autoinserting:: Filling up empty files as soon as you visit them. @@ -96,6 +95,7 @@ completions and expansions of text at point. * QuickURL:: Inserting URLs based on text at point. * Tempo:: Flexible template insertion. * Hippie Expand:: Expansion of text trying various methods. +* Skeleton Language:: Making skeleton commands insert what you want. * GNU Free Documentation License:: The license for this documentation. * Concept Index:: @@ -209,105 +209,6 @@ have been omitted.) -@node Skeleton Language -@chapter Skeleton Language -@cindex skeleton language - -@findex skeleton-insert - Skeletons are a shorthand extension to the Lisp language, where various -atoms directly perform either actions on the current buffer or rudimentary -flow control mechanisms. Skeletons are interpreted by the function -@code{skeleton-insert}. - - A skeleton is a list starting with an interactor, which is usually a -prompt-string, or @code{nil} when not needed, but can also be a Lisp -expression for complex read functions or for returning some calculated value. -The rest of the list are any number of elements as described in the following -table: - -@table @asis -@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} -@vindex skeleton-transformation -Insert string or character. Literal strings and characters are passed through -@code{skeleton-transformation} when that is non-@code{nil}. -@item @code{?\n} -@c ??? something seems very wrong here. -Insert a newline and align under current line, but not if this is the -last element of a skeleton and the newline would be inserted at end of -line, or this is the first element and the newline would be inserted -at beginning of line. Use newline character @code{?\n} to prevent -alignment. Use @code{"\n"} as the first or last string element of a -skeleton to insert a newline unconditionally. -@item @code{_} -Interesting point. When wrapping skeletons around successive regions, they are -put at these places. Point is left at first @code{_} where nothing is -wrapped. -@item @code{-} -Interesting point with no inter-region interaction; overrides -interesting point set by @code{_}. -@item @code{>} -Indent line according to major mode. When following element is @code{_}, and -there is an interregion that will be wrapped here, indent that interregion. -@item @code{&} -Logical and. If preceding element moved point, i.e., usually inserted -something, do following element. -@item @code{|} -Logical xor. If preceding element didn't move point, i.e., usually inserted -nothing, do following element. -@item @code{@@} -Add position to @code{skeleton-positions}. -@item @code{-@var{number}} -Delete preceding number characters. Depends on value of -@code{skeleton-untabify}. -@item @code{()} or @code{nil} -Ignored. -@item @var{lisp-expression} -Evaluated, and the return value is again interpreted as a skeleton element. -@item @code{str} -A special variable that, when evaluated the first time, usually prompts -for input according to the skeleton's interactor. It is then set to the -return value resulting from the interactor. Each subskeleton has its local -copy of this variable. -@item @code{v1}, @code{v2} -Skeleton-local user variables. -@item @code{'@var{expression}} -Evaluate following Lisp expression for its side-effect, but prevent it from -being interpreted as a skeleton element. -@item @var{skeleton} -Subskeletons are inserted recursively, not once, but as often as the user -enters something at the subskeletons interactor. Thus there must be a -@code{str} in the subskeleton. They can also be used non-interactively, when -prompt is a lisp-expression that returns successive list-elements. -@item @code{resume:} -Ignored. Execution resumes here if the user quits during skeleton -interpretation. -@item @code{help} -Help form during interaction with the user or @code{nil}. -@item @code{input} -Initial input (a string or a cons with index) while reading the input. -@item @code{quit} -A constant which is non-@code{nil} when the @code{resume:} section was entered -because the user quit. -@end table - -@findex skeleton-further-elements - Some modes also use other skeleton elements they themselves defined. For -example in shell script mode's skeletons you will find @code{<} which does a -rigid indentation backwards, or in CC mode's skeletons you find the -self-inserting elements @code{@{} and @code{@}}. These are defined by the -buffer-local variable @code{skeleton-further-elements} which is a list of -variables bound while interpreting a skeleton. - -@findex define-skeleton - The macro @code{define-skeleton} defines a command for interpreting a -skeleton. The first argument is the command name, the second is a -documentation string, and the rest is an interactor and any number of skeleton -elements together forming a skeleton. This skeleton is assigned to a variable -of the same name as the command and can thus be overridden from your -@file{~/.emacs} file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). - - - @node Inserting Pairs @chapter Inserting Matching Pairs of Characters @cindex inserting pairs @@ -656,6 +557,104 @@ Typically you would bind @code{hippie-expand} to @kbd{M-/} with @code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one of the expansion possibilities. +@node Skeleton Language +@chapter Skeleton Language +@cindex skeleton language + +@findex skeleton-insert + Skeletons are a shorthand extension to the Lisp language, where various +atoms directly perform either actions on the current buffer or rudimentary +flow control mechanisms. Skeletons are interpreted by the function +@code{skeleton-insert}. + + A skeleton is a list starting with an interactor, which is usually a +prompt-string, or @code{nil} when not needed, but can also be a Lisp +expression for complex read functions or for returning some calculated value. +The rest of the list are any number of elements as described in the following +table: + +@table @asis +@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} +@vindex skeleton-transformation +Insert string or character. Literal strings and characters are passed through +@code{skeleton-transformation} when that is non-@code{nil}. +@item @code{?\n} +@c ??? something seems very wrong here. +Insert a newline and align under current line, but not if this is the +last element of a skeleton and the newline would be inserted at end of +line, or this is the first element and the newline would be inserted +at beginning of line. Use newline character @code{?\n} to prevent +alignment. Use @code{"\n"} as the first or last string element of a +skeleton to insert a newline unconditionally. +@item @code{_} +Interesting point. When wrapping skeletons around successive regions, they are +put at these places. Point is left at first @code{_} where nothing is +wrapped. +@item @code{-} +Interesting point with no inter-region interaction; overrides +interesting point set by @code{_}. +@item @code{>} +Indent line according to major mode. When following element is @code{_}, and +there is an interregion that will be wrapped here, indent that interregion. +@item @code{&} +Logical and. If preceding element moved point, i.e., usually inserted +something, do following element. +@item @code{|} +Logical xor. If preceding element didn't move point, i.e., usually inserted +nothing, do following element. +@item @code{@@} +Add position to @code{skeleton-positions}. +@item @code{-@var{number}} +Delete preceding number characters. Depends on value of +@code{skeleton-untabify}. +@item @code{()} or @code{nil} +Ignored. +@item @var{lisp-expression} +Evaluated, and the return value is again interpreted as a skeleton element. +@item @code{str} +A special variable that, when evaluated the first time, usually prompts +for input according to the skeleton's interactor. It is then set to the +return value resulting from the interactor. Each subskeleton has its local +copy of this variable. +@item @code{v1}, @code{v2} +Skeleton-local user variables. +@item @code{'@var{expression}} +Evaluate following Lisp expression for its side-effect, but prevent it from +being interpreted as a skeleton element. +@item @var{skeleton} +Subskeletons are inserted recursively, not once, but as often as the user +enters something at the subskeletons interactor. Thus there must be a +@code{str} in the subskeleton. They can also be used non-interactively, when +prompt is a lisp-expression that returns successive list-elements. +@item @code{resume:} +Ignored. Execution resumes here if the user quits during skeleton +interpretation. +@item @code{help} +Help form during interaction with the user or @code{nil}. +@item @code{input} +Initial input (a string or a cons with index) while reading the input. +@item @code{quit} +A constant which is non-@code{nil} when the @code{resume:} section was entered +because the user quit. +@end table + +@findex skeleton-further-elements + Some modes also use other skeleton elements they themselves defined. For +example in shell script mode's skeletons you will find @code{<} which does a +rigid indentation backwards, or in CC mode's skeletons you find the +self-inserting elements @code{@{} and @code{@}}. These are defined by the +buffer-local variable @code{skeleton-further-elements} which is a list of +variables bound while interpreting a skeleton. + +@findex define-skeleton + The macro @code{define-skeleton} defines a command for interpreting a +skeleton. The first argument is the command name, the second is a +documentation string, and the rest is an interactor and any number of skeleton +elements together forming a skeleton. This skeleton is assigned to a variable +of the same name as the command and can thus be overridden from your +@file{~/.emacs} file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). + + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi