Commit | Line | Data |
---|---|---|
4009494e GM |
1 | \input texinfo |
2 | @c This is an annex of the Emacs manual. | |
fc23fe2d | 3 | @c Author: Daniel Pfeiffer <Daniel.Pfeiffer@Informatik.START.dbp.de> |
29993416 | 4 | @setfilename ../../info/autotype.info |
4009494e GM |
5 | @c @node Autotypist, Picture, Abbrevs, Top |
6 | @c @chapter Features for Automatic Typing | |
7 | @settitle Features for Automatic Typing | |
c6ab4664 | 8 | @documentencoding UTF-8 |
4009494e GM |
9 | @c @cindex text |
10 | @c @cindex selfinserting text | |
11 | @c @cindex autotypist | |
12 | ||
13 | @copying | |
6bc383b1 | 14 | Copyright @copyright{} 1994--1995, 1999, 2001--2014 |
6bf430d1 | 15 | Free Software Foundation, Inc. |
4009494e GM |
16 | |
17 | @quotation | |
18 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 19 | under the terms of the GNU Free Documentation License, Version 1.3 or |
7b2d06e1 | 20 | any later version published by the Free Software Foundation; with no |
551a89e1 | 21 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
7b2d06e1 GM |
22 | and with the Back-Cover Texts as in (a) below. A copy of the license |
23 | is included in the section entitled ``GNU Free Documentation License''. | |
4009494e | 24 | |
6f093307 | 25 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 26 | modify this GNU manual.'' |
4009494e GM |
27 | @end quotation |
28 | @end copying | |
29 | ||
0c973505 | 30 | @dircategory Emacs misc features |
4009494e | 31 | @direntry |
f9405d87 GM |
32 | * Autotype: (autotype). Convenient features for text that you enter |
33 | frequently in Emacs. | |
4009494e GM |
34 | @end direntry |
35 | ||
36 | @titlepage | |
37 | @sp 10 | |
38 | ||
39 | @center @titlefont{Autotyping} | |
40 | @sp 2 | |
605f02ee | 41 | @center Convenient features for text that you enter frequently in Emacs |
4009494e GM |
42 | @sp 2 |
43 | @center Daniel Pfeiffer | |
44 | @center additions by Dave Love | |
45 | ||
46 | @page | |
47 | @vskip 0pt plus 1filll | |
48 | @insertcopying | |
49 | @end titlepage | |
50 | ||
5dc584b5 KB |
51 | @contents |
52 | ||
4009494e GM |
53 | @node Top |
54 | @top Autotyping | |
55 | ||
56 | Under certain circumstances you will find yourself typing similar things | |
57 | over and over again. This is especially true of form letters and programming | |
58 | language constructs. Project-specific header comments, flow-control | |
59 | constructs or magic numbers are essentially the same every time. Emacs has | |
60 | various features for doing tedious and repetitive typing chores for you | |
88edc57f | 61 | in addition to the Abbrev features (@pxref{Abbrevs,,, emacs, The GNU Emacs Manual}). |
4009494e GM |
62 | |
63 | One solution is using skeletons, flexible rules that say what to | |
64 | insert, and how to do it. Various programming language modes offer some | |
65 | ready-to-use skeletons, and you can adapt them to suit your needs or | |
66 | taste, or define new ones. | |
67 | ||
68 | Another feature is automatic insertion of what you want into empty files, | |
69 | depending on the file-name or the mode as appropriate. You can have a file or | |
70 | a skeleton inserted, or you can call a function. Then there is the | |
71 | possibility to have Un*x interpreter scripts automatically take on a magic | |
72 | number and be executable as soon as they are saved. Or you can have a | |
73 | copyright notice's year updated, if necessary, every time you save a | |
74 | file. Similarly for time stamps in the file. | |
75 | ||
76 | URLs can be inserted based on a word at point. Flexible templates can | |
77 | be defined for inserting and navigating between text more generally. A | |
78 | sort of meta-expansion facility can be used to try a set of alternative | |
79 | completions and expansions of text at point. | |
80 | ||
5dc584b5 KB |
81 | @ifnottex |
82 | @insertcopying | |
83 | @end ifnottex | |
84 | ||
4009494e GM |
85 | @menu |
86 | * Using Skeletons:: How to insert a skeleton into your text. | |
87 | * Wrapping Skeletons:: Putting existing text within a skeleton. | |
88 | * Skeletons as Abbrevs:: An alternative for issuing skeleton commands. | |
89 | * Skeleton Language:: Making skeleton commands insert what you want. | |
90 | * Inserting Pairs:: Typing one character and getting another | |
91 | after point. | |
92 | * Autoinserting:: Filling up empty files as soon as you visit them. | |
93 | * Copyrights:: Inserting and updating copyrights. | |
9360256a | 94 | * Executables:: Turning interpreter scripts into executables. |
4009494e GM |
95 | * Timestamps:: Updating dates and times in modified files. |
96 | * QuickURL:: Inserting URLs based on text at point. | |
97 | * Tempo:: Flexible template insertion. | |
98 | * Hippie Expand:: Expansion of text trying various methods. | |
99 | ||
100 | * GNU Free Documentation License:: The license for this documentation. | |
101 | * Concept Index:: | |
102 | * Command Index:: | |
103 | * Variable Index:: | |
104 | @end menu | |
105 | ||
106 | ||
4009494e GM |
107 | @node Using Skeletons |
108 | @chapter Using Skeletons | |
109 | @cindex skeletons | |
110 | @cindex using skeletons | |
111 | ||
112 | When you want Emacs to insert a form letter or a typical construct of the | |
113 | programming language you are using, skeletons are a means of accomplishing | |
114 | this. Normally skeletons each have a command of their own, that, when called, | |
115 | will insert the skeleton. These commands can be issued in the usual ways | |
88edc57f | 116 | (@pxref{Commands,,, emacs, The GNU Emacs Manual}). Modes that offer various skeletons will often |
4009494e GM |
117 | bind these to key-sequences on the @kbd{C-c} prefix, as well as having |
118 | an @cite{Insert} menu and maybe even predefined abbrevs for them | |
119 | (@pxref{Skeletons as Abbrevs}). | |
120 | ||
121 | The simplest kind of skeleton will simply insert some text indented | |
122 | according to the major mode and leave the cursor at a likely place in the | |
123 | middle. Interactive skeletons may prompt you for a string that will be part | |
124 | of the inserted text. | |
125 | ||
126 | Skeletons may ask for input several times. They even have a looping | |
127 | mechanism in which you will be asked for input as long as you are willing to | |
128 | furnish it. An example would be multiple ``else if'' conditions. You can | |
129 | recognize this situation by a prompt ending in @key{RET}, @kbd{C-g} | |
130 | or @kbd{C-h}. This | |
131 | means that entering an empty string will simply assume that you are finished. | |
132 | Typing quit on the other hand terminates the loop but also the rest of the | |
1df7defd | 133 | skeleton, e.g., an ``else'' clause is skipped. Only a syntactically necessary |
4009494e GM |
134 | termination still gets inserted. |
135 | ||
136 | ||
137 | ||
138 | @node Wrapping Skeletons | |
139 | @chapter Wrapping Skeletons Around Existing Text | |
140 | @cindex wrapping skeletons | |
141 | ||
142 | Often you will find yourself with some code that for whatever reason | |
143 | suddenly becomes conditional. Or you have written a bit of text and want to | |
144 | put it in the middle of a form letter. Skeletons provide a means for | |
145 | accomplishing this, and can even, in the case of programming languages, | |
146 | reindent the wrapped code for you. | |
147 | ||
148 | Skeleton commands take an optional numeric prefix argument | |
88edc57f | 149 | (@pxref{Arguments,,, emacs, The GNU Emacs Manual}). This is interpreted in two different ways depending |
1df7defd PE |
150 | on whether the prefix is positive, i.e., forwards oriented, or negative, |
151 | i.e., backwards oriented. | |
4009494e GM |
152 | |
153 | A positive prefix means to wrap the skeleton around that many | |
154 | following words. This is accomplished by putting the words there where | |
155 | the point is normally left after that skeleton is inserted (@pxref{Using | |
88edc57f | 156 | Skeletons}). The point (@pxref{Point,,, emacs, The GNU Emacs Manual}) is left at the next |
4009494e GM |
157 | interesting spot in the skeleton instead. |
158 | ||
e1dbe924 | 159 | A negative prefix means to do something similar with that many previously |
88edc57f | 160 | marked interregions (@pxref{Mark,,, emacs, The GNU Emacs Manual}). In the simplest case, if you type |
4009494e GM |
161 | @kbd{M--} just before issuing the skeleton command, that will wrap the |
162 | skeleton around the current region, just like a positive argument would have | |
163 | wrapped it around a number of words. | |
164 | ||
165 | Smaller negative arguments will wrap that many interregions into successive | |
166 | interesting spots within the skeleton, again leaving the point at the next one. | |
167 | We speak about interregions rather than regions here, because we treat them in | |
168 | the order they appear in the buffer, which coincides with successive regions | |
169 | only if they were marked in order. | |
170 | ||
171 | That is, if you marked in alphabetical order the points A B C [] (where [] | |
172 | represents the point) and call a skeleton command with @kbd{M-- 3}, you will | |
173 | wrap the text from A to B into the first interesting spot of the skeleton, the | |
174 | text from B to C into the next one, the text from C to the point into the | |
175 | third one, and leave the point in the fourth one. If there are less marks in | |
176 | the buffer, or if the skeleton defines less interesting points, the surplus is | |
177 | ignored. | |
178 | ||
179 | If, on the other hand, you marked in alphabetical order the points [] A C B, | |
180 | and call a skeleton command with @kbd{M-- 3}, you will wrap the text from | |
1df7defd | 181 | point to A, then the text from A to C and finally the text from C to B@. This |
4009494e GM |
182 | is done because the regions overlap and Emacs would be helplessly lost if it |
183 | tried to follow the order in which you marked these points. | |
184 | ||
185 | ||
186 | ||
187 | @node Skeletons as Abbrevs | |
188 | @chapter Skeletons as Abbrev Expansions | |
189 | @cindex skeletons as abbrevs | |
190 | ||
191 | Rather than use a key binding for every skeleton command, you can also | |
88edc57f GM |
192 | define an abbreviation (@pxref{Defining Abbrevs,,, emacs, The GNU Emacs Manual}) that will expand |
193 | (@pxref{Expanding Abbrevs,,, emacs, The GNU Emacs Manual}) into the skeleton. | |
4009494e GM |
194 | |
195 | Say you want @samp{ifst} to be an abbreviation for the C language if | |
196 | statement. You will tell Emacs that @samp{ifst} expands to the empty string | |
197 | and then calls the skeleton command. In Emacs Lisp you can say something like | |
198 | @code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit | |
199 | the output from @kbd{M-x list-abbrevs} to make it look like this: | |
200 | ||
201 | @example | |
202 | (c-mode-abbrev-table) | |
9360256a | 203 | "if" 0 "" c-if |
4009494e GM |
204 | @end example |
205 | ||
206 | @noindent | |
207 | (Some blank lines of no semantic significance, and other abbrev tables, | |
208 | have been omitted.) | |
209 | ||
210 | ||
211 | ||
212 | @node Skeleton Language | |
213 | @chapter Skeleton Language | |
214 | @cindex skeleton language | |
215 | ||
216 | @findex skeleton-insert | |
217 | Skeletons are an shorthand extension to the Lisp language, where various | |
218 | atoms directly perform either actions on the current buffer or rudimentary | |
219 | flow control mechanisms. Skeletons are interpreted by the function | |
220 | @code{skeleton-insert}. | |
221 | ||
222 | A skeleton is a list starting with an interactor, which is usually a | |
223 | prompt-string, or @code{nil} when not needed, but can also be a Lisp | |
224 | expression for complex read functions or for returning some calculated value. | |
225 | The rest of the list are any number of elements as described in the following | |
226 | table: | |
227 | ||
228 | @table @asis | |
229 | @item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} | |
230 | @vindex skeleton-transformation | |
231 | Insert string or character. Literal strings and characters are passed through | |
232 | @code{skeleton-transformation} when that is non-@code{nil}. | |
233 | @item @code{?\n} | |
234 | @c ??? something seems very wrong here. | |
8047f439 EZ |
235 | Insert a newline and align under current line, but not if this is the |
236 | last element of a skeleton and the newline would be inserted at end of | |
f3953a24 EZ |
237 | line, or this is the first element and the newline would be inserted |
238 | at beginning of line. Use newline character @code{?\n} to prevent | |
239 | alignment. Use @code{"\n"} as the first or last string element of a | |
240 | skeleton to insert a newline unconditionally. | |
4009494e GM |
241 | @item @code{_} |
242 | Interesting point. When wrapping skeletons around successive regions, they are | |
243 | put at these places. Point is left at first @code{_} where nothing is wrapped. | |
244 | @item @code{>} | |
245 | Indent line according to major mode. When following element is @code{_}, and | |
246 | there is a interregion that will be wrapped here, indent that interregion. | |
247 | @item @code{&} | |
d136f184 | 248 | Logical and. If preceding element moved point, i.e., usually inserted |
4009494e GM |
249 | something, do following element. |
250 | @item @code{|} | |
d136f184 | 251 | Logical xor. If preceding element didn't move point, i.e., usually inserted |
4009494e GM |
252 | nothing, do following element. |
253 | @item @code{-@var{number}} | |
254 | Delete preceding number characters. Depends on value of | |
255 | @code{skeleton-untabify}. | |
256 | @item @code{()} or @code{nil} | |
257 | Ignored. | |
258 | @item @var{lisp-expression} | |
259 | Evaluated, and the return value is again interpreted as a skeleton element. | |
260 | @item @code{str} | |
261 | A special variable that, when evaluated the first time, usually prompts | |
262 | for input according to the skeleton's interactor. It is then set to the | |
263 | return value resulting from the interactor. Each subskeleton has its local | |
264 | copy of this variable. | |
265 | @item @code{v1}, @code{v2} | |
266 | Skeleton-local user variables. | |
267 | @item @code{'@var{expression}} | |
268 | Evaluate following Lisp expression for its side-effect, but prevent it from | |
269 | being interpreted as a skeleton element. | |
270 | @item @var{skeleton} | |
271 | Subskeletons are inserted recursively, not once, but as often as the user | |
272 | enters something at the subskeletons interactor. Thus there must be a | |
273 | @code{str} in the subskeleton. They can also be used non-interactively, when | |
274 | prompt is a lisp-expression that returns successive list-elements. | |
275 | @item @code{resume:} | |
276 | Ignored. Execution resumes here if the user quits during skeleton | |
277 | interpretation. | |
278 | @item @code{quit} | |
279 | A constant which is non-@code{nil} when the @code{resume:} section was entered | |
280 | because the user quit. | |
281 | @end table | |
282 | ||
283 | @findex skeleton-further-elements | |
284 | Some modes also use other skeleton elements they themselves defined. For | |
285 | example in shell script mode's skeletons you will find @code{<} which does a | |
286 | rigid indentation backwards, or in CC mode's skeletons you find the | |
287 | self-inserting elements @code{@{} and @code{@}}. These are defined by the | |
288 | buffer-local variable @code{skeleton-further-elements} which is a list of | |
289 | variables bound while interpreting a skeleton. | |
290 | ||
291 | @findex define-skeleton | |
292 | The macro @code{define-skeleton} defines a command for interpreting a | |
293 | skeleton. The first argument is the command name, the second is a | |
294 | documentation string, and the rest is an interactor and any number of skeleton | |
295 | elements together forming a skeleton. This skeleton is assigned to a variable | |
296 | of the same name as the command and can thus be overridden from your | |
88edc57f | 297 | @file{~/.emacs} file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). |
4009494e GM |
298 | |
299 | ||
300 | ||
301 | @node Inserting Pairs | |
302 | @chapter Inserting Matching Pairs of Characters | |
303 | @cindex inserting pairs | |
304 | @cindex pairs | |
305 | ||
306 | Various characters usually appear in pairs. When, for example, you insert | |
307 | an open parenthesis, no matter whether you are programming or writing prose, | |
308 | you will surely enter a closing one later. By entering both at the same time | |
06827ec8 | 309 | and leaving the cursor in between, Emacs can guarantee you that such |
4009494e GM |
310 | parentheses are always balanced. And if you have a non-qwerty keyboard, where |
311 | typing some of the stranger programming language symbols makes you bend your | |
312 | fingers backwards, this can be quite relieving too. | |
313 | ||
314 | @findex skeleton-pair-insert-maybe | |
315 | @vindex skeleton-pair | |
88edc57f | 316 | This is done by binding the first key (@pxref{Rebinding,,, emacs, The GNU Emacs Manual}) of |
4009494e GM |
317 | the pair to @code{skeleton-pair-insert-maybe} instead of |
318 | @code{self-insert-command}. The ``maybe'' comes from the fact that | |
319 | this at-first surprising behavior is initially turned off. To enable | |
320 | it, you must set @code{skeleton-pair} to some non-@code{nil} value. | |
88edc57f | 321 | And even then, a positive argument (@pxref{Arguments,,, emacs, The GNU Emacs Manual}) will |
4009494e | 322 | make this key behave like a self-inserting key |
88edc57f | 323 | (@pxref{Inserting Text,,, emacs, The GNU Emacs Manual}). |
4009494e GM |
324 | |
325 | @vindex skeleton-pair-on-word | |
326 | While this breaks with the stated intention of always balancing pairs, it | |
327 | turns out that one often doesn't want pairing to occur, when the following | |
328 | character is part of a word. If you want pairing to occur even then, set | |
329 | @code{skeleton-pair-on-word} to some non-@code{nil} value. | |
330 | ||
331 | @vindex skeleton-pair-alist | |
332 | Pairing is possible for all visible characters. By default the | |
333 | parenthesis @samp{(}, the square bracket @samp{[}, the brace | |
334 | @samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all | |
335 | pair with the symmetrical character. All other characters pair | |
336 | themselves. This behavior can be modified by the variable | |
337 | @code{skeleton-pair-alist}. This is in fact an alist of skeletons | |
338 | (@pxref{Skeleton Language}), with the first part of each sublist | |
339 | matching the typed character. This is the position of the interactor, | |
340 | but since pairs don't need the @code{str} element, this is ignored. | |
341 | ||
342 | Some modes have bound the command @code{skeleton-pair-insert-maybe} | |
343 | to relevant keys. These modes also configure the pairs as | |
344 | appropriate. For example, when typing english prose, you'd expect the | |
345 | backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell | |
346 | script mode it must pair to itself. They can also inhibit pairing in | |
347 | certain contexts. For example an escaped character stands for itself. | |
348 | ||
349 | ||
350 | ||
351 | @node Autoinserting | |
352 | @chapter Autoinserting Text in Empty Files | |
353 | @cindex autoinserting | |
354 | ||
355 | @findex auto-insert | |
356 | @kbd{M-x auto-insert} will put some predefined text at the beginning of | |
357 | the buffer. The main application for this function, as its name suggests, | |
358 | is to have it be called automatically every time an empty, and only an | |
359 | empty file is visited. This is accomplished by putting @code{(add-hook | |
360 | 'find-file-hook 'auto-insert)} into your @file{~/.emacs} file | |
88edc57f | 361 | (@pxref{Init File,,, emacs, The GNU Emacs Manual}). |
4009494e GM |
362 | |
363 | @vindex auto-insert-alist | |
364 | What gets inserted, if anything, is determined by the variable | |
365 | @code{auto-insert-alist}. The @sc{car}s of this list are each either | |
366 | a mode name, making an element applicable when a buffer is in that | |
367 | mode. Or they can be a string, which is a regexp matched against the | |
368 | buffer's file name. In that way different kinds of files that have | |
369 | the same mode in Emacs can be distinguished. The @sc{car}s may also | |
370 | be cons cells consisting of mode name or regexp as above and an | |
371 | additional descriptive string. | |
372 | ||
373 | When a matching element is found, the @sc{cdr} says what to do. It may | |
374 | be a string, which is a file name, whose contents are to be inserted, if | |
375 | that file is found in the directory @code{auto-insert-directory} or under a | |
376 | absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to | |
377 | be inserted. | |
378 | ||
379 | It can also be a function, which allows doing various things. The function | |
380 | can simply insert some text, indeed, it can be skeleton command (@pxref{Using | |
381 | Skeletons}). It can be a lambda function which will for example conditionally | |
382 | call another function. Or it can even reset the mode for the buffer. If you | |
1df7defd | 383 | want to perform several such actions in order, you use a vector, i.e., several |
4009494e GM |
384 | of the above elements between square brackets (@samp{[@r{@dots{}}]}). |
385 | ||
386 | By default C and C++ headers insert a definition of a symbol derived from | |
387 | the filename to prevent multiple inclusions. C and C++ sources insert an | |
388 | include of the header. Makefiles insert the file makefile.inc if it exists. | |
389 | ||
390 | TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while | |
391 | LaTeX mode files insert a typical @code{\documentclass} frame. Html | |
392 | files insert a skeleton with the usual frame. | |
393 | ||
394 | Ada mode files call the Ada header skeleton command. Emacs lisp | |
395 | source files insert the usual header, with a copyright of your | |
396 | environment variable @env{$ORGANIZATION} or else the FSF, and prompt | |
397 | for valid keywords describing the contents. Files in a @file{bin} | |
398 | directory for which Emacs could determine no specialized mode | |
88edc57f | 399 | (@pxref{Choosing Modes,,, emacs, The GNU Emacs Manual}) are set to Shell script mode. |
4009494e GM |
400 | |
401 | @findex define-auto-insert | |
88edc57f | 402 | In Lisp (@pxref{Init File,,, emacs, The GNU Emacs Manual}) you can use the function |
4009494e GM |
403 | @code{define-auto-insert} to add to or modify |
404 | @code{auto-insert-alist}. See its documentation with @kbd{C-h f | |
405 | define-auto-insert}. | |
406 | ||
407 | @vindex auto-insert | |
408 | The variable @code{auto-insert} says what to do when @code{auto-insert} is | |
1df7defd | 409 | called non-interactively, e.g., when a newly found file is empty (see above): |
4009494e GM |
410 | @table @asis |
411 | @item @code{nil} | |
412 | Do nothing. | |
413 | @item @code{t} | |
1df7defd | 414 | Insert something if possible, i.e., there is a matching entry in |
4009494e GM |
415 | @code{auto-insert-alist}. |
416 | @item other | |
417 | Insert something if possible, but mark as unmodified. | |
418 | @end table | |
419 | ||
420 | @vindex auto-insert-query | |
421 | The variable @code{auto-insert-query} controls whether to ask about | |
422 | inserting something. When this is @code{nil}, inserting is only done with | |
423 | @kbd{M-x auto-insert}. When this is @code{function}, you are queried | |
424 | whenever @code{auto-insert} is called as a function, such as when Emacs | |
425 | visits an empty file and you have set the above-mentioned hook. Otherwise | |
e4920bc9 | 426 | you are always queried. |
4009494e GM |
427 | |
428 | @vindex auto-insert-prompt | |
429 | When querying, the variable @code{auto-insert-prompt}'s value is used as a | |
430 | prompt for a y-or-n-type question. If this includes a @samp{%s} construct, | |
431 | that is replaced by what caused the insertion rule to be chosen. This is | |
432 | either a descriptive text, the mode-name of the buffer or the regular | |
433 | expression that matched the filename. | |
434 | ||
435 | ||
436 | ||
437 | @node Copyrights | |
438 | @chapter Inserting and Updating Copyrights | |
439 | @cindex copyrights | |
440 | ||
441 | @findex copyright | |
442 | @kbd{M-x copyright} is a skeleton inserting command, that adds a copyright | |
443 | notice at the point. The ``by'' part is taken from your environment variable | |
444 | @env{$ORGANIZATION} or if that isn't set you are prompted for it. If the | |
88edc57f | 445 | buffer has a comment syntax (@pxref{Comments,,, emacs, The GNU Emacs Manual}), this is inserted as a comment. |
4009494e GM |
446 | |
447 | @findex copyright-update | |
448 | @vindex copyright-limit | |
449 | @vindex copyright-current-year | |
450 | @kbd{M-x copyright-update} looks for a copyright notice in the first | |
451 | @code{copyright-limit} characters of the buffer and updates it when necessary. | |
452 | The current year (variable @code{copyright-current-year}) is added to the | |
1df7defd | 453 | existing ones, in the same format as the preceding year, i.e., 1994, '94 or 94. |
4009494e GM |
454 | If a dash-separated year list up to last year is found, that is extended to |
455 | current year, else the year is added separated by a comma. Or it replaces | |
456 | them when this is called with a prefix argument. If a header referring to a | |
88edc57f | 457 | wrong version of the GNU General Public License (@pxref{Copying,,, emacs, The GNU Emacs Manual}) is found, |
4009494e GM |
458 | that is updated too. |
459 | ||
460 | An interesting application for this function is to have it be called | |
461 | automatically every time a file is saved. This is accomplished by | |
462 | putting @code{(add-hook 'before-save-hook 'copyright-update)} into | |
88edc57f | 463 | your @file{~/.emacs} file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). Alternative, |
4009494e GM |
464 | you can do @kbd{M-x customize-variable @key{RET} before-save-hook |
465 | @key{RET}}. @code{copyright-update} is conveniently listed as an | |
466 | option in the customization buffer. | |
467 | ||
468 | @vindex copyright-query | |
469 | The variable @code{copyright-query} controls whether to update the | |
470 | copyright or whether to ask about it. When this is @code{nil} updating is | |
471 | only done with @kbd{M-x copyright-update}. When this is @code{function} | |
472 | you are queried whenever @code{copyright-update} is called as a function, | |
473 | such as in the @code{before-save-hook} feature mentioned above. Otherwise | |
474 | you are always queried. | |
475 | ||
476 | ||
477 | ||
478 | @node Executables | |
479 | @chapter Making Interpreter Scripts Executable | |
480 | @cindex executables | |
481 | ||
482 | @vindex executable-prefix | |
483 | @vindex executable-chmod | |
484 | Various interpreter modes such as Shell script mode or AWK mode will | |
485 | automatically insert or update the buffer's magic number, a special | |
486 | comment on the first line that makes the @code{exec} systemcall know | |
487 | how to execute the script. To this end the script is automatically | |
488 | made executable upon saving, with @code{executable-chmod} as argument | |
489 | to the system @code{chmod} command. The magic number is prefixed by | |
490 | the value of @code{executable-prefix}. | |
491 | ||
492 | @vindex executable-magicless-file-regexp | |
493 | Any file whose name matches @code{executable-magicless-file-regexp} is not | |
494 | furnished with a magic number, nor is it made executable. This is mainly | |
495 | intended for resource files, which are only meant to be read in. | |
496 | ||
497 | @vindex executable-insert | |
498 | The variable @code{executable-insert} says what to do when | |
1df7defd | 499 | @code{executable-set-magic} is called non-interactively, e.g., when file has no |
4009494e GM |
500 | or the wrong magic number: |
501 | @table @asis | |
502 | @item @code{nil} | |
503 | Do nothing. | |
504 | @item @code{t} | |
505 | Insert or update magic number. | |
506 | @item other | |
507 | Insert or update magic number, but mark as unmodified. | |
508 | @end table | |
509 | ||
510 | @findex executable-set-magic | |
511 | @vindex executable-query | |
512 | The variable @code{executable-query} controls whether to ask about | |
513 | inserting or updating the magic number. When this is @code{nil} updating | |
514 | is only done with @kbd{M-x executable-set-magic}. When this is | |
515 | @code{function} you are queried whenever @code{executable-set-magic} is | |
516 | called as a function, such as when Emacs puts a buffer in Shell script | |
e4920bc9 | 517 | mode. Otherwise you are always queried. |
4009494e GM |
518 | |
519 | @findex executable-self-display | |
520 | @kbd{M-x executable-self-display} adds a magic number to the buffer, which | |
521 | will turn it into a self displaying text file, when called as a Un*x command. | |
522 | The ``interpreter'' used is @code{executable-self-display} with argument | |
523 | @samp{+2}. | |
524 | ||
525 | @node Timestamps | |
526 | @chapter Maintaining Timestamps in Modified Files | |
527 | @cindex timestamps | |
528 | ||
529 | @findex time-stamp | |
530 | @vindex before-save-hook | |
531 | The @code{time-stamp} command can be used to update automatically a | |
532 | template in a file with a new time stamp every time you save the file. | |
533 | Customize the hook @code{before-save-hook} to add the function | |
534 | @code{time-stamp} to arrange this. It you use Custom to do this, | |
535 | then @code{time-stamp} is conveniently listed as an option in the | |
536 | customization buffer. | |
537 | ||
538 | @vindex time-stamp-active | |
539 | @vindex time-stamp-format | |
540 | @vindex time-stamp-start | |
541 | The time stamp is updated only if the customizable variable | |
542 | @code{time-stamp-active} is on, which it is by default; the command | |
543 | @code{time-stamp-toggle-active} can be used to toggle it. The format of | |
544 | the time stamp is set by the customizable variable | |
545 | @code{time-stamp-format}. | |
546 | ||
547 | @vindex time-stamp-line-limit | |
548 | @vindex time-stamp-end | |
549 | @vindex time-stamp-count | |
550 | @vindex time-stamp-inserts-lines | |
551 | The variables @code{time-stamp-line-limit}, @code{time-stamp-start}, | |
552 | @code{time-stamp-end}, @code{time-stamp-count}, and | |
553 | @code{time-stamp-inserts-lines} control finding the template. Do not | |
554 | change these in your init file or you will be incompatible with other | |
555 | people's files. If you must change them, do so only in the local | |
556 | variables section of the file itself. | |
557 | ||
558 | Normally the template must appear in the first 8 lines of a file and | |
559 | look like one of the following: | |
560 | ||
561 | @example | |
562 | Time-stamp: <> | |
563 | Time-stamp: " " | |
564 | @end example | |
565 | ||
566 | The time stamp is written between the brackets or quotes: | |
567 | ||
568 | @example | |
569 | Time-stamp: <1998-02-18 10:20:51 gildea> | |
570 | @end example | |
571 | ||
572 | @node QuickURL | |
573 | @chapter QuickURL: Inserting URLs Based on Text at Point | |
574 | ||
575 | @vindex quickurl-url-file | |
576 | @findex quickurl | |
577 | @cindex URLs | |
578 | @kbd{M-x quickurl} can be used to insert a URL into a buffer based on | |
579 | the text at point. The URLs are stored in an external file defined by | |
580 | the variable @code{quickurl-url-file} as a list of either cons cells of | |
581 | the form @code{(@var{key} . @var{URL})} or | |
582 | lists of the form @code{(@var{key} @var{URL} @var{comment})}. These | |
583 | specify that @kbd{M-x quickurl} should insert @var{URL} if the word | |
584 | @var{key} is at point, for example: | |
585 | ||
586 | @example | |
587 | (("FSF" "http://www.fsf.org/" "The Free Software Foundation") | |
588 | ("emacs" . "http://www.emacs.org/") | |
589 | ("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World")) | |
590 | @end example | |
591 | ||
592 | @findex quickurl-add-url | |
593 | @findex quickurl-list | |
594 | @kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} | |
595 | pair. @kbd{M-x quickurl-list} provides interactive editing of the URL | |
596 | list. | |
597 | ||
598 | @node Tempo | |
599 | @chapter Tempo: Flexible Template Insertion | |
600 | ||
601 | @cindex templates | |
602 | The Tempo package provides a simple way to define powerful templates, or | |
603 | macros, if you wish. It is mainly intended for, but not limited to, | |
604 | programmers to be used for creating shortcuts for editing | |
605 | certain kinds of documents. | |
606 | ||
607 | @findex tempo-backward-mark | |
608 | @findex tempo-forward-mark | |
609 | A template is defined as a list of items to be inserted in the current | |
610 | buffer at point. Some can be simple strings, while others can control | |
611 | formatting or define special points of interest in the inserted text. | |
612 | @kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be | |
613 | used to jump between such points. | |
614 | ||
615 | More flexible templates can be created by including Lisp symbols, which | |
616 | will be evaluated as variables, or lists, which will be evaluated | |
617 | as Lisp expressions. Automatic completion of specified tags to expanded | |
618 | templates can be provided. | |
619 | ||
620 | @findex tempo-define-template | |
621 | See the documentation for @code{tempo-define-template} for the different | |
622 | items that can be used to define a tempo template with a command for | |
623 | inserting it. | |
624 | ||
625 | See the commentary in @file{tempo.el} for more information on using the | |
626 | Tempo package. | |
627 | ||
628 | @node Hippie Expand | |
629 | @chapter `Hippie' Expansion | |
630 | ||
631 | @findex hippie-expand | |
632 | @kindex M-/ | |
633 | @vindex hippie-expand-try-functions-list | |
634 | @kbd{M-x hippie-expand} is a single command providing a variety of | |
635 | completions and expansions. Called repeatedly, it tries all possible | |
636 | completions in succession. | |
637 | ||
638 | Which ones to try, and in which order, is determined by the contents of | |
639 | the customizable option @code{hippie-expand-try-functions-list}. Much | |
640 | customization of the expansion behavior can be made by changing the | |
641 | order of, removing, or inserting new functions in this list. Given a | |
642 | positive numeric argument, @kbd{M-x hippie-expand} jumps directly that | |
643 | number of functions forward in this list. Given some other argument (a | |
644 | negative argument or just @kbd{C-u}) it undoes the tried completion. | |
645 | ||
646 | See the commentary in @file{hippie-exp.el} for more information on the | |
647 | possibilities. | |
648 | ||
649 | Typically you would bind @code{hippie-expand} to @kbd{M-/} with | |
650 | @code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one | |
651 | of the expansion possibilities. | |
652 | ||
653 | @node GNU Free Documentation License | |
654 | @appendix GNU Free Documentation License | |
655 | @include doclicense.texi | |
656 | ||
657 | @node Concept Index | |
658 | @unnumbered Concept Index | |
659 | @printindex cp | |
660 | ||
661 | @node Command Index | |
662 | @unnumbered Command Index | |
663 | @printindex fn | |
664 | ||
665 | @node Variable Index | |
666 | @unnumbered Variable Index | |
667 | @printindex vr | |
668 | ||
4009494e | 669 | @bye |