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