next up previous contents index
Next: Bug reporting Up: Standard File Headers Previous: Simple customization

Advanced customization


What do you do if you want to insert additional fields in all new file headers? You have to do some Lisp programming to add to the functions in filehdr.el. Under no circumstances should you modify filehdr.el itself! That is the sole prerogative of its original author. You can freely copy code from it, but put that code in a file with a different name.

If you are a real Lisp wizard, you can just read the code in filehdr.el, and write whatever new code you want. On the other hand, if you were such a wizard, you'd probably ``read the code instead of this documentation.''

The most likely function you'll want to modify is make-file-header.¸make-file-header Here is what its body looks like:

    (mapcar '(lambda (entry)
               (file-header-key (car entry) (nth 1 entry)))
            (append file-header-standard-entries

Each of these lines is a Lisp function call; the function name is the first one in each parenthesized list. Each function supplies part of the standard file header.

The first and last function calls provide a full line comment start and end, if the file class requires it.

The file-header-entry¸file-header-entry and file-header-exit¸file-header-exit functions supply the class name tag and the final closing brace. That is, they generate something like this:

%%%  @LaTeX-file{
%%%  }

The individual file attributes are then supplied by calls to the generic function file-header-key,¸file-header-key which is given the attribute name as its first argument, and the name of a function to call to generate a string for the attribute's initial value. The returned string may span multiple lines; it will be neatly formatted and properly indented by a service function called inside file-header-key.

The Lisp mapcar¸mapcar function called in the body of make-file-header¸make-file-header applies its second argument, here an anonymous lambda¸lambda function, to each element of the list supplied as its third argument. The keywords that are inserted are determined by the entries in the lists file-header-standard-entries¸file-header-standard-entries and file-header-extra-entries,¸file-header-extra-entries which are appended into one big list.

Here is a simple example of one of these initial value-returning functions:

(defun file-header-codetable ()
  "Return as a string the default codetable value."

If you want to add a new file header attribute entry, you need to add an entry to file-header-extra-entries,¸file-header-extra-entries and write a function to return an appropriate initial value.

This is best illustrated by a real example--the addition of a copyright attribute¸attributecopyright in the file header.

First we insert the lines

(setq file-header-extra-entries
        ("copyright" file-header-copyright)

in the .emacs file.

Next, we write the function to return the initial value:

(defun file-header-copyright ()
  "Return as a string the default copyright value."
  "None.  This file is PUBLIC DOMAIN."

That is all there is to it. To test the new code, you can compile it inside Emacs in Emacs-Lisp editing mode by typing ESC C-x with the cursor inside the function, and then run it by name from the minibuffer: ESC ESC (file-header-copyright).

When you run make-file-header,¸make-file-header it should now produce an attribute entry like

%%%     copyright     = "None.  This file is PUBLIC DOMAIN.",

When everything is working, save the new Emacs Lisp file, and run M-x byte-compile-file on it. You can then load it interactively with M-x load-file, or better, automatically at Emacs start-up time by adding the line

(load "myfilhdr" t t nil)

assuming you called the modified file myfilhdr.el.

If the code in myfilhdr.el is short, you can keep it in your .emacs instead, and altogether avoid the need for a separate file and the byte compilation and load¸load command. Compilation is only useful for speeding up the loading of large files of Emacs Lisp code.

You probably will not have to do any more than this, unless you add a new attribute that must be updated each time the function update-file-header-and-save¸update-file-header-and-save is invoked. In such a case, you'll have to study its body, and the functions it calls, to make the necessary modifications.

Bug reporting, Bibliography, Advanced customization, Top

next up previous contents index
Next: Bug reporting Up: Standard File Headers Previous: Simple customization
Nelson H. F. Beebe