The preceding chapters have outlined the background for, and contents of, standard file headers. Here we show how to generate them with very little effort.
The GNU Emacs file filehdr.el contains the following user-callable functions:
make-file-header show-file-header-variables test-file-header update-checksum update-date update-date-and-minor-version update-file-header-and-save update-major-version update-minor-version update-simple-checksum
There are several other functions in that file, but they are for internal use only, and will not be further documented here.
When you want to add a new file header to an existing file, you just type M-x make-file-header; this produces something like this at the top of your file:
%%% ====================================================================
%%% @LaTeX-file{
%%% author = "Nelson H. F. Beebe",
%%% version = "1.28",
%%% date = "06 March 1996",
%%% time = "13:14:03 MST",
%%% filename = "filehdr.ltx",
%%% address = "Center for Scientific Computing
%%% Department of Mathematics
%%% University of Utah
%%% Salt Lake City, UT 84112
%%% USA",
%%% telephone = "+1 801 581 5254",
%%% FAX = "+1 801 581 4148",
%%% URL = "http://www.math.utah.edu/~beebe",
%%% checksum = "53883 2543 10843 81774",
%%% email = "beebe@math.utah.edu (Internet)",
%%% codetable = "ISO/ASCII",
%%% keywords = "file header, checksum",
%%% supported = "yes",
%%% docstring = "This LaTeXinfo document describes
%%% filehdr.el, a GNU Emacs support package for
%%% the creation and maintenance of standard
%%% file headers, such as this one. It may be
%%% processed by LaTeX to produce a typeset
%%% document, or by M-x latexinfo-format-buffer
%%% in GNU Emacs to produce an info file for
%%% on-line documentation.
%%%
%%% The checksum field above contains a CRC-16
%%% checksum as the first value, followed by the
%%% equivalent of the standard UNIX wc (word
%%% count) utility output of lines, words, and
%%% characters. This is produced by Robert
%%% Solovay's checksum utility.",
%%% }
%%% ====================================================================
Where does it get all of this information? Well, the file name, date and time stamps, author name, electronic mail address, and date are all determined automatically from calls to various system services. For example, on UNIX, the author name comes from the file /etc/passwd; on VAX VMS, it will come from the file SYSMANAGER:SYSUAF.DAT.
The comment syntax was determined from the file extension, and we'll say more about it later.
The only information above that Emacs cannot determine is your postal address,¸postal addressdefining and telephone¸telephone numberdefining and FAX numbers, and possibly, your WorldWide Web URL.¸FAX numberdefining These only have to be supplied once, usually in your GNU Emacs startup file, .emacs. This is most easily done with Lisp code that looks something like this:
(setq file-header-user-address ; for M-x make-file-header "Center for Scientific Computing Department of Mathematics University of Utah Salt Lake City, UT 84112 USA") (setq file-header-user-telephone "+1 801 581 5254") (setq file-header-user-FAX "+1 801 581 4148") (setq file-header-user-URL "http://www.math.utah.edu/~beebe")file-header-user-address¸file-header-user-telephone¸file-header-user-FAX file-header-user-URL
Once this is installed in the .emacs file, GNU Emacs will find it every time it starts up.
If the electronic-mail address constructed from the Emacs user-login-name¸user-login-name and system-name¸system-name functions is not suitable, you can provide an alternative one like this:
(setq file-header-user-email "beebe@math.utah.edu")file-header-user-email¸
In any of the following situations, you should set file-header-user-email¸file-header-user-email in your startup .emacs file.
The version number is left empty; you can manually insert an appropriate one, perhaps 1.00, or if you are just starting, 0.00.
The checksum and keywords entries are also left empty. There is no point in inserting a checksum until you are ready to save the file, and the keywords have to be supplied by a human.
Now suppose you've just edited a file with such a file header, and you would like to update the header to reflect the changes, and then save the file. All you need to type is M-x update-file-header-and-save, and with Emacs' normal command completion, you can probably hit the tab key after the f in file.
The function update-file-header-and-save¸update-file-header-and-save will update the date and time stamps, the minor version number, the checksum, and save the file.
If the file is a LATEX¸LaTeXdate update file, the date update will also search forward for text that looks something like
\\date{29 November 1991 \\
Version 1.01}
and change it to the current date and version. That makes it easy to get the version number and revision date printed on the title page.
You can do these updates manually if you like by invoking the functions update-checksum,¸update-checksum update-date,¸update-date update-minor-version,¸update-minor-version and update-date-and-minor-version¸update-date-and-minor-version explicitly.
Major version numbers are rarely changed, and you could easily do the job manually. Nevertheless, for completeness, update-major-version¸update-major-version is supplied to automate the job.
update-checksum¸update-checksum will trim trailing whitespace¸whitespacediscarding trailing (but leave embedded tabs intact), send the buffer to the checksum program, and replace it with the output. Don't interrupt it while it is working, or you might lose your file! ¸The Emacs interface to checksum has not yet been tested on VAX VMS,¸VAX VMS so update-checksum¸update-checksum on that system calls update-simple-checksum¸update-simple-checksum instead. That function will compute counts of lines, words, and characters and insert them in the checksum value. You could use this if for some reason you don't have checksum¸checksum installed yet. checksum should be available from the same place you got filehdr.el; eventually it will be on dozens of TEX archive machines around the world.
Simple customization, Advanced customization, GNU Emacs editing support, Top