Sams Teach Yourself Emacs in 24 Hours |  | ContentsIndex
Hour 4: Basic Editing |  | Previous HourNext Hour
Sections in this Hour: |  |  |  |

## Document Templates

One of the main philosophies of Emacs is that you should spend your time being a genius instead of doing trivial monotonous tasks! If you remember this when you use Emacs, you'll find that you spend time on things that Emacs can do for you with a single keystroke or even no keystrokes!

An example of this is creating a new file. When you create a new file, you most often spend the first few minutes inserting the same text that you inserted the last time you created a similar file, for example, the last time you created an HTML document.

The solution to this problem is to make Emacs insert a template. This template is different depending on whether you write C programs, HTML documents, or even a letter to Grandma. Furthermore, the template might differ between one set of HTML files to another. The HTML files of your personal Web page might be quite different from those you make for your company. Likewise templates for one programming project can be quite different from those of another.

On the CD is a library called template. The installation is described in Appendix A. When this library is enabled, Emacs inserts templates for you. You must, of course, define the templates first.

Caution - This library is powerful and configurable but, for simple document templates, you will never use all its power. When you finish with this book and want to learn more, I strongly suggest that you take a look at the top of the Lisp file (discussed in Hour 1, "Introducing Emacs").

### Finding the Template File

When a new file is created, Emacs searches for a template with a name based on the file's extension. That is, if you create a file with the name test.html, Emacs searches for a template file called TEMPLATE.html.tpl. Likewise if you create a new file called letter.txt, Emacs searches for the template file TEMPLATE.txt.tpl.

When searching for a template, Emacs first looks in the directory in which the new file is to be located. If Emacs doesn't find the file there, it looks in the subdirectory of this one with the name Templates. If Emacs still doesn't find the file, Emacs continues searching in the parent directory and a subdirectory of this called Templates. Emacs continues searching for the file in this way until Emacs gets to the root of your home directory. If Emacs still hasn't found the file at that point, Emacs searches for the file in a directory that you might have defined as a template directory.

An example might clarify the matter. Imagine that you are creating the file ~/work/Emacs-project/note.txt and all your standard templates are located in the directory ~/lib/templates. Emacs searches for the following files in this order. The first it finds it uses as the template:

  1. ~/work/Emacs-project/TEMPLATE.txt.tpl

  2. ~/work/Emacs-project/Templates/TEMPLATE.txt.tpl

  3. ~/work/TEMPLATE.txt.tpl

  4. ~/work/Templates/TEMPLATE.txt.tpl

  5. ~/TEMPLATE.txt.tpl

  6. ~/Templates/TEMPLATE.txt.tpl

  7. ~/lib/templates/TEMPLATE.txt.tpl

You might think that it is strange behavior searching so desperately for a template; however, it's important for the following reasons:

- By searching in both the current directory and the Template subdirectory, you have the opportunity to hide the templates in a subdirectory if you don't want them to lie around with all your other files. On the other hand, you are not forced to do so!

- By searching back trough the path, you might find specific templates in subdirectories and generic templates in top-level directories. As an example, you might have a directory called Letters that contains all your letters. In this directory, you might have a generic template, which inserts something like Dear... and the current date. In a subdirectory to the Letter directory you might have a directory with letters to your girl- or boyfriend. This template might include text such as Yours forever , and so on.

- By looking in the standard template directory at the end, you can have some templates that are general for all files ending in .txt (letters, configuration descriptions, and other kinds of text files) located in one place.

Windows Notes - If you use Windows, you know that you seldom edit files located in your home directory (not as often as you would if you used UNIX). You might need to tell Emacs to search for templates farther down in the directory structure than in your home directory. To do this, insert the following line into your .emacs file: (setq template-home-directory "/")

### The Content of a Template

The templates can contain ordinary text combined with stand-ins. These stand-ins either are replaced with other text or mark positions in the buffer at the time a new file is created based on this template. The stand-ins are in the form (>>>letter<<<). Examples include >>>P<<<, which sets the point of the newly created document at this location in the buffer, and >>>A<<<, which inserts your email address.

The simplest kind of templates are those that simply insert text combined with one of the predefined stand-ins. The predefined stand-ins can be seen in Table 4.1.

#### Table 4.1 All the Codes that Require No User Definition

Code | Example | Description
| Files and Directories |
(>>>DIR<<<) | ~/Letters/ | Directory part of the filename
(>>>FILE<<<) | Gretchen.txt | The filename without the directory
(>>>RILE_RAW<<<) | Gretchen | The filename without the extension
(>>>EILE_EXT<<<) | txt | The extension of the filename (without the dot)
| Time and Date |
(>>>DATE<<<) | 07 Jan 1999 20:17:29 | The date and time
(>>>ISO_DATE<<<) | 1999-01-07 | The ISO 8601 date
| System Information |
(>>>AUTHOR<<<) | blackie@ifad.dk | The full email address
(>>>LOGIN_NAME<<<) | blackie | The login name
(>>>HOST_ADDR<<<) | ifad.dk | The hostname
(>>>USER_NAME<<<) | Jesper Pedersen | The user's real name
| Locations |
(>>>POINT<<<) |  | This sets the point; only one point can be set, of course
(>>>MARK<<<) |  | This sets the mark; again, only one mark can be set
(>>>1<<<) ... (>>>9<<<) |  | These are ten possible locations that you can get to later. To get to any of these locations, press C-x r j (jump-to-register) and the number given previously.

A sample template might be the following:

                                Odense (I<<<)
    Dear (>P<<<)

    Our record number: (>1<<<)

    Cheers (>U<<<)

In Figure 4.16, you can see a new file created with this template.

Figure 4.16
A file created with the sample template.

### Inserting the Result of Asking a Question

In your template, you can also insert text that is the result of asking a question. Thus in the previous example, you might want to be prompted for the name to be inserted after the word Dear. (It is very important to you that you do not forget this name.)

Questions like this can be inserted in the template, as you can see in the following template:

                               Odense (>>>I<<<)
    Dear (>>>name<<<)
    (>>>P<<<)

    Our record number: (>>>number<<<)

    Cheers (>>>U<<<)

    >TEMPLATE-DEFINITION-SECTION<<
    ("name" "What is the name of the customer? ")
    ("number" "What is the record number? ")

To make Emacs ask you questions, you need to insert a line that indicates that the definitions section starts. Text after this line is for defining the questions, so be very careful not to insert text that does not have the syntax you see in the preceding template.

Each question is associated to a word (the question What is the name of the customer? is associated with the word name). This word is used as the stand-in for the text (that is, the text (>>>name<<<) after the word Dear).

When you open a new file, Emacs now asks you these questions, as you can see in Figure 4.17, and your answers are inserted at the appropriate locations in the buffer, as you can see in Figure 4.18.

Figure 4.17
Emacs asks for information within the template.

Figure 4.18
The answer is inserted in the text.

Sams Teach Yourself Emacs in 24 Hours |  | ContentsIndex
Hour 4: Basic Editing |  | Previous HourNext Hour
Sections in this Hour: |  |  |  |

© Copyright Macmillan USA. All rights reserved.