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