The GNU Emacs Lisp code in filehdr.el has been written to make it easy to customize without your having to become a Lisp programmer. Of course, Lisp is so much fun that you might want to do that anyway!
The code contains several large tables stored in Lisp variables:
file-header-standard-at-sign-special-cases file-header-standard-comment-prefixes file-header-standard-entries file-header-standard-paired-comment-delimiter-languages file-header-standard-suffix-and-type
These are not intended to be modified by users, as the phrase -standard- in their names indicates.
Each of them is a list of lists; the innermost lists contain two or three character strings. Sublists are ordered alphabetically for human readability; the code does not care what order they appear in.
The first of them, file-header-standard-at-sign-special-cases,¸file-header-standard-at-sign-special-cases is used to handle those few exceptional file classes that do not permit at-signs, @, to be used in comments without special handling. Here is the current value of this variable:
(
("BibTeX" " at ")
("C-Web" "@@")
("Web" "@@")
("Web-change" "@@")
)
This means that when a header for a file in class BibTeX is created, at-signs should be replaced by the string at . For the other classes, at-signs must be doubled.
The second variable, file-header-standard-comment-prefixes,¸file-header-standard-comment-prefixes has a very long value, so we show only a portion here:
(
("Adobe-Font-Metric" "Comment ")
("AmSTeX" "%%% ")
("Awk" "### ")
...
("Web-change" "%%% ")
("Yacc" "")
)
This means that in an Adobe Font Metric file,¸Adobe Font Metric file comments must begin a line with the string Comment . For awk¸awk files, a triple sharp sign and a space will begin all file header lines. yacc¸yacc file headers have no comment prefix at all.
The third variable, file-header-standard-entries,¸file-header-standard-entries contains pairs of entry names and functions to supply values for them. It looks something like this:
(
("author" file-header-author)
("version" file-header-version)
("date" file-header-date)
("time" file-header-time)
("filename" file-header-filename)
("address" file-header-address)
("telephone" file-header-telephone)
("FAX" file-header-FAX)
("URL" file-header-URL)
("checksum" file-header-checksum)
("email" file-header-email)
("codetable" file-header-codetable)
("keywords" file-header-keywords)
("supported" file-header-supported)
("docstring" file-header-docstring)
)
The file header is created by processing these entry names in order.
The fourth variable, with the name file-header-standard-paired-comment-delimiter-languages,¸file-header-standard-paired-comment-delimiter-languages is a little more complex. Its classes cover languages that use distinct starting and ending comment strings, instead of having comments that terminate at end of line. For each class name, its list entries contain two strings, one for the comment start, and one for the comment end. To help make them stand out better, the strings are often stretched to 72 characters in length:
(
("C"
(concat "/*" (make-string 70 ?\*) "\n")
(concat (make-string 70 ?\*) "*/\n"))
("Font-Property-List"
(concat "(COMMENT "(make-string 63 ?\*) "\n")
(concat (make-string 71 ?\*) ")\n"))
...
("Scribe"
"@Begin{Comment}\n"
"@End{Comment}\n")
...
("Yacc"
(concat " /*" (make-string 69 ?\*) "\n")
(concat " " (make-string 69 ?\*) "*/\n"))
)
)
To avoid the need for long constant strings in the code, several of them are generated dynamically by the Lisp concatenation operator, concat.¸concat
Class names in this variable do not include the phrase -file that appears in the file header; that suffix is supplied automatically by the Emacs functions.
The last variable, file-header-standard-suffix-and-type,¸file-header-standard-suffix-and-type is the biggest of them all. It relates file extensions to file classes. This indirection was chosen because there are often several file extensions belonging to a single class. Its value looks something like this:
(
("1" "Troff-man")
("1l" "Troff-man")
("2" "Troff-man")
...
("afm" "Adobe-Font-Metric")
...
("web" "Web")
("y" "Yacc")
("yacc" "Yacc")
)
Observe that the extensions do not include a leading period.
The list of extensions was constructed by going through some large UNIX file systems (several hundred thousand files) to produce a set of unique file extensions, and then augmenting the list by hand based on the author's personal experience on several other operating systems. The resulting list has about 150 file extensions, and 85 file classes. If a file extension is unrecognized, it is assigned the class name UNKNOWN.
Here now is how you can customize the behavior of make-file-header.¸make-file-header For each Lisp variable with the phrase -standard-, there is a corresponding one with the phrase -extra- instead. These new variables are intended for user customization; you can initialize them in your startup .emacs file, and they will automatically be added to the standard ones at run time.
Here is a set of sample customizations:¸customizationexamples
(setq file-header-extra-at-sign-special-cases
'(
("Foo-Bar" " <<<AT>>> ")
))
(setq file-header-extra-comment-prefixes
'(
("Foo-Bar" "!FB!")
))
(setq file-header-extra-entries
'(
("copyright" file-header-copyright)
))
(setq file-header-extra-suffix-and-type
'(
("foobar" "Foo-Bar")
))
(setq file-header-extra-paired-comment-delimiter-languages
'(
("Foo-Bar"
(concat "/#" (make-string 70 ?\#) "\n")
(concat (make-string 70 ?\#) "#/\n"))
))
file-header-extra-at-sign-special-cases¸file-header-extra-comment-prefixes¸file-header-extra-entries¸file-header-extra-suffix-and-type¸file-header-extra-paired-comment-delimiter-languages¸
These would define a new file class Foo-Bar attached to files with extension .foobar, for which comments are delimited by /# ... #/, and by ! to end-of-line. The file header body lines would all begin with !FB!.
The Lisp form (setq var value)¸setq assigns value to the variable var; most other programming languages would write this as var = value.
The extra values set in these variables are appended to the end of the standard ones, so they can augment, but not replace , the standard values. This design choice was made intentionally to encourage standardization of the file headers. If you need to do something differently, you'll have to learn some Lisp, and look in the next chapter.
You can test your additions by visiting files with the new extensions, and then running M-x make-file-header.¸make-file-header
You can test the entire collection of code by typing M-x test-file-header.¸test-file-header This takes a while, but is thorough: it will create file headers in a temporary editor buffer for every file extension defined in the two lists file-header-standard-suffix-and-type¸file-header-standard-suffix-and-type and file-header-extra-suffix-and-type.¸file-header-extra-suffix-and-type
To see the settings of the variables named file-header-standard-xxx¸file-header-standard-xxx and file-header-extra-xxx,¸file-header-extra-xxx type M-x show-file-header-variables.¸show-file-header-variables The results will appear in a temporary buffer.
Prior to version 19 (released in early summer of 1993), GNU Emacs did not provide the time zone,¸time zone but on UNIX systems, it can be obtained from the output of the date¸date command. Since this takes a few seconds to run as a subprocess, the result is saved in a global variable, file-header-timezone-string.¸file-header-timezone-string Subsequent file headers will be produced much more rapidly. With Version 19 or later, this delay is eliminated.
If you find the delay on the first use objectionable, you can set the time zone in your .emacs file:
(setq file-header-timezone-string "MST")
This practice is not recommended, since you'll have to change it twice a year, or if you work in a different time zone.
Advanced customization, Bug reporting, Simple customization, Top