summaryrefslogtreecommitdiff
path: root/support/filehdr
diff options
context:
space:
mode:
Diffstat (limited to 'support/filehdr')
-rw-r--r--support/filehdr/Makefile182
-rw-r--r--support/filehdr/filehdr.bbl31
-rw-r--r--support/filehdr/filehdr.bib89
-rw-r--r--support/filehdr/filehdr.el1733
-rw-r--r--support/filehdr/filehdr.info1940
-rw-r--r--support/filehdr/filehdr.ltx2582
-rw-r--r--support/filehdr/filehdr.pdfbin0 -> 206397 bytes
-rw-r--r--support/filehdr/filehdr.sok176
-rw-r--r--support/filehdr/makeinfo25
l---------support/filehdr/rcs1
10 files changed, 6759 insertions, 0 deletions
diff --git a/support/filehdr/Makefile b/support/filehdr/Makefile
new file mode 100644
index 0000000000..e7f661fce1
--- /dev/null
+++ b/support/filehdr/Makefile
@@ -0,0 +1,182 @@
+#=======================================================================
+# Makefile for files in ~beebe/tex/talks/filehdr
+#
+# [30-Aug-1993]
+#=======================================================================
+
+COMPRESS = compress
+
+CP = /bin/cp -p
+
+CPP = /lib/cpp -P
+
+BIBTEX = bibtex
+
+DETEX = detex -n
+
+DIST-FILES = Makefile filehdr.bbl filehdr.bib filehdr.dvi filehdr.el \
+ filehdr.info filehdr.ltx filehdr.sok makeinfo rcs.sty
+
+DVIALW = dvialw -back
+
+FTPDIR = /u/ftp/pub/tex/bib
+
+INDEX-FILES = filehdr.cp filehdr.fn filehdr.pg filehdr.tp filehdr.vr
+
+ISPELL = ispell
+
+LATEX = latex
+
+LN = ln -s
+
+MAKEINDEX = makeindex
+
+MV = /bin/mv
+
+PSVIEW = gs -g700x1000+2+2
+
+RM = /bin/rm -f
+
+SED = /bin/sed
+
+SHELL = /bin/sh
+
+SPELL = spell
+
+TEXINDEX = texindex
+
+UNZIP = unzip
+
+VERSION = `nawk '/^;;; *version * = / \
+ { gsub(/[^0-9.]/,"",$$4); print $$4 }' filehdr.el`
+
+ZIP = zip
+
+ZOO = zoo
+
+#=======================================================================
+
+.SUFFIXES:
+
+.SUFFIXES: .dvi-alw .dvi .ltx
+
+.ltx.dvi:
+ $(LATEX) $<
+
+.dvi.dvi-alw:
+ $(DVIALW) $<
+# $(PSVIEW) $*.dvi-alw quit.ps
+
+#=======================================================================
+
+all: filehdr.dvi filehdr.info
+
+clean:
+ -$(RM) *.blg
+ -$(RM) *.cps
+ -$(RM) *.dvi
+ -$(RM) *.dvi-alw
+ -$(RM) *.fns
+ -$(RM) *.ilg
+ -$(RM) *.isp
+ -$(RM) *.kys
+ -$(RM) *.log
+ -$(RM) *.o
+ -$(RM) *.pgs
+ -$(RM) *.spl
+ -$(RM) *.tar
+ -$(RM) *.tar-lst
+ -$(RM) *.tps
+ -$(RM) *.vrs
+ -$(RM) *.zip
+ -$(RM) *.zip-lst
+ -$(RM) *.zoo
+ -$(RM) *.zoo-lst
+ -$(RM) *~
+ -$(RM) \#*
+ -$(RM) core
+
+clobber: clean
+ -$(RM) *.aux
+ -$(RM) *.bbl
+ -$(RM) *.cp
+ -$(RM) *.elc
+ -$(RM) *.fn
+ -$(RM) *.info
+ -$(RM) *.ky
+ -$(RM) *.lof
+ -$(RM) *.lot
+ -$(RM) *.pg
+ -$(RM) *.toc
+ -$(RM) *.tp
+ -$(RM) *.vr
+
+# Comment out the command line here if you don't have the doubled-word
+# utility installed. It is available via anonymous ftp from
+# ftp.math.utah.edu in pub/misc.
+dw:
+ -$(DETEX) <filehdr.ltx | dw
+
+# LaTeXinfo doesn't define ties, so we need to remove them from the
+# bibliography
+filehdr.bbl: filehdr.aux filehdr.bib
+ $(BIBTEX) filehdr
+ $(MV) filehdr.bbl /tmp/filehdr.bbl
+ $(SED) -e 's/~/ /g' </tmp/filehdr.bbl >filehdr.bbl
+
+filehdr.dvi: filehdr.ltx filehdr.bib
+ -$(MAKE) dw filehdr.spl filehdr.isp
+ $(LATEX) filehdr.ltx
+ $(MAKE) filehdr.bbl
+ $(TEXINDEX) $(INDEX-FILES)
+ $(LATEX) filehdr.ltx
+ $(TEXINDEX) $(INDEX-FILES)
+ $(LATEX) filehdr.ltx
+
+filehdr.info: filehdr.ltx
+ ./makeinfo filehdr.ltx
+
+filehdr.tar: $(DIST-FILES)
+ -$(RM) filehdr.tar filehdr.tar-lst
+ tar chf filehdr.tar $(DIST-FILES)
+ -mkdir filehdr-$(VERSION)
+ cd filehdr-$(VERSION); tar xf ../filehdr.tar
+ tar cf filehdr-$(VERSION).tar filehdr-$(VERSION)
+ -$(RM) -r filehdr-$(VERSION)
+ -$(RM) filehdr.tar
+ $(LN) filehdr-$(VERSION).tar filehdr.tar
+
+filehdr.zip: $(DIST-FILES)
+ -$(RM) filehdr*.zip
+ -$(RM) filehdr*.zip-lst
+ $(ZIP) filehdr-$(VERSION).zip $(DIST-FILES)
+ $(UNZIP) -v filehdr-$(VERSION).zip >filehdr-$(VERSION).zip-lst
+ $(LN) filehdr-$(VERSION).zip filehdr.zip
+
+filehdr.zoo: $(DIST-FILES)
+ -$(RM) filehdr*.zoo
+ -$(RM) filehdr*.zoo-lst
+ $(ZOO) a filehdr-$(VERSION).zoo $(DIST-FILES)
+ $(ZOO) v filehdr-$(VERSION).zoo >filehdr-$(VERSION).zoo-lst
+ $(LN) filehdr-$(VERSION).zoo filehdr.zoo
+
+install: DATE-INSTALLED
+
+DATE-INSTALLED: filehdr.tar filehdr.zip filehdr.zoo
+ tar tvf filehdr-$(VERSION).tar >$(FTPDIR)/filehdr-$(VERSION).tar-lst
+ $(COMPRESS) <filehdr-$(VERSION).tar >$(FTPDIR)/filehdr-$(VERSION).tar.z
+ $(CP) filehdr-$(VERSION).zip $(FTPDIR)
+ $(CP) filehdr-$(VERSION).zip-lst $(FTPDIR)
+ $(CP) filehdr-$(VERSION).zoo $(FTPDIR)
+ $(CP) filehdr-$(VERSION).zoo-lst $(FTPDIR)
+ $(CP) filehdr.el $(FTPDIR)
+ ls -l $(FTPDIR)/file*
+ date >DATE-INSTALLED
+
+filehdr.spl spell:
+ -$(DETEX) <filehdr.ltx | $(SPELL) +filehdr.sok >filehdr.spl
+ @/bin/cat filehdr.spl
+
+filehdr.isp ispell:
+ -$(DETEX) <filehdr.ltx | $(ISPELL) -l -p filehdr.sok >filehdr.isp
+ @/bin/cat filehdr.isp
diff --git a/support/filehdr/filehdr.bbl b/support/filehdr/filehdr.bbl
new file mode 100644
index 0000000000..071be8ebcc
--- /dev/null
+++ b/support/filehdr/filehdr.bbl
@@ -0,0 +1,31 @@
+\begin{thebibliography}{1}
+
+\bibitem{Beebe:TB11-4-485-487}
+Nelson H. F. Beebe.
+\newblock {{From the President}}.
+\newblock {\em TUGboat}, 11(4):485--487, November 1990.
+
+\bibitem{Lamport:LDP85}
+Leslie Lamport.
+\newblock {\em {\LaTeX}---A Document Preparation System---User's Guide and
+ Reference Manual}.
+\newblock Ad{\-d}i{\-s}on-Wes{\-l}ey, 1985.
+
+\bibitem{Lottor:CACM-34-11-21}
+Mark Lottor.
+\newblock Internet domain system.
+\newblock {\em Communications of the Association for Computing Machinery},
+ 34(11):21--22, November 1991.
+\newblock This letter reports that the ZONE program at the Network Information
+ Systems Center at SRI International in July 1991 found approximately 535,000
+ Internet hosts in 16,000 domains. The 10 largest domains were EDU
+ (educational)--206,000, COM (commercial)--144,000, GOV (government)---36,000,
+ MIL (military) 26,000, AU (Australia)--22,000, DE (Germany)---21,000, CA
+ (Canada)--19,000, ORG (organizations)---15,000, SE (Sweden)---12,000, and CH
+ (Switzerland)---10,000.
+
+\bibitem{Unilogic:SDP84}
+Unilogic, Ltd.
+\newblock {\em Scribe Document Production System User Manual}, April 1984.
+
+\end{thebibliography}
diff --git a/support/filehdr/filehdr.bib b/support/filehdr/filehdr.bib
new file mode 100644
index 0000000000..2b249b2dca
--- /dev/null
+++ b/support/filehdr/filehdr.bib
@@ -0,0 +1,89 @@
+%% /home/csc-sun/a/sy/beebe/emacs/filehdr.bib, Sat Nov 9 18:43:36 1991
+%% Edit by Nelson H. F. Beebe <beebe at jeeves.math.utah.edu>
+
+%%% ====================================================================
+%%% BibTeX-file{
+%%% author = "Nelson H. F. Beebe",
+%%% version = "1.01",
+%%% date = "12 December 1991",
+;;; time = "15:32:32 MST",
+%%% filename = "filehdr.bib",
+%%% address = "Center for Scientific Computing
+%%% Department of Mathematics
+%%% South Physics Building
+%%% University of Utah
+%%% Salt Lake City, UT 84112
+%%% USA
+%%% Tel: (801) 581-5254
+%%% FAX: (801) 581-4148",
+%%% checksum = "02007 89 349 3428",
+%%% email = "beebe at jeeves.math.utah.edu (Internet)",
+%%% codetable = "ISO/ASCII",
+%%% keywords = "file header, checksum",
+%%% supported = "yes",
+%%% docstring = "This file is the BibTeX bibliography data
+%%% base for filehdr.ltx.
+%%%
+%%% 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.",
+%%% }
+%%% ====================================================================
+
+@String{j-CACM = "Communications of the Association for Computing Machinery"}
+
+@String{j-TUGboat = "TUGboat"}
+
+@String{pub-AW = "Ad{\-d}i{\-s}on-Wes{\-l}ey"}
+
+@Article{Beebe:TB11-4-485-487,
+ author = "Nelson H. F. Beebe",
+ title = "{{From the President}}",
+ journal = j-TUGboat,
+ year = "1990",
+ volume = "11",
+ number = "4",
+ pages = "485--487",
+ month = Nov,
+}
+
+@Book{Lamport:LDP85,
+ author = "Leslie Lamport",
+ title = "{\LaTeX}---A Document Preparation System---User's
+ Guide and Reference Manual",
+ publisher = pub-AW,
+ year = "1985",
+ ISBN = "0-201-15790-X",
+}
+
+@Article{Lottor:CACM-34-11-21,
+ author = "Mark Lottor",
+ title = "Internet Domain System",
+ journal = j-CACM,
+ year = "1991",
+ volume = "34",
+ number = "11",
+ pages = "21--22",
+ month = nov,
+ note = "This letter reports that the ZONE program at the
+ Network Information Systems Center at SRI
+ International in July 1991 found approximately
+ 535,000 Internet hosts in 16,000 domains. The 10
+ largest domains were EDU (educational)--206,000, COM
+ (commercial)--144,000, GOV (government)---36,000,
+ MIL (military) 26,000, AU (Australia)--22,000, DE
+ (Germany)---21,000, CA (Canada)--19,000, ORG
+ (organizations)---15,000, SE (Sweden)---12,000, and
+ CH (Switzerland)---10,000."
+}
+
+@Manual{Unilogic:SDP84,
+ title = "Scribe Document Production System User Manual",
+ organization = "Unilogic, Ltd.",
+ year = "1984",
+ month = apr,
+}
+
diff --git a/support/filehdr/filehdr.el b/support/filehdr/filehdr.el
new file mode 100644
index 0000000000..75e4854fb8
--- /dev/null
+++ b/support/filehdr/filehdr.el
@@ -0,0 +1,1733 @@
+;;; ====================================================================
+;;; @Emacs-Lisp-file{
+;;; author = "Nelson H. F. Beebe",
+;;; version = "1.28",
+;;; date = "05 March 1996",
+;;; time = "19:04:36 MST",
+;;; filename = "filehdr.el",
+;;; 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 = "16197 1733 7127 68969",
+;;; email = "beebe@solitude.math.utah.edu (Internet)",
+;;; codetable = "ISO/ASCII",
+;;; keywords = "checksum, file header",
+;;; supported = "yes",
+;;; docstring = {This file provides functions written in GNU
+;;; Emacs Lisp for the generation of standard
+;;; file headers, like this one. The headers
+;;; resembles a BibTeX bibliography entry, with
+;;; key = "value" fields that document the file
+;;; contents.
+;;;
+;;; The only user-callable functions in this file
+;;; are these:
+;;;
+;;; 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
+;;;
+;;; Here is a quick guide to using these
+;;; functions:
+;;;
+;;; (1) See the note below about defining the
+;;; file-header-user-address variable. If
+;;; you forget to set
+;;; file-header-user-address, you'll just
+;;; get an empty string in that position.
+;;; The same applies to
+;;; file-header-user-telephone and
+;;; file-header-user-FAX.
+;;; (2) Load this file by
+;;; M-x load-file<RET>filehdr.el
+;;; or put the line
+;;; (load "/some-dir-name/filehdr.el" t t t)
+;;; in your .emacs file so you always have it
+;;; preloaded.
+;;; (3) Position the cursor to the line at which
+;;; you want the header, and type
+;;; M-x make-file-header.
+;;; (4) Fill in the empty fields, starting with
+;;; the one where the cursor is positioned.
+;;; (5) Make your edits.
+;;; (6) Type M-x update-file-header-and-save to
+;;; set the new date, version, and checksum,
+;;; and save the file.
+;;;
+;;; Here is an example of how to initialize the
+;;; file-header-user-address and related
+;;; variables in the ~/.emacs startup file;
+;;; note that line breaks are PRESERVED:
+;;;
+;;; (setq file-header-user-address
+;;; "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")
+;;;
+;;; The user personal name and electronic mail
+;;; address will be obtained automatically from
+;;; system authorization files. If the e-mail
+;;; address constructed from these is inadequate,
+;;; then you can instead set it in the variable
+;;; file-header-user-email.
+;;;
+;;; The function make-file-header generates a
+;;; header customized to the type of the file,
+;;; and to the user generating it.
+;;; make-file-header knows about most standard
+;;; file types (over 110 of them), including
+;;; vagaries like the effect of at-signs in
+;;; BibTeX files. When it is in doubt, it will
+;;; generate a UNKNOWN-file type entry.
+;;;
+;;; show-file-header-variables will show in a
+;;; temporary buffer neatly-formatted tables with
+;;; the settings of all variables named
+;;; file-header-standard-xxx and
+;;; file-header-extra-xxx.
+;;;
+;;; test-file-header will run make-file-header
+;;; for every file type in
+;;; file-header-standard-suffix-and-type and
+;;; file-header-extra-suffix-and-type to test
+;;; their correct execution.
+;;;
+;;; The function update-checksum recomputes and
+;;; set the checksum field;
+;;; update-simple-checksum is a simpler version
+;;; that does not provide the CRC-16 checksum.
+;;; It will be invoked automatically by
+;;; update-checksum on VAX VMS until code is
+;;; added to support calling the checksum
+;;; program on that operating system.
+;;;
+;;; Similarly, update-date-and-minor-version
+;;; resets the date to today, and increments
+;;; the minor version number.
+;;;
+;;; update-major-version increments the major
+;;; version, and resets the minor version to
+;;; zero.
+;;;
+;;; update-minor-version increments the minor
+;;; version.
+;;;
+;;; Finally, update-file-header-and-save
+;;; combines these to reset the date, version
+;;; and checksum, and save the file.
+;;;
+;;; The user-customizable variables are:
+;;;
+;;; file-header-extra-at-sign-special-cases
+;;; file-header-extra-comment-prefixes
+;;; file-header-extra-paired-comment-delimiter-languages
+;;; file-header-extra-suffix-and-type
+;;;
+;;; They provide additions to the built-in lists
+;;; stored in corresponding variables named
+;;; file-header-standard-xxx. Here is an example
+;;; of how you might customize them:
+;;;
+;;; (setq file-header-extra-at-sign-special-cases
+;;; '(
+;;; ("Foo-Bar" " <<<AT>>> ")
+;;; ))
+;;;
+;;; (setq file-header-extra-comment-prefixes
+;;; '(
+;;; ("Foo-Bar" "!FB!")
+;;; ))
+;;;
+;;; (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"))
+;;; ))
+;;;
+;;; These would define a new file type 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 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.}
+;;; }
+;;; ====================================================================
+;;;
+;;; filehdr.el --- support for standard file headers
+;;
+;; Author: Nelson H. F. Beebe <beebe@math.utah.edu>
+;; Created: 05-Sep-1991
+;; Version: 1.31
+;; Keywords: file header, checksum
+
+;; Copyright (C) 1993 Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 2, or (at your option)
+;; any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING. If not, write to
+;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+
+;;; Change log:
+;;
+;; NB: Don't forget to update file-header-code-version below!
+;;
+;; Version 1.29 [05-Mar-1996] {Thanks to Ulrik Vieth <vieth@thphy.uni-duesseldorf.de>
+;; Add some more TeX- and METAFONT-related file types and
+;; extensions (suggested by Ulrik Vieth), plus several dozen new
+;; types and extensions for Expect, Fortran-90, HTML, Java, Python,
+;; SGML, Scheme, STk, and Tcl.
+;;
+;; Version 1.28 [26-Jan-1996]
+;; Add new variable file-header-user-URL and new function
+;; file-header-URL, and update file-header-standard-entries to
+;; include file-header-URL, so that a user WorldWide Web URL line
+;; is generated by make-file-header.
+;;
+;; Version 1.27 [31-Oct-1993] {Thanks to Niel Kempson <kempson@snowyowl.co.uk>}
+;; Add file-header-temp-file-prefix and use it in update-checksum
+;; for creating temporary file names.
+;;
+;; Version 1.26 [22-Oct-1993]
+;; Update update-checksum to handle a nil return (meaning success)
+;; from call-process (encountered on MIPS RC6280 RISCos 2.1.1)
+;;
+;; Version 1.25 [14-Jun-1993]
+;; Update for Emacs 19. Change file-header-timezone to use
+;; current-time-zone when available. Revise comment structure to
+;; match the standards described in info node elisp -> tips ->
+;; library headers. Reformat functions according to guidelines
+;; in info node elisp -> tips -> style tips. Use message instead
+;; of princ in one place, and replace message+ding by error
+;; function.
+;;
+;; Version 1.24 [17-Nov-1992]
+;; Modify update-file-header-and-save to suppress updating
+;; minor version number if invoked with an argument.
+;;
+;; Version 1.23 [14-Nov-1992]
+;; Add code in update-date to handle Karl Berry's timestamp
+;; variant.
+;;
+;; Version 1.22 [07-Nov-1992]
+;; Install workaround in update-checksum for nasty Emacs bug
+;; that resulted in loss of the buffer for large files.
+;;
+;; Version 1.21 [04-Oct-1992]
+;; Modify update-checksum to supply a final newline if one is
+;; lacking, and to remove trailing blank lines.
+;;
+;; Version 1.20 [01-Aug-1992]
+;; Change update-date to use delete-region instead of zap-to-char
+;; so as to leave the kill ring untouched. Internationalize
+;; telephone and FAX numbers.
+;;
+;; Version 1.19 [29-May-1992] {Thanks to Alan Jeffrey
+;; <alanje@cogs.sussex.ac.uk> for suggestions.}
+;; Add abstract keyword, and additional comments in accompanying
+;; documentation about handling of multiple fields of one type.
+;;
+;; Version 1.18 [25-May-1992] {Thanks to David M. Jones
+;; <dmjones@theory.lcs.mit.edu> for some of these improvements.}
+;; Change user-xxx variables to file-header-user-xxx, and
+;; count-matches to file-header-count-matches, to avoid conflicts
+;; with other packages.
+;; Add file-header-user-email variable for more customization.
+;; Add load-time initializations of some variables that are
+;; normally set at run-time to remove undeclared-variable
+;; warnings issued by new byte-compile-file.
+;;
+;; Version 1.17 [25-Mar-1992]
+;; Use call-process instead of shell-command for getting time
+;; zone; the speedup is noticeable.
+;;
+;; Version 1.16 [07-Jan-1992]
+;; Correct minor error in setting of the variable
+;; file-header-standard-suffix-and-type for Xdefaults.
+;;
+;; Version 1.15 [30-Dec-1991]
+;; Add workaround in file-header-timezone for possible extra
+;; garbage generated by shell-command; this can happen if the
+;; shell startup file produces any output.
+;;
+;; Version 1.14 [19-Dec-1991]
+;; Add 4Dwmrc entry to file-header-standard-suffix-and-type and
+;; file-header-standard-comment-prefixes.
+;;
+;; Version 1.13 [17-Dec-1991]
+;; Replace file-header-comment-start-string by calls to
+;; file-header-comment-start; this was an unwise economization.
+;;
+;; Version 1.12 [16-Dec-1991]
+;; Add definition of file-header-comment-start-string if found to
+;; be nil in functions that use it.
+;;
+;; Version 1.11 [12-Dec-1991]
+;; Add new functions file-header-get-version-numbers and
+;; file-header-number-list, and new variables
+;; internal-file-header-prefix-version,
+;; internal-file-header-major-version, and
+;; internal-file-header-minor-version. Extend
+;; update-major-version and update-minor-version to handle zero
+;; or more dot-separated unsigned integers.
+;;
+;; Version 1.10 [11-Dec-1991]
+;; Add show-file-header-variables, internal-show-file-header-alist,
+;; and internal-show-file-header-entry.
+;; Update test-file-header to use file-header-extra-suffix-and-type
+;; values as well.
+;; Revise make-file-header to use file-header-standard-entries and
+;; file-header-extra-entries to allow better customization.
+;; Add file-header-telephone and FAX entries to
+;; file-header-standard-entries.
+;; Add functions file-header-time and file-header-timezone, and
+;; variable file-header-timezone-string, and add time to
+;; file-header-standard-entries.
+;; Make update-date handle the time as well, and insert a time
+;; entry if one is not already present.
+;;
+;; Version 1.09 [09-Dec-1991]
+;; Add a space before \\ in \date{...} so that it is preserved if
+;; the date is later used in a LaTeX page header.
+;;
+;; Version 1.08 [12-Nov-1991]
+;; Add more support for X Window System files
+;;
+;; Version 1.07 [09-Nov-1991]
+;; Add support for X Window System files
+;;
+;; Version 1.06 [02-Nov-1991]
+;; Repair stupid typo in declaration of
+;; file-header-extra-suffix-and-type.
+;;
+;; Version 1.05 [25-Oct-1991]
+;; Add support for Reduce.
+;;
+;; For all variables file-header-standard-xxx, add user
+;; customization variables file-header-extra-xxx. The extra ones
+;; are APPENDED to the standard ones, so they can augment, but not
+;; replace, them.
+;;
+;; Version 1.04 [19-Oct-1991]
+;; Add support for Basic, C Locale, and Digital Standard Runoff.
+;;
+;; Fix Scribe support.
+;;
+;; Version 1.03 [11-Sep-1991]
+;; Make file-header-date return full month names instead of
+;; 3-letter abbreviations.
+;;
+;; Version 1.02 [10-Sep-1991]
+;; Change file-header-comment-delimiter-line to only output text
+;; when the language has inline comments.
+;;
+;; Rename update-file-header-checksum to update-simple-checksum.
+;;
+;; Add update-checksum, update-date,
+;; update-date-and-minor-version, update-major-version,
+;; update-minor-version, and update-header-and-save.
+;; update-checksum will call update-simple-checksum to do the job
+;; on VAX VMS, since I have not yet added support for the calling
+;; the checksum program under VAX VMS.
+;;
+;; Introduce association list variables
+;; file-header-standard-at-sign-special-cases,
+;; file-header-standard-comment-prefixes,
+;; file-header-standard-paired-comment-delimiter-languages, and
+;; file-header-standard-suffix-and-type to simplify code and ease
+;; future additions.
+;;
+;; Modify file-header-at-sign and file-header-entry to handle at
+;; signs differently in Web files, using
+;; file-header-standard-at-sign-special-cases for the exceptional
+;; cases.
+;;
+;; Add test-file-header function for testing the code.
+;;
+;; Version 1.01 [06-Sep-1991]
+;; Change long filename from make-file-header.el to shorter
+;; filehdr.el.
+;;
+;; Add several new extensions for web, cweb, and troff.
+;;
+;; Add file-header-comment-delimiter-line and call in
+;; file-header-entry and file-header-exit to make the inserted
+;; header more visible.
+;;
+;; Add file-header-code-author and file-header-code-version
+;; variables.
+;;
+;; Version 1.00 [05-Sep-1991]
+;; First release
+;; ====================================================================
+
+(defconst file-header-code-author
+ "Nelson H. F. Beebe <beebe@math.utah.edu>"
+ "Author of code in filehdr.el")
+
+(defconst file-header-code-version nil
+ "Version number of the filehdr.el library, a collection of functions
+for the generation and maintenance of standard file headers.")
+
+(setq file-header-code-version "1.29 [05-Mar-1996]")
+;;; (setq file-header-code-version "1.28 [26-Jan-1996]")
+;;; (setq file-header-code-version "1.27 [31-Oct-1993]")
+;;; (setq file-header-code-version "1.26 [22-Oct-1993]")
+;;; (setq file-header-code-version "1.25 [14-Jun-1993]")
+;;; (setq file-header-code-version "1.24 [17-Nov-1992]")
+;;; (setq file-header-code-version "1.23 [14-Nov-1992]")
+;;; (setq file-header-code-version "1.22 [07-Nov-1992]")
+;;; (setq file-header-code-version "1.21 [04-Oct-1992]")
+;;; (setq file-header-code-version "1.20 [01-Aug-1992]")
+;;; (setq file-header-code-version "1.19 [29-May-1992]")
+;;; (setq file-header-code-version "1.18 [25-May-1992]")
+;;; (setq file-header-code-version "1.17 [25-Mar-1992]")
+;;; (setq file-header-code-version "1.16 [07-Jan-1992]")
+;;; (setq file-header-code-version "1.15 [30-Dec-1991]")
+;;; (setq file-header-code-version "1.14 [19-Dec-1991]")
+;;; (setq file-header-code-version "1.13 [17-Dec-1991]")
+;;; (setq file-header-code-version "1.12 [16-Dec-1991]")
+;;; (setq file-header-code-version "1.11 [12-Dec-1991]")
+;;; (setq file-header-code-version "1.10 [11-Dec-1991]")
+;;; (setq file-header-code-version "1.09 [09-Dec-1991]")
+;;; (setq file-header-code-version "1.08 [12-Nov-1991]")
+;;; (setq file-header-code-version "1.07 [09-Nov-1991]")
+;;; (setq file-header-code-version "1.06 [02-Nov-1991]")
+;;; (setq file-header-code-version "1.05 [25-Oct-1991]")
+;;; (setq file-header-code-version "1.04 [19-Oct-1991]")
+;;; (setq file-header-code-version "1.03 [11-Sep-1991]")
+;;; (setq file-header-code-version "1.02 [10-Sep-1991]")
+;;; (setq file-header-code-version "1.01 [06-Sep-1991]")
+;;; (setq file-header-code-version "1.00 [05-Sep-1991]")
+
+;;; Decide where temporary files should be placed. If the environment
+;;; variable TMP has been defined, we use its value. If TMP has not
+;;; been defined, we put the files in an O/S-dependent scratch
+;;; directory.
+(defvar file-header-temp-file-prefix
+ (let* ( (env (getenv "TMP"))
+ (prefix (cond
+ ((and env (> (length env) 0)) env)
+ ((eq system-type 'alpha-vms) "SYS$SCRATCH:")
+ ((eq system-type 'vax-vms) "SYS$SCRATCH:")
+ (t "/tmp/"))))
+ (cond
+ ((= (aref prefix (1- (length prefix))) ?:) nil) ;leave final colon
+ ((= (aref prefix (1- (length prefix))) ?/) nil) ;leave final slash
+ (t (concat prefix "/")))
+ prefix) ;else supply final slash
+ "*Prefix to put on temporary file names. Do not start with `~/' or
+`~user-name/'.")
+
+(defvar file-header-user-address nil
+ "*Customized personal address for make-file-header use. This should
+not include either your personal name or e-mail address, just a postal
+address.")
+
+(defvar file-header-user-email nil
+ "*Customized personal e-mail address for file-header-email use when
+the default of username@systemname is inadequate.")
+
+(defvar file-header-user-telephone nil
+ "*Customized personal telephone number(s) for make-file-header use.")
+
+(defvar file-header-user-URL nil
+ "*Customized personal WWW address for file-header-URL use when
+the default of http://systemname/~username is inadequate.")
+
+(defvar file-header-user-FAX nil
+ "*Customized personal FAX number(s) for make-file-header use.")
+
+(defconst file-header-month-abbrevs nil
+ "List of lists of pairs of month abbreviations and full names")
+
+(setq file-header-month-abbrevs
+ '(
+ ("Jan" "January")
+ ("Feb" "February")
+ ("Mar" "March")
+ ("Apr" "April")
+ ("May" "May")
+ ("Jun" "June")
+ ("Jul" "July")
+ ("Aug" "August")
+ ("Sep" "September")
+ ("Oct" "October")
+ ("Nov" "November")
+ ("Dec" "December")
+ ))
+
+;;; ====================================================================
+;;; These variables may be customized according to user requirements,
+;;; although in the interests of standardizing the file headers, it is
+;;; STRONGLY recommended that you do so ONLY through the
+;;; file-header-extra-xxx variables which augment, but do not replace,
+;;; the values stored in the file-header-standard-xxx variables.
+;;;
+;;; The values are stored as association lists so that new entries can
+;;; be easily added, or existing ones modified, by addition of short
+;;; Emacs Lisp sequences to your .emacs startup file.
+;;;
+;;; Here is how to manipulate these lists:
+;;;
+;;; Prepend an element:
+;;; (setq file-header-standard-comment-prefixes
+;;; (cons (list "foo" "@@@ ")
+;;; file-header-standard-comment-prefixes))
+;;;
+;;; Append an element:
+;;; (setq file-header-standard-comment-prefixes
+;;; (append file-header-standard-comment-prefixes
+;;; (list (list "foo" "@@@ "))))
+;;;
+;;; Delete an existing element:
+;;; (delq (assoc "Awk" file-header-standard-comment-prefixes)
+;;; file-header-standard-comment-prefixes)
+;;;
+;;; Since association lists are accessed in order first to last, if you
+;;; want to override an existing element, PREPEND it to the list.
+
+(defvar file-header-extra-at-sign-special-cases nil
+ "*List of additions to file-header-standard-at-sign-special-cases")
+
+(defvar file-header-standard-at-sign-special-cases nil
+ "*List of list of alternate representations of at sign (@) for
+certain file header name types.")
+
+(setq file-header-standard-at-sign-special-cases
+ '(
+ ("BibTeX" " at ")
+ ("C-Web" "@@")
+ ("Web" "@@")
+ ("Web-change" "@@")
+ ))
+
+(defvar file-header-extra-comment-prefixes nil
+ "*List of additions to file-header-standard-comment-prefixes.")
+
+(defvar file-header-standard-comment-prefixes nil
+ "*List of lists of file header names and comment prefixes.")
+
+(setq file-header-standard-comment-prefixes
+ '(
+ ("SGI-4D-Window-Manager-Initialization-file" "### ")
+ ("Adobe-Font-Metric" "Comment ")
+ ("AmSTeX" "%%% ")
+ ("Awk" "### ")
+ ("Basic" "REM ")
+ ("BibTeX" "%%% ")
+ ("BibTeX-style" "%%% ")
+ ("C" "")
+ ("C++" "/// ")
+ ("C-Locale" "NOTE ")
+ ("C-Web" "%%% ")
+ ("Digital-Standard-Runoff" ".!!! ")
+ ("Emacs-Lisp" ";;; ")
+ ("Encapsulated-PostScript" "%%% ")
+ ("Expect" "### ")
+ ("Font-Property-List" "")
+ ("Fortran" "C====>")
+ ("Fortran-90" "!!! ")
+ ("Ghostscript-font" "%%% ")
+ ("Gnuplot" "### ")
+ ("HTML" "--- ")
+ ("Java" "/// ")
+ ("LaTeX" "%%% ")
+ ("LaTeX-bibliography" "%%% ")
+ ("LaTeX-class" "%%% ")
+ ("LaTeX-class-option" "%%% ")
+ ("LaTeX-doc-source" "%%% ")
+ ("LaTeX-font-def" "%%% ")
+ ("LaTeX-style" "%%% ")
+ ("LaTeXinfo" "\\comment ")
+ ("Letter" ";;; ")
+ ("Lex" "")
+ ("Lisp" ";;; ")
+ ("M4" "### ")
+
+ ;; using 4 `%' helps to avoid problems when
+ ;; pretty-printing MF or MP sources with MFT
+ ("METAFONT" "%%%% ")
+ ("MetaPost" "%%%% ")
+
+ ;; it's important to have 4 `%' for MFT files
+ ;; since 3 `%' has a different meaning in MFT
+ ("MFT" "%%%% ")
+
+ ("MS-DOS-batch" ":### ")
+ ("MakeIndex-style" "%%% ")
+ ("Maple" "### ")
+ ("Matlab" "%%% ")
+ ("Mock-Lisp" ";;; ")
+ ("Modula-2" "")
+ ("Motif-Window-Manager-Initialization" "### ")
+ ("OpenLook-Window-Manager-Initialization" "### ")
+ ("Pascal" "")
+ ("Perl" "### ")
+ ("PicTeX" "%%% ")
+ ("PostScript" "%%% ")
+ ("Prolog" "/* ")
+ ("Python" "### ")
+ ("Ratfor" "### ")
+ ("Reduce" "%%% ")
+ ("SFTRAN3" "C$===>")
+ ("SGML" "--- ")
+ ("SLiTeX" "%%% ")
+ ("Scheme" ";;; ")
+ ("Scribe" "@@@ ")
+ ("STk" ";;; ")
+ ("Tab-Window-Manager-Initialization" "### ")
+ ("Tcl" "### ")
+ ("TeX" "%%% ")
+ ("TeXinfo" "@comment ")
+ ("Teco" "")
+ ("Text" "")
+ ("Tib" "### ")
+ ("Troff" ".\\\" ")
+ ("Troff-eqn" ".\\\" ")
+ ("Troff-grap" ".\\\" ")
+ ("Troff-man" ".\\\" ")
+ ("Troff-me" ".\\\" ")
+ ("Troff-mm" ".\\\" ")
+ ("Troff-ms" ".\\\" ")
+ ("Troff-pic" ".\\\" ")
+ ("Troff-refer" ".\\\" ")
+ ("Troff-tbl" ".\\\" ")
+ ("UNIX-sed" "### ")
+ ("UNIX-shell" "### ")
+ ("UNKNOWN" "")
+ ("VAX-VMS-shell" "$ !!! ")
+ ("Web" "%%% ")
+ ("Web-change" "%%% ")
+ ("X-Bitmap" "")
+ ("X-Window-System-Defaults" "!!! ")
+ ("X-Window-System-Initialization" "### ")
+ ("Yacc" "")
+ ))
+
+(defvar file-header-extra-entries nil
+ "*List of extra pairs of entry strings and functions to run to
+insert them in the file header produced by make-file-header. They
+are always inserted AFTER the standard strings.")
+
+(defvar file-header-standard-entries nil
+ "*List of standard pairs of entry strings and functions to run to
+insert them in the file header produced by make-file-header.")
+
+(setq file-header-standard-entries
+ '(
+ ("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)
+ ("abstract" file-header-abstract)
+ ("docstring" file-header-docstring)
+ ))
+
+
+(defvar file-header-extra-paired-comment-delimiter-languages nil
+ "*List of additions to
+file-header-standard-paired-comment-delimiter-languages.")
+
+(defvar file-header-standard-paired-comment-delimiter-languages nil
+ "*List of lists of language types that have paired comment
+delimiters. Each sublist consists of a string giving the language
+name, a string for file-header-comment-block-begin to insert, and a
+string for file-header-comment-block-end to insert.")
+
+(setq file-header-standard-paired-comment-delimiter-languages
+ '(
+ ("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"))
+
+ ("HTML"
+ (concat "<!-- " (make-string 67 ?\-) "\n")
+ (concat (make-string 68 ?\-) " -->\n"))
+
+ ("Lex"
+ (concat " /*" (make-string 69 ?\*) "\n")
+ (concat " " (make-string 69 ?\*) "*/\n"))
+
+ ("Modula-2"
+ (concat "(*" (make-string 70 ?\*) "\n")
+ (concat (make-string 70 ?\*) "*)\n"))
+
+ ("Pascal"
+ (concat "(*" (make-string 70 ?\*) "\n")
+ (concat (make-string 70 ?\*) "*)\n"))
+
+ ("Scribe"
+ "@Begin{Comment}\n"
+ "@End{Comment}\n")
+
+ ("SGML"
+ (concat "<!-- " (make-string 67 ?\-) "\n")
+ (concat (make-string 68 ?\-) " -->\n"))
+
+ ("Teco"
+ (concat "!*" (make-string 70 ?\*) "\n")
+ (concat (make-string 71 ?\*) "!\n"))
+
+ ("Yacc"
+ (concat " /*" (make-string 69 ?\*) "\n")
+ (concat " " (make-string 69 ?\*) "*/\n"))
+
+ ))
+
+(defvar file-header-extra-suffix-and-type nil
+ "*List of additions to file-header-standard-suffix-and-type")
+
+(defvar file-header-standard-suffix-and-type nil
+ "*List of lists of file header extension suffixes (excluding the
+leading dot), and the type names used in the file headers and
+keys of other association lists.")
+
+;;; I've included everything defined in GNU Emacs loaddefs.el for the
+;;; auto-mode-alist variable, which associates file extensions with
+;;; editing modes, plus several others.
+;;;
+;;; The list was further extended by extracting the unique file
+;;; extensions from 209K files in a large Sun file system, and 25K files
+;;; in a small IBM AIX file system. This gave about 3500 unique
+;;; extensions, which were then examined manually for other candidates.
+;;;
+;;; Please keep these entries in alphabetical order for editing
+;;; convenience
+
+(setq file-header-standard-suffix-and-type
+ '(
+ ("1" "Troff-man")
+ ("1l" "Troff-man")
+ ("2" "Troff-man")
+ ("2l" "Troff-man")
+ ("3" "Troff-man")
+ ("3l" "Troff-man")
+ ("4" "Troff-man")
+ ("4Dwmrc" "SGI-4D-Window-Manager-Initialization-file")
+ ("4l" "Troff-man")
+ ("5" "Troff-man")
+ ("5l" "Troff-man")
+ ("6" "Troff-man")
+ ("6l" "Troff-man")
+ ("7" "Troff-man")
+ ("7l" "Troff-man")
+ ("8" "Troff-man")
+ ("8l" "Troff-man")
+ ("afm" "Adobe-Font-Metric")
+ ("article" "Text")
+ ("atx" "AmSTeX")
+ ("awk" "Awk")
+ ("b" "C")
+ ("bas" "Basic")
+ ("bat" "MS-DOS-batch")
+ ("bbl" "LaTeX-bibliography")
+ ("bib" "BibTeX")
+ ("bit" "C")
+ ("bix" "Digital-Standard-Runoff")
+ ("brn" "Digital-Standard-Runoff")
+ ("bst" "BibTeX-style")
+ ("btc" "Digital-Standard-Runoff")
+ ("C" "C++")
+ ("c" "C")
+ ("c++" "C++")
+ ("CC" "C++")
+ ("cc" "C++")
+ ("cgi" "Perl")
+ ("ch" "Web-change")
+ ("clo" "LaTeX-class-option")
+ ("cls" "LaTeX-class")
+ ("com" "VAX-VMS-shell")
+ ("CPP" "C++")
+ ("cpp" "C++")
+ ("csh" "UNIX-shell")
+ ("cur" "C")
+ ("CXX" "C++")
+ ("cxx" "C++")
+ ("doc" "Text")
+ ("dtx" "LaTeX-doc-source")
+ ("el" "Emacs-Lisp")
+ ("emacs" "Teco")
+ ("eqn" "Troff-eqn")
+ ("eps" "Encapsulated-PostScript")
+ ("epsf" "Encapsulated-PostScript")
+ ("exp" "Expect")
+ ("f" "Fortran")
+ ("f77" "Fortran")
+ ("f90" "Fortran-90")
+ ("fd" "LaTeX-font-def")
+ ("flex" "Lex")
+ ("for" "Fortran")
+ ("ftn" "Fortran")
+ ("gnuplot" "Gnuplot")
+ ("grap" "Troff-grap")
+ ("gsf" "Ghostscript-font")
+ ("h" "C")
+ ("HTM" "HTML")
+ ("HTML" "HTML")
+ ("htm" "HTML")
+ ("html" "HTML")
+ ("hxx" "C++")
+ ("icn" "C")
+ ("icon" "C")
+ ("inc" "Fortran")
+ ("java" "Java")
+ ("l" "Lex")
+ ("latexinfo" "LaTeXinfo")
+ ("letter" "Letter")
+ ("lex" "Lex")
+ ("lisp" "Lisp")
+ ("lni" "Digital-Standard-Runoff")
+ ("loc" "C-Locale")
+ ("lsp" "Lisp")
+ ("ltr" "LaTeX")
+ ("ltx" "LaTeX")
+ ("m" "Matlab")
+ ("m2" "Modula-2")
+ ("m4" "M4")
+ ("man" "Troff-man")
+ ("maple" "Maple")
+ ("mat" "Matlab")
+ ("me" "Troff-me")
+ ("mec" "Digital-Standard-Runoff")
+ ("mem" "Text")
+ ("mex" "Digital-Standard-Runoff")
+ ("mf" "METAFONT")
+ ("mft" "MFT")
+ ("ml" "Mock-Lisp")
+ ("mm" "Troff-mm")
+ ("mp" "MetaPost")
+ ("ms" "Troff-ms")
+ ("mss" "Scribe")
+ ("mst" "MakeIndex-style")
+ ("mwmrc" "Motif-Window-Manager-Initialization")
+ ("n" "Troff-man")
+ ("olwmmenu" "OpenLook-Window-Manager-Initialization")
+ ("openwin-menu" "OpenLook-Window-Manager-Initialization")
+ ("p" "Pascal")
+ ("pas" "Pascal")
+ ("perl" "Perl")
+ ("pic" "Troff-pic")
+ ("pictex" "PicTeX")
+ ("pl" "Font-Property-List")
+;; ("pl" "Prolog") ;duplicate -- ignore
+ ("prolog" "Prolog")
+ ("ps" "PostScript")
+ ("px" "C")
+ ("py" "Python")
+ ("r" "Ratfor")
+ ("red" "Reduce")
+ ("refer" "Troff-refer")
+ ("rno" "Digital-Standard-Runoff")
+ ("rnt" "Digital-Standard-Runoff")
+ ("rnx" "Digital-Standard-Runoff")
+ ("scm" "Scheme")
+ ("sed" "UNIX-sed")
+ ("sf3" "SFTRAN3")
+ ("sgm" "SGML")
+ ("SGM" "SGML")
+ ("SGML" "SGML")
+ ("sgml" "SGML")
+ ("sh" "UNIX-shell")
+ ("stk" "STk")
+ ("stx" "SLiTeX")
+ ("sty" "LaTeX-style")
+ ("tbl" "Troff-tbl")
+ ("tcl" "Tcl")
+ ("teco" "Teco")
+ ("tex" "TeX")
+ ("texi" "TeXinfo")
+ ("texinfo" "TeXinfo")
+ ("text" "Text")
+ ("tib" "Tib")
+ ("twmrc" "Tab-Window-Manager-Initialization")
+ ("txi" "TeXinfo")
+ ("vpl" "Font-Property-List")
+ ("w" "C-Web")
+ ("web" "Web")
+ ("Xdefaults" "X-Window-System-Defaults")
+ ("xinitrc" "X-Window-System-Initialization")
+ ("y" "Yacc")
+ ("yacc" "Yacc")
+ ))
+
+(defvar file-header-timezone-string nil
+ "Saved time zone string. This is stored globally because getting the
+time zone is a slow process under Emacs version 18 or earlier. It
+only needs to be computed once, because most computers don't change
+time zones while they run.")
+
+(setq internal-file-header-major-version nil)
+(setq internal-file-header-minor-version nil)
+(setq internal-file-header-prefix-version nil)
+
+;=======================================================================
+
+(defun make-file-header ()
+ "Insert a standard file header comment at the start of the current
+line. The header fields are filled in with the author, date,
+filename, and email address. If the variable file-header-user-address
+is defined, each line of its contents are inserted in the address
+field as well. The value returned by file-header-comment-start is
+prefixed to each line. The cursor is left positioned in the first
+empty value string.
+
+The key = value entries that are inserted are determined by the
+contents of the lists file-header-standard-entries and
+file-header-extra-entries, which contain pairs of \"KEY\" strings and
+file-header-KEY functions to supply a value.
+
+You can customize this function by defining suitable entries for
+file-header-extra-entries."
+
+ (interactive)
+
+ (if (null (buffer-file-name))
+ (error "You must have a buffer file name set to use make-file-header!"))
+
+ (beginning-of-line)
+ (save-excursion
+ (file-header-comment-block-begin)
+ (file-header-entry)
+ (mapcar '(lambda (entry)
+ (file-header-key (car entry) (nth 1 entry)))
+ (append file-header-standard-entries file-header-extra-entries))
+ (file-header-exit)
+ (file-header-comment-block-end))
+ (search-forward "\"\"")
+ (backward-char 1))
+
+(defun show-file-header-variables ()
+ "Show the current settings of file-header-standard-xxx and
+file-header-extra-xxx variables in a temporary buffer."
+ (interactive)
+ (let ((start))
+ (with-output-to-temp-buffer "*File Header*"
+ (set-buffer "*File Header*")
+
+ (internal-show-file-header-alist
+ "Standard File Header Suffix-Type Bindings"
+ file-header-standard-suffix-and-type)
+
+ (internal-show-file-header-alist "Extra File Header Suffix-Type Bindings"
+ file-header-extra-suffix-and-type)
+
+ (internal-show-file-header-alist "Standard Comment Prefixes"
+ file-header-standard-comment-prefixes)
+
+ (internal-show-file-header-alist "Extra Comment Prefixes"
+ file-header-extra-comment-prefixes)
+
+ (internal-show-file-header-alist
+ "At Sign (@) Special Cases"
+ file-header-standard-at-sign-special-cases))))
+
+(defun test-file-header ()
+ "Select a temporary buffer, and then run make-file-header on every
+file extension defined in file-header-standard-suffix-and-type and
+file-header-extra-suffix-and-type to test its correct execution.
+Because this takes several seconds to run, each file name is displayed
+in the echo area."
+ (interactive)
+ (create-file-buffer "*Test*")
+ (set-buffer "*Test*")
+ (let ((k)
+ (suffix)
+ (suffix-and-type (append file-header-standard-suffix-and-type
+ file-header-extra-suffix-and-type)))
+ (setq k 0)
+ (while (nth k suffix-and-type)
+ (set-visited-file-name
+ (concat "foo."
+ (nth 0 (nth k suffix-and-type))))
+ (message "%s" (buffer-file-name))
+ (goto-char (point-max))
+ (insert "\f\n")
+ (make-file-header)
+ (setq k (1+ k))))
+ (switch-to-buffer (buffer-name))
+ (goto-char (point-min))
+ (message "[Done]"))
+
+(defun update-checksum ()
+ "Trim trailing whitespace from all lines in the buffer, ensure that
+the final line is terminated by a newline, remove all trailing blank
+lines, then update the checksum line in the standard file header
+generated by make-file-header, using the checksum program to compute
+it. The whitespace removal is important because some mail and file
+systems may modify it, and no reasonable text file should ever depend
+upon it."
+ (interactive)
+ (if (eq system-type 'vax-vms) ;then VAX VMS
+ (progn
+ (message "Using simple wc-style checksum on VAX VMS")
+ (update-simple-checksum))
+ (save-restriction ;else on UNIX, use checksum program
+ (widen)
+ (goto-char (point-min))
+ (replace-regexp "[ \t]+$" "") ;blank trim lines before checksumming
+ (goto-char (1- (point-max))) ;make sure last character in the
+ (if (not (looking-at "\n")) ;buffer is a newline, and
+ (progn ;supply one if necessary
+ (forward-char 1)
+ (insert "\n")))
+ (goto-char (point-max))
+ (delete-blank-lines) ;remove trailing blank lines
+ (goto-char (point-min))
+
+ ;; We used to just do
+ ;; (call-process-region (point-min) (point-max) "checksum" t t nil)
+ ;; but that fails if the region is large, leaving us with an
+ ;; empty buffer and lost text. This bug (which is really a
+ ;; deficiency in GNU Emacs, not an error in the filehdr.el code)
+ ;; first showed up 11 months after filehdr.el was written. It
+ ;; was reported by David Carlisle
+ ;; <carlisle@computer-science.manchester.ac.uk> on Thu, 29 Oct
+ ;; 1992 11:21:31. The author (NHFB) reproduced it on
+ ;; 07-Nov-1992, and prepared this fix for it.
+ ;;
+ ;; Instead, we run checksum directly using temporary files, and
+ ;; only if it is successful do we even replace the buffer. In
+ ;; order to create unique temporary file names, we include the
+ ;; mm:ss part of the current hh:mm:ss time stamp in the file
+ ;; name, keeping the filenames within the 14-character limit of
+ ;; some older UNIX systems, in the form "/tmp/FLHDRmm:ss.xyz"
+ ;;
+ ;; A process id would be better than mm:ss, but Emacs' O/S
+ ;; interface is deficient, and does not provide it.
+ ;;
+ ;; A random number would work here too; (concat (lsh (random t)
+ ;; -8)) could be used in place of (substring
+ ;; (current-time-string) 14 19). However, that would change the
+ ;; random number seed, which might interfere with other
+ ;; functions that use it.
+ ;;
+ ;; NOTE: some systems (e.g. MS-DOS, OS/2, VMS) don't like a colon
+ ;; half-way through the file specification. Change the temporary
+ ;; file spec to be in the form "$TMP/FHDRhhmmss.xyz", where $TMP
+ ;; is determined from the environment variable TMP by the variable
+ ;; file-header-temp-file-prefix.
+ ;;
+ (let* ((tmpname (concat file-header-temp-file-prefix
+ "FHDR"
+ (substring (current-time-string) 11 13)
+ (substring (current-time-string) 14 16)
+ (substring (current-time-string) 17 19)))
+ (oldname (concat tmpname ".old"))
+ (newname (concat tmpname ".new"))
+ (result))
+ (write-region (point-min) (point-max) oldname nil 0)
+ (kill-buffer
+ (get-buffer-create "*checksum*")) ;delete any current contents
+ (setq result
+ (call-process "checksum" nil (get-buffer-create "*checksum*")
+ nil oldname newname))
+ (if (null result)
+ (setq result 0))
+ (if (= 0 result)
+ (progn
+ (delete-region (point-min) (point-max))
+ (insert-file newname)
+ (goto-char (point-min))
+ (re-search-forward "checksum[ \t]*=[ \t]*\"")
+ (kill-buffer "*checksum*"))
+ (goto-char (point-min))
+ (display-buffer "*checksum*"))
+ (delete-file oldname)
+ (delete-file newname)))))
+
+
+(defun update-date ()
+ "Update a file header to set the date to today, and the time to now.
+The header is expected to contain lines like
+
+%% date = \"29 May 1991\",
+%% time = \"23:11:10 MST\",
+%% version = \"1.06\",
+
+and the body may optionally contain
+
+\\date{29 May 1991 \\
+Version 1.01}
+
+If no time entry is found, it is inserted after the date line. This is
+to update old file headers that lacked a time entry.
+
+Any leading comment prefix on the date line in the file header is ignored.
+The version number from the file header is used in the optional \\date{}
+entry in the body.
+
+A less common form
+
+%%% timestamp = \"Sat Nov 14 12:42:07 1992\",
+
+is also recognized and updated. This form is never generated by
+make-file-header."
+ (interactive)
+ (let ((major) (minor) (start))
+ (goto-char (point-min))
+ (if (re-search-forward
+ "version[ \t]*=[ \t]*\"\\([0-9]+\\)\\.\\([0-9]+\\)" nil t)
+ (progn
+ (setq major (string-to-int
+ (buffer-substring (match-beginning 1) (match-end 1))))
+ (setq minor (string-to-int
+ (buffer-substring (match-beginning 2) (match-end 2))))))
+
+ (goto-char (point-min))
+ (if (re-search-forward "date[ \t]*=[ \t]*\"" nil t)
+ (progn
+ (setq start (point))
+ (search-forward "\"")
+ (forward-char -1)
+ (delete-region start (point))
+ (insert (file-header-date))))
+
+ (goto-char (point-min))
+ (if (re-search-forward "^[ \t]*\\\\date{" nil t)
+ (progn
+ (setq start (point))
+ (search-forward "}")
+ (forward-char -1)
+ (delete-region start (point))
+ (insert (file-header-date))
+ (insert (format " \\\\\nVersion %d.%02d" major minor))))
+
+ (goto-char (point-min))
+ (if (re-search-forward "time[ \t]*=[ \t]*\"" nil t)
+ (progn
+ (setq start (point))
+ (search-forward "\"")
+ (forward-char -1)
+ (delete-region start (point))
+ (insert (file-header-time)))
+ (progn ;else no time field found
+ (goto-char (point-min)) ;so insert it after the date line
+ (if (re-search-forward "date[ \t]*=[ \t]*\"" nil t)
+ (progn
+ (forward-line 1)
+ (file-header-key "time" 'file-header-time)))))
+
+ (goto-char (point-min))
+ (if (re-search-forward "timestamp[ \t]*=[ \t]*\"" nil t)
+ (progn
+ (setq start (point))
+ (search-forward "\"")
+ (forward-char -1)
+ (delete-region start (point))
+ (insert (current-time-string))))))
+
+(defun update-date-and-minor-version ()
+ "Update a file header to set the date to today, the time to now, and
+increment the version number. The header is expected to contain lines like
+
+%% version = \"1.06\",
+%% date = \"29 May 1991\",
+%% time = \"23:11:10 MST\",
+
+and the body may optionally contain
+
+\\date{29 May 1991 \\
+Version 1.01}
+
+Any leading comment prefix on the version and date lines in the file
+header is ignored."
+ (interactive)
+ (update-minor-version) ;first bump the minor version number
+ (update-date)) ;next set the date and time
+
+(defun update-file-header-and-save ()
+ "Update the date, increment the minor version, update the checksum,
+and save the file. Use this function after completing an edit on the
+file. With an argument, the minor version is left unchanged."
+ (interactive)
+ (if (null current-prefix-arg)
+ (update-date-and-minor-version)
+ (update-date))
+ (update-checksum)
+ (save-buffer))
+
+(defun update-major-version ()
+ "Update a file header to increment the major version number, and
+reset the minor version to 0. The header is expected to contain lines
+like
+
+%% version = \"\",
+%% version = \"1\",
+%% version = \"1.06\",
+%% version = \"1.3.17\",
+%% version = \"4.7.2.13\",
+
+The major version number is the SECOND LAST number in the dotted list
+of integers. Any leading comment prefix on the version line in the
+file header is ignored."
+ (interactive)
+ (goto-char (point-min))
+ (if (re-search-forward "version[ \t]*=[ \t]*\"\\([0-9.]*\\)\"" nil t)
+ (let ( (data (match-data)) ;file-header-get-version-numbers destroys this
+ (minor) )
+ (goto-char (match-beginning 0))
+ (file-header-get-version-numbers)
+ (store-match-data data)
+ (delete-region (match-beginning 1) (match-end 1))
+ (backward-char 1) ;position between ""
+ (insert internal-file-header-prefix-version)
+ (if (not (string-equal internal-file-header-prefix-version ""))
+ (insert "."))
+ (setq internal-file-header-minor-version "0")
+ (insert (format "%d.%02d"
+ (1+ (string-to-int internal-file-header-major-version))
+ (string-to-int internal-file-header-minor-version))))))
+
+(defun update-minor-version ()
+ "Update a file header to increment the minor version number. The
+header is expected to contain lines like
+
+%% version = \"\",
+%% version = \"1\",
+%% version = \"1.06\",
+%% version = \"1.3.17\",
+%% version = \"4.7.2.13\",
+
+The minor version number is the LAST number in the dotted list of
+integers. Any leading comment prefix on the version line in the file
+header is ignored."
+ (interactive)
+ (goto-char (point-min))
+ (if (re-search-forward "version[ \t]*=[ \t]*\"\\([0-9.]*\\)\"" nil t)
+ (let ( (data (match-data)) ;file-header-get-version-numbers destroys this
+ (minor) )
+ (goto-char (match-beginning 0))
+ (file-header-get-version-numbers)
+ (store-match-data data)
+ (delete-region (match-beginning 1) (match-end 1))
+ (backward-char 1) ;position between ""
+ (insert internal-file-header-prefix-version)
+ (if (not (string-equal internal-file-header-prefix-version ""))
+ (insert "."))
+ (insert internal-file-header-major-version)
+ (if (not (string-equal internal-file-header-major-version ""))
+ (insert "."))
+ (insert
+ (format (if (string-equal internal-file-header-major-version "")
+ "%d" "%02d")
+ (1+ (string-to-int internal-file-header-minor-version)))))))
+
+(defun update-simple-checksum ()
+ "Trim trailing whitespace from all lines in the buffer, then update
+the checksum line in the standard file header generated by
+make-file-header, using a simple UNIX wc-style checksum of counts of
+lines, words, and characters.
+
+The old checksum field is left as the first entry on the kill ring, so
+you can get the text back if necessary.
+
+Tab characters are NOT expanded to blanks, but if you want the
+checksums to hold across e-mail transfers, it is wise to expand tabs
+by M-x untabify, or the UNIX expand utility, if they do not otherwise
+need to be present."
+ (interactive)
+ (save-restriction
+ (widen)
+ (goto-char (point-min))
+ (replace-regexp "[ \t]+$" "") ;blank trim lines before checksumming
+ (goto-char (point-min))
+ (if (re-search-forward " *checksum *= *\"\\([0-9 ]*\\)\"," nil t)
+ (let ((start) (end) (words) (lines) (chars))
+ (setq start (match-beginning 1))
+ (setq end (match-end 1))
+ (kill-region start end)
+ (goto-char (point-min))
+ (setq words (file-header-count-matches "[^ \t\n]+"))
+ (goto-char (point-min))
+ (setq lines (file-header-count-matches "\n"))
+ (goto-char (point-min))
+ (setq chars (+ (buffer-size) (length (format "%d" lines)) 8 8))
+ (goto-char start)
+ (insert (format "%d%8d%8d" lines (+ words 2) chars))))))
+
+;;; ====================================================================
+;;; The following functions are all private support functions for
+;;; make-file-header and update-checksum. The only ones that might
+;;; require modification are file-header-comment-start and
+;;; file-header-entry-name, which associate file extensions with header
+;;; name strings.
+
+(defun file-header-abstract ()
+ "Return as a string the default abstract value."
+ "")
+
+(defun file-header-address ()
+ "Return as a string the default address value."
+ (if (boundp 'file-header-user-address)
+ file-header-user-address ;this variable holds the default, and
+ "")) ;otherwise, we return an empty string
+
+(defun file-header-at-sign ()
+ "Return \"@\" or \" at \", according to the file extension. BibTeX 0.99
+croaks if there are @ signs anywhere except in valid BibTeX entries."
+ (let ((e (file-header-entry-name)) (s))
+ (setq s
+ (eval (nth 1
+ (assoc e
+ (append
+ file-header-standard-at-sign-special-cases
+ file-header-extra-at-sign-special-cases)))))
+ (if (null s) "@" s)))
+
+(defun file-header-author ()
+ "Return as a string the default author value."
+ (user-full-name))
+
+(defun file-header-checksum ()
+ "Return as a string the default checksum value."
+ "")
+
+(defun file-header-codetable ()
+ "Return as a string the default codetable value."
+ "ISO/ASCII")
+
+(defun file-header-comment-block-begin ()
+ "Insert a comment block begin string for languages that lack a single
+comment-from-here-to-end-of-line capability."
+ (let ((e (file-header-entry-name)) (s))
+ (setq s
+ (eval
+ (nth 1
+ (assoc (file-header-entry-name)
+ (append
+ file-header-standard-paired-comment-delimiter-languages
+ file-header-extra-paired-comment-delimiter-languages)))))
+ (if (not (null s))
+ (insert s))))
+
+(defun file-header-comment-block-end ()
+ "Insert a comment block end string for languages that lack a single
+comment-from-here-to-end-of-line capability."
+ (let ((e (file-header-entry-name)) (s))
+ (setq s
+ (eval
+ (nth 2
+ (assoc (file-header-entry-name)
+ (append
+ file-header-standard-paired-comment-delimiter-languages
+ file-header-extra-paired-comment-delimiter-languages)))))
+ (if (not (null s))
+ (insert s))))
+
+
+(defun file-header-comment-delimiter-line ()
+ "Insert a comment delimiter line to sharpen the visibility of
+the comments."
+ (let ((e (file-header-entry-name)) (s))
+ (setq s
+ (eval
+ (nth 1
+ (assoc (file-header-entry-name)
+ (append
+ file-header-standard-paired-comment-delimiter-languages
+ file-header-extra-paired-comment-delimiter-languages)))))
+ (if (null s)
+ (progn
+ (insert (file-header-comment-start))
+ (insert-char ?\= (- 72 (current-column)))
+ (insert "\n")))))
+
+(defun file-header-comment-start ()
+ "Return as a string a suitable comment start, chosen according
+to the file extension, or if that is not determinable, from the
+value of comment-start."
+
+ ;; The returned string should normally have space following it,
+ ;; and be a little more distinctive than a normal comment.
+ ;; Usually replication of the comment starter is a reasonable
+ ;; idea. We follow Lisp conventions in using tripled comment
+ ;; starters where possible.
+ ;;
+ ;; For languages like C and Pascal that require comment
+ ;; terminators, or for languages where there is no real comment
+ ;; start, return an empty string, since separate start and end
+ ;; lines will be supplied elsewhere.
+
+ (let ((entry-name (file-header-entry-name)) (s))
+ (setq s (assoc entry-name
+ (append
+ file-header-standard-comment-prefixes
+ file-header-extra-comment-prefixes)))
+ (if (null s)
+ comment-start
+ (nth 1 s))))
+
+(defun file-header-count-matches (regexp)
+ "Return number of matches for REGEXP following point."
+ ;; Code borrowed from how-many in lisp/replace.el
+ (interactive "sHow many matches for (regexp): ")
+ (let ((count 0) opoint)
+ (save-excursion
+ (while (and (not (eobp))
+ (progn (setq opoint (point))
+ (re-search-forward regexp nil t)))
+ (if (= opoint (point))
+ (forward-char 1)
+ (setq count (1+ count))))
+ count)))
+
+(defun file-header-date ()
+ "Return as a string the default date value in the form \"23 January 1991\"."
+ (let ((cts (current-time-string)))
+ (concat
+ (if (equal (substring cts 8 9) " ")
+ "0"
+ (substring cts 8 9))
+ (substring cts 9 10) ;get "dd"
+ " "
+ (nth 1 (assoc (substring cts 4 7)
+ file-header-month-abbrevs)) ;expand "mon" to full name
+ " "
+ (substring cts 20 24)))) ;get "yyyy"
+
+(defun file-header-docstring ()
+ "Return as a string the default docstring value."
+ (if (eq system-type 'vax-vms) ;on VAX VMS, get only simple checksum
+ ;from update-checksum
+ "The checksum field above contains the
+standard UNIX wc (word count) utility
+output of lines, words, and characters;
+eventually, a better checksum scheme should
+be developed."
+ ;else on UNIX, get CRC-16 + wc style
+ ;from update-checksum
+ "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."))
+
+(defun file-header-email ()
+ "Return as a string the default email value."
+ (or file-header-user-email
+ (concat (user-login-name) (file-header-at-sign) (system-name)
+ " (Internet)")))
+
+(defun file-header-entry ()
+ "Insert a file header entry line, choosing the entry name according to
+the filename extension."
+ (file-header-comment-delimiter-line)
+ (insert (file-header-comment-start)
+ " "
+ (if (string-equal (file-header-at-sign) " at ")
+ "" (file-header-at-sign))
+ (file-header-entry-name)
+ "-file{\n"))
+
+(defun file-header-entry-name ()
+ "Return a file header entry name, chosen according to the
+file extension."
+ (let ((ext (file-name-extension
+ (file-name-sans-versions (buffer-file-name))))
+ (s))
+ (setq s (assoc ext
+ (append file-header-standard-suffix-and-type
+ file-header-extra-suffix-and-type)))
+ (if (null s)
+ "UNKNOWN"
+ (nth 1 s))))
+
+(defun file-header-exit ()
+ "Insert a file header exit line."
+ (insert (file-header-comment-start)
+ " }\n")
+ (file-header-comment-delimiter-line))
+
+(defun file-header-FAX ()
+ "Return as a string the default user FAX number."
+ (if (boundp 'file-header-user-FAX)
+ file-header-user-FAX ;this variable holds the default, and
+ "")) ;otherwise, we return an empty string
+
+(defun file-header-filename ()
+ "Return as a string the default filename value. The directory
+name is excluded since it is often dependent on the local installation."
+ (file-name-nondirectory (buffer-file-name)))
+
+(defun file-header-get-version-numbers ()
+ "Search for a line of the form
+ version = \"1.20.3.17\"
+where there are zero or more dot-separated unsigned integers in the
+value string, and set global variables internal-file-header-major-version and
+internal-file-header-minor-version to the string values of the last two
+numbers, and internal-file-header-prefix-version to the complete prefix string.
+Some of these may be empty strings. The list of numbers is returned
+as the function value, e.g. (\"1\" \"20\" \"3\" \"17\")."
+ (if (re-search-forward
+ "version[ \t]*=[ \t]*\"\\([0-9.]*\\)\""
+ nil t)
+ (let* ((the-list (file-header-number-list
+ (buffer-substring (match-beginning 1) (match-end 1))))
+ (n (length the-list))
+ (k 0))
+ (cond ;switch on the count of numbers found
+ ((= n 0) ;"" (empty string)
+ (setq internal-file-header-major-version "")
+ (setq internal-file-header-minor-version ""))
+ ((= n 1) ;"1"
+ (setq internal-file-header-major-version "")
+ (setq internal-file-header-minor-version (nth 0 the-list)))
+ ((= n 2) ;"1.2"
+ (setq internal-file-header-major-version (nth 0 the-list))
+ (setq internal-file-header-minor-version (nth 1 the-list)))
+ (t ;"1.2.3" or more
+ (setq internal-file-header-major-version (nth (- n 2) the-list))
+ (setq internal-file-header-minor-version (nth (- n 1) the-list))))
+
+ (setq internal-file-header-prefix-version "") ;everything but last
+ ;two numbers
+
+ (while (< k (- n 2))
+ (setq internal-file-header-prefix-version
+ (concat internal-file-header-prefix-version
+ (if (string-equal
+ internal-file-header-prefix-version "")
+ "" ".")
+ (nth k the-list)))
+ (setq k (1+ k)))
+ the-list)))
+
+(defun file-header-insert-multiline-string (value indent-column)
+ "Insert a possibly multiline string, VALUE, providing a leading comment
+string and blank padding to column INDENT-COLUMN."
+ (let ( (k 0) )
+ (while (< k (length value))
+ (insert-char (aref value k) 1)
+ (if (= (aref value k) ?\n)
+ (progn
+ (insert (file-header-comment-start))
+ (insert (make-string (- indent-column (current-column)) ?\ ))))
+ (setq k (1+ k)))))
+
+
+(defun file-header-key (key value)
+ "Insert a file header key = \"value\" line, using the constant
+string KEY for the key name, and the function VALUE to get the value
+string. If the string contains newlines, additional comment starters
+and indentation are supplied."
+ (insert (file-header-comment-start)
+ " "
+ key) ;complete key insertion so current-column is up-to-date
+ (insert (make-string
+ (if (> (- 24 (current-column)) 0)
+ (- 24 (current-column))
+ 1)
+ ?\ )
+ "= \"")
+ (file-header-insert-multiline-string (funcall value) 27)
+ (insert "\",\n"))
+
+(defun file-header-keywords ()
+ "Return as a string the default keywords value."
+ "")
+
+(defun file-header-number-list (s)
+ "Given a string S matching a series of unsigned integers separated
+by dots, return a list of those integers."
+ (let ((k 0) (n (length s)) (element nil) (number-list nil) (sk))
+ (while (< k n)
+ (setq sk (char-to-string (aref s k)))
+ (cond
+ ((string-match "[0-9]" sk)
+ (setq element (concat element sk)))
+ ((string-match "\\." sk)
+ (setq number-list (append number-list (list element)))
+ (setq element nil))
+ (t
+ (error "Bad version string [%s]" s)))
+ (setq k (1+ k)))
+ (setq number-list (append number-list (list element)))
+ (if (equal number-list (list nil))
+ (setq number-list nil))
+ number-list))
+
+(defun file-header-supported ()
+ "Return as a string the default supported value."
+ "yes"
+ )
+
+(defun file-header-telephone ()
+ "Return as a string the default user telephone number."
+ (if (boundp 'file-header-user-telephone)
+ file-header-user-telephone ;this variable holds the default, and
+ "")) ;otherwise, we return an empty string
+
+(defun file-header-time ()
+ "Return as a string the current time."
+ ;; current-time-string returns
+ ;; "Tue Feb 9 17:06:20 1988"
+ ;; 0123456789.123456789.123
+ (let ((timezone (file-header-timezone)))
+ (concat (substring (current-time-string) 11 19)
+ (if (string-equal timezone "")
+ ""
+ (concat " " timezone)))))
+
+(defun file-header-timezone ()
+ "Return as the string the local time zone abbreviation. Until Emacs
+version 19, this is not available from Emacs, so we have to invoke a
+shell to get it, which is, alas, slow. We save the result in a global
+variable so we can return it rapidly on later calls."
+ (cond
+ ((not (null file-header-timezone-string))) ;do nothing if already set
+ ((eq system-type 'vax-vms) ;cannot get it on VAX VMS
+ (setq file-header-timezone-string "")) ;no timezone available
+ ((null file-header-timezone-string) ;no saved timezone
+ (if (fboundp 'current-time-zone) ;then Emacs 19
+ (setq file-header-timezone-string (nth 1 (current-time-zone)))
+ (get-buffer-create "*timezone*") ;else Emacs 18 or earlier
+ (save-excursion
+ (set-buffer "*timezone*")
+ (delete-region (point-min) (point-max))
+ (message "Getting time zone...this will take a few seconds")
+ (sit-for 2) ;shell-command produces a Mark Set
+ ;message that wipes out this one,
+ ;so wait for it to be seen
+ ;; (shell-command "date" t) ;this is too slow
+ (call-process "date" nil t) ;this is pretty fast
+ ;; DECstation ULTRIX returns extra lines of garbage "Where are you?"
+ ;; so delete all but last line (which has the date command output)
+ (goto-char (point-max))
+ (forward-line -1)
+ (delete-region (point-min) (point))
+
+ ;; UNIX date returns:
+ ;; Wed Dec 11 14:32:18 MST 1991
+ ;; 123456789.123456789.123456789
+ (setq file-header-timezone-string (buffer-substring 21 24)))
+ (kill-buffer "*timezone*")
+ (message "Time zone saved"))))
+ file-header-timezone-string)
+
+(defun file-header-URL ()
+ "Return as a string the default URL value. If the variable
+file-header-user-URL is not set, on UNIX, we assume that the
+World-Wide Web host name for local host a.b.c.d is www.b.c.d, provided
+that that name can be found in the file /etc/hosts."
+ (let ((k) (www-name))
+ (save-excursion
+ (setq www-name (system-name))
+ (if (file-exists-p "/etc/hosts")
+ (progn
+ ;; Reduce a.b.c.d to .b.c.d, and prefix www.
+ (setq k 0)
+ (while (< k (length www-name))
+ (progn
+ (if (string-equal (substring www-name k (1+ k)) ".")
+ (progn
+ (setq www-name (concat "www" (substring www-name k)))
+ (setq k (length www-name)))) ;to force loop exit
+ (setq k (1+ k))))
+ ;; Now see whether this name exists
+ (find-file "/etc/hosts")
+ (goto-char (point-min))
+ (if (not (search-forward www-name nil t))
+ (setq www-name "???"))
+ (kill-buffer nil)))
+ (or file-header-user-URL
+ (concat "http://" www-name "/~" (user-login-name))))))
+
+(defun file-header-version ()
+ "Return as a string the default version value."
+ "")
+
+(defun file-name-extension (filename)
+ "Return the extension of FILENAME, minus the leading period (e.g.
+the call (file-name-extension \"foo.bar\") returns \"bar\"). If there
+is no extension, nil is returned."
+ (let (n)
+ (setq n (1- (length filename)))
+ (>= n 0)
+ (while (and (>= n 0) (not (= (aref filename n) ?.)))
+ (setq n (1- n)))
+ (if (< n 0)
+ nil
+ (substring filename (1+ n)))))
+
+(defun internal-show-file-header-alist (the-title the-list)
+ "Insert into the current buffer THE-TITLE followed by the entries of
+THE-LIST, one per line, in sorted order."
+ (insert-char ?\= (length the-title))
+ (newline)
+ (insert the-title "\n")
+ (insert-char ?\= (length the-title))
+ (newline)
+ (let ((start (point)))
+ (mapcar 'internal-show-file-header-entry the-list)
+ (newline)
+ (sort-lines nil start (point))
+ (goto-char (point-max))
+ (newline 2)))
+
+(defun internal-show-file-header-entry (entry)
+ "Insert an entry pair in the current buffer, where entry looks
+like (\"extension\" \"class\")."
+ (insert (format "%-39s\"%s\"\n" (car entry) (car (cdr entry)))))
+
+;;; This is for GNU Emacs file-specific customization:
+;;; Local Variables:
+;;; indent-tabs-mode: nil
+;;; End:
+;;; filehdr.el ends here
diff --git a/support/filehdr/filehdr.info b/support/filehdr/filehdr.info
new file mode 100644
index 0000000000..170db05671
--- /dev/null
+++ b/support/filehdr/filehdr.info
@@ -0,0 +1,1940 @@
+Info file: filehdr.info, -*-Text-*-
+produced by latexinfo-format-buffer
+from file: filehdr.ltx
+
+
+
+
+File: filehdr.info Node: Top, Prev: Variable Index, Up: (dir), Next: Licensing information
+
+This file documents version 1.28 of the standard file header support
+package for GNU Emacs, version 18 or later.
+
+Copyright (C) 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+
+
+* Menu:
+
+* Licensing information:: Conditions for use
+* Author and version:: Who wrote this
+* Background:: The origins of all of this
+* What's in a header?::
+* Putting it all together::
+* Outline of file headers::
+* Attribute descriptions:: Details of attributes
+* GNU Emacs editing support:: Letting Emacs do the work for you
+* Simple customization:: Changing things the easy way
+* Advanced customization:: Changing things the hard way
+* Bug reporting:: How to report bugs, comments, etc.
+* Bibliography:: Literature references
+* Concept Index:: General topic index
+* Function Index:: Lisp functions
+* Person Index:: Individuals cited in this text
+* Program Index:: Operating system programs
+* Variable Index:: Lisp variables
+
+
+
+File: filehdr.info Node: Licensing information, Prev: Top, Up: Top, Next: Author and version
+
+
+Licensing information
+*********************
+
+
+
+The program currently being distributed that relates to standard file
+headers is contained in the file `filehdr.el'. It consists of numerous
+support functions for to the creation and maintenance of file headers.
+This program is "free"; this means that everyone is free to use it and
+free to redistribute it on a free basis.
+
+Specifically, we want to make sure that you have the right to give away
+copies of the programs that relate to `filehdr.el', that you receive
+source code or else can get it if you want it, that you can change these
+programs or use pieces of them in new free programs, and that you know
+you can do these things.
+
+To make sure that everyone has such rights, we have to forbid you to
+deprive anyone else of these rights. For example, if you distribute
+copies of the file `filehdr.el', you must give the recipients all the
+rights that you have. You must make sure that they, too, receive or can
+get the source code. And you must tell them their rights.
+
+Also, for our own protection, we must make certain that everyone finds
+out that there is no warranty for the programs that relate to
+`filehdr.el'. If these programs are modified by someone else and passed
+on, we want their recipients to know that what they have is not what we
+distributed, so that any problems introduced by others will not reflect
+on our reputation.
+
+The precise conditions of the licenses for the programs currently being
+distributed that relate to `filehdr.el' are found in the General Public
+Licenses that accompany them. The programs that are part of GNU Emacs
+are covered by the GNU Emacs copying terms (*Note License:
+(emacs)License.), and other programs are covered by licenses that are
+contained in their source files.
+
+
+File: filehdr.info Node: Author and version, Prev: Licensing information, Up: Top, Next: Background
+
+The GNU Emacs Lisp file `filehdr.el' was developed by
+
+Nelson H. F. Beebe
+Center for Scientific Computing
+Department of Mathematics
+University of Utah
+Salt Lake City, UT 84112
+USA
+Tel: +1 801 581 5254
+FAX: +1 801 581 4148
+E-mail: beebe@math.utah.edu
+URL: http://www.math.utah.edu/~beebe
+
+in the summer of 1991, and contributed to the Free Software Foundation.
+
+This documentation corresponds to version 1.28 of `filehdr.el'. This
+should match the code version that is stored in the Emacs variable
+`file-header-code-version'. The author information is similarly stored
+in the variable `file-header-code-author'.\c
+\vindex{file-header-code-author}
+
+
+
+File: filehdr.info Node: Background, Prev: Author and version, Up: Top, Next: What's in a header?
+
+
+Background
+**********
+
+
+With the rapid spread of the global Internet, which by 1991 reaches more
+than a half-million computersall around the world
+[Lottor:CACM-34-11-21], the opportunities for free exchange of software
+and textual data are greatly enhanced.
+
+While this brings exciting new capabilities to many people, not just
+those involved in academic research, it is hampered by several factors.
+
+First, not all network file exchange is error-free. Electronic
+mailsystems in particular are notorious for corrupting information,
+either by truncation of lines or message bodies, or by transliteration
+or other altering of certain characters. These problems are most severe
+for mail exchanges *between* major networks, such as between the
+Internet and Usenet or Bitnet.\c
+
+Second, no standards yet exist for describing the contents of files.
+While this is an area of research at some academic institutions, the
+wide variety of operating systems in use, and the growing numbers of
+computers (approaching 100 million on a world-wide basis in 1991),
+suggest that such standards may never exist, any more than products on
+the commercial market, from soup to saltines, have standard labels.
+
+Third, without a record of origin of software and data, it is impossible
+for users to verify that they have up-to-date copies, or to contribute
+improvements and additions back to the original authors.
+
+Fourth, without a standard means of encoding information in file
+headers, there is no hope of automating the process of collecting
+information from file headers to produce enhanced file archive
+summaries, catalogs, and the like.
+
+During the author's 1991--92 tenure as President of the TeX Users Group,
+efforts were undertaken to improve the quality and quantity of
+electronic distribution of TeX-related software and data. While this
+work had a narrow focus, it has quite general ramifications, and the GNU
+Emacs support code here is quite general, and capable of handling almost
+any type of computer-readable textual material.
+
+It does *not*, however, address the issue of exchange of binary
+(non-textual) data; that has a number of difficulties associated with
+it, the two most severe being rigid formats intolerant of extension, and
+machine-specific encoding and byte order.
+
+During a visit to Heidelberg University in June 1990, the author spent a
+pleasant brain-storming session that lasted until 3am with a dozen
+colleagues (who names, alas, were unrecorded) from Heidelberg, Mainz,
+Darmstadt, and Goettingen.
+
+We discussed many things that evening, but one topic in particular led
+to this work: an informal proposal for standard file headers that could
+address all of the problems noted above.
+
+
+File: filehdr.info Node: What's in a header?, Prev: Background, Up: Top, Next: Putting it all together
+
+
+What's in a header?
+*******************
+
+The BibTeX system for support of bibliographic data bases was developed
+by Oren Patashnik at Stanford University, based on earlier work by Brian
+Reid at Carnegie Mellon University on the Scribe document formatting
+system [Unilogic:SDP84]. BibTeX is described in Leslie Lamport's book
+[Lamport:LDP85] on LaTeX. It is based on the notion that bibliographic
+items can be divided into distinct *classes*: articles, books, reports,
+theses, and so on.
+
+Each class of documents has certain features in common. For example,
+journal articles have authors, titles, volume numbers, often issue
+numbers, page numbers, and dates of publications. Theses and reports
+would have the name of an institution attached.
+
+The number of classes of documents is not fixed; indeed, it may change
+with time, or between cultures and languages. Thus, a bibliographic
+system must be *extensible*. BibTeX provides this critical feature by
+an implementation in a programming language that knows how to parse the
+general structure of a bibliographic data base entry, without particular
+knowledge of the classes, or attributes of classes. That information is
+instead encoded in a *style file*, which is written in a much more
+compact form that is specialized for its job, and is presumably easier
+for users to change than BibTeX itself is.
+
+The style file can specify which attributes are required to be present
+in a class (e.g. a Ph.D. thesis must have an institution), and which
+attributes are optional (a book may or may not have an International
+Standard Book Number, ISBN).
+
+Some styles may not require all attributes in a particular class, so
+BibTeX simply *ignores* attributes not required by the current style,
+checking them only cursorily for proper syntax.
+
+In addition, the style file can specify how individual bibliographic
+entries extracted by BibTeX from data base files are to be formatted.
+In a typesetting application, this flexibility is important, because
+there are a great many bibliography formatting styles, and each journal
+or publisher often has rather strict (and arbitrary) rules that authors
+must adhere to.
+
+How does this relate to the question of file headers?
+
+Clearly, the notion of classes and attributes applies to all computer
+files as well. The class is the file type, such as Lisp file, Pascal
+code file, and national census data file. The attributes are things
+like author(s), author's address, date of last modification, file name,
+revision history, character set name, and so on.
+
+In many operating systems, file naming conventions have been adopted by
+which the name encodes information about the class to which the file
+belongs. For example, if the file name ends in `.c', it is assumed to
+contain code written in the C programming language. Unfortunately, few
+file systems are general enough to permit the creators of computer files
+to encode additional header information that might be more detailed.
+
+Since this additional information cannot be standardly encoded in the
+file system, it must be supplied in some way inside the files
+themselves. This is not universally possible, particularly with binary
+files.
+
+However, textual data tends to be much more portable between computer
+systems, and all reasonable programming languages and text processing
+systems make some provision for *comments*, that is, explanatory
+material inserted into the file which is otherwise ignored by the
+program which processes the file.
+
+Such comments are generally identified by a unique start symbol,
+followed by the comment text, and a unique end symbol.
+
+The start symbol is usually a particular special character, or special
+short character sequence, not otherwise required in the language in
+which the file is encoded. Sometimes the start symbol must begin in a
+certain column of the line, such as Fortran's `C' or `*' in column 1, or
+is implicitly present at a certain column (assembly languages for older
+computers often decreed something like "a comment starts in column 32 of
+the input record").
+
+The end symbol is frequently an end-of-line condition, which need not be
+an actual character. This convention is simple, but limits comments to
+single lines. If a comment end symbol other than end-of-line is chosen,
+the comment body may span multiple lines. Thus, the PL/1 and C
+programming languages delimit comments by `/*' and `*/', and Pascal by
+`(*' and `*)', or by paired braces. Some programming languages even
+permit comments to be properly *nested*, so that one can comment out a
+block of code that itself contains comments.
+
+Ideally, a comment syntax should be simple, yet permit *any*
+processor-representable characters to appear in the comment text, so as
+not to hinder freedom of expression.
+
+In any event, with most programming languages, we should be able to
+encode file header information as comments in such a way that expression
+is not restricted, yet both humans and suitable computer programs can
+recognize the presence of the file header.
+
+
+File: filehdr.info Node: Putting it all together, Prev: What's in a header?, Up: Top, Next: Outline of file headers
+
+
+Putting it all together
+***********************
+
+
+The preceding sections have outlined the notions of *classes*,
+*attributes*, and *comment embedding*. What we want to do is to borrow
+the syntax used by BibTeX for bibliography data base files, and encode
+the file header as comment body text in whatever syntax the programming
+language allows, but to do so in such a way that it can be readily
+recognized by both humans and computer programs.
+
+Thus, in a Fortran file, for which comments run from a `C' in column 1
+to end of line, our file header might look something like this:
+
+C @Class{
+C attribute1 = "value1",
+C attribute2 = {value2},
+C attribute3 = {value3 with {extra braces}},
+C attribute4 = {value4 with "quotation marks"},
+C attribute5 = "value5 with ""quotation marks""",
+C ...
+C }
+
+The key to programmatic recognition of the header is the syntax *name
+followed by an opening brace, zero or more attribute assignments, and a
+closing brace*. The attribute value fields can be enclosed in quotation
+marks, or balanced braces, as shown above.
+
+In the event that braces otherwise have special significance (such as in
+one of Pascal's comment forms), other distinct paired delimiters could
+be used; in the ASCII character set, this means parentheses, square
+brackets, or angle brackets.
+
+The order of attributes is significant only in the event of
+duplications; in such a case, the *last* value assignment is the one to
+be used. Conventions for the order of attributes will make file headers
+easier to read, however.
+
+Readers familiar with BibTeX will note the absence of a *tag* following
+the opening brace. In the bibliography data base application, the tag
+serves as a unique citation key that can be placed in other documents to
+uniquely identify the bibliographic reference. In the current
+application for file headers, we have no need of such a tag.
+
+For languages in which comments continue from a start symbol to end of
+line, it will be useful, though not essential, to make the comment
+section containing the file header more visible. This can be done in a
+variety of ways, such as by doubling or tripling the comment start
+symbol, or putting a distinctive character sequence, like several
+asterisks or an arrow, `==>', after it. The essential point is that if
+each line begins with a comment start symbol, *that same prefix must be
+used on every line of the header*. Not only does this enhance
+visibility, it makes it possible for a relatively simple computer
+program to identify the first line of the header and recognize the
+comment syntax automatically, and then collect the remainder of the
+header by discarding identical comment prefixesfrom succeeding lines
+until a complete header has been collected.
+
+
+File: filehdr.info Node: Outline of file headers, Prev: Putting it all together, Up: Top, Next: Attribute descriptions
+
+
+Outline of file headers
+***********************
+
+This chapter briefly describes what the file headers contain: class
+names, attribute names, and attribute values. Each is treated in a
+separate section. Detailed descriptions of attributes will be found in
+the next chapter (*Note Attribute descriptions::).
+
+* Menu:
+
+* Class names::
+* Attribute names::
+* Attribute values::
+
+
+
+File: filehdr.info Node: Class names, Prev: Outline of file headers, Up: Top, Next: Attribute names
+
+
+Class names
+===========
+
+What should the class name in a file header be? We want it to be
+indicative of the file contents, even to a reader unfamiliar with the
+computer system from which it originated. Here are some desirable
+criteria:
+
+ * The class name should *not* be restricted by the length constraints
+ of many file systems, and it should not use abbreviations, because
+ they are often unintelligible to readers unfamiliar with the
+ originating computer system, or with the language in which the
+ header is written.
+
+ * It must also be possible to generate the class name automatically
+ from knowledge of what the file name is, at least for those many
+ classes of files that are distinguished by particular phrases in
+ their file names.
+
+ * Class names must be standard across different operating systems, so
+ that when files are moved between such systems, they can be readily
+ associated with the correct class.
+
+ * Class names must be recognizable by a simple computer program, and
+ thus must conform to an agreed-upon syntax.
+
+
+I therefore propose that class names consist of an optional at-sign,
+`@', immediately followed by an initial letter, optionally followed by
+letters, digits, and hyphens, followed by the phrase `-file'.
+
+Letter case may be mixed for readability, *but is not otherwise
+significant*: `@LATEX-FILE' and `@LaTeX-file' represent the same file
+class.
+
+This style of naming is common to many programming languages. Hyphens
+between words improve readability, while avoiding ambiguities introduced
+when spaces are allowed to be part of names.
+
+
+File: filehdr.info Node: Attribute names, Prev: Class names, Up: Top, Next: Attribute values
+
+
+Attribute names
+===============
+
+What file header attributes do we need? Here are several that are
+desirable: abstract, author(s), checksum, code table, date,
+documentation, filename, keywords (for later indexing and
+cross-referencing), postal, electronic mail, and WorldWide Web
+addresses, and version.
+
+Attribute names have the same syntax as class names, except that an
+at-sign, `@', is never present. New attribute names can be added as
+needed, with the understanding that the file header processing software
+will ignore attributes that it has not been programmed to deal with.
+
+
+File: filehdr.info Node: Attribute values, Prev: Attribute names, Up: Top, Next: Outline of file headers
+
+
+Attribute values
+================
+
+What about attribute values? These are for the most part arbitrary text
+strings, usually delimited by quotation marks. In the event that
+quotation marks are needed in the text itself, braces (or parentheses,
+square brackets, or angle brackets) may be used instead, provided that
+they are properly nested. The value text should *not* presuppose the
+existence of any particular text formatting system;in particular, it
+should be understandable to a human reader when it is displayed in the
+95 printable characters of the ASCII character set.
+
+Attribute values may span multiple lines, and in most cases, newlines
+can be treated like spaces.However, file header processing software
+*must* distinguish between spaces and newlines, and in some cases, such
+as for address values, newlines will be preserved in the output.
+
+Since file headers are encoded inside language comments, each line will
+often begin with a comment start symbol and white space chosen to
+provide neat formatting of the header to enhance its readability. Thus,
+after stripping the comment start symbol, leading white space (blanks
+and horizontal tabs) may be ignored.\c
+
+File header processing software *may* choose to eliminate common prefix
+strings consisting of a comment start symbol and following white space
+from successive lines of a single value, but preserve additional
+indentation space. Thus, the input
+
+;;; name = "Blah blah blah blah blah blah
+;;; blah blah blah blah blah blah.
+;;;
+;;; Blah blah blah blah blah.
+;;; blah blah blah blah blah blah.
+;;;
+;;; Blah blah blah blah blah."
+
+could produce the value string
+
+Blah blah blah blah blah blah
+blah blah blah blah blah blah.
+
+ Blah blah blah blah blah.
+blah blah blah blah blah blah.
+
+ Blah blah blah blah blah.
+
+if common prefixes are stripped, or
+
+Blah blah blah blah blah blah
+blah blah blah blah blah blah.
+
+Blah blah blah blah blah.
+blah blah blah blah blah blah.
+
+Blah blah blah blah blah.
+
+if all leading white space is discarded.
+
+BibTeX adopts that convention that braced groups inside a value string
+are protected from certain actions, such as letter case conversion, or
+sorting. In particular, a single quotation mark may be enclosed in
+braces to prevent its recognition as a value string terminator, assuming
+the string was started by a quotation mark. Since BibTeX expects that
+its output will be processed by the TeX typesetting system, where braces
+serve as grouping commands, and are not normally themselves printable,
+this is a reasonable choice: the value string `"A quotation mark, {"},
+must be braced"' will be reduced by TeX to `A quotation mark, ", must be
+braced'.
+
+In the context of general file headers, this convention is not
+reasonable, because the value strings will not in general be processed
+by TeX, but instead, will be treated as verbatim strings.
+
+Similarly, although the C programming language has character escape
+conventions to permit encoding of non-printable characters in printable
+form, such as `\n' for newline and `\t' for horizontal tab, such usages
+are undesirable in the context of general file headers that must serve
+for many different programming languages and file types.
+
+Several programming languages adopt the convention that a quote inside a
+quoted string is represented by an adjacent pair of quotes. This
+convention is easy to understand, requires no additional escape
+characters, and permits unrestricted representation of all printable
+characters, and of course, white space (blanks and horizontal tabs). We
+adopt this convention for attribute value strings, but note that since
+balanced braces (parentheses, square brackets, angle brackets) can also
+be used to delimit value strings, the need for such doubling will be
+rare.\c
+
+
+File: filehdr.info Node: Attribute descriptions, Prev: Attribute values, Up: Top, Next: GNU Emacs editing support
+
+
+Attribute descriptions
+**********************
+
+In this chapter, we go into the details of each of the currently-defined
+attributes in a standard file header. Attributes are treated in
+alphabetical order in the following sections; they need not occur in
+that order in file headers.
+
+* Menu:
+
+* abstract::
+* address::
+* author::
+* checksum::
+* codetable::
+* date::
+* docstring::
+* email::
+* FAX::
+* filename::
+* keywords::
+* supported::
+* telephone::
+* time::
+* URL::
+* version::
+* multiple values::
+
+
+
+File: filehdr.info Node: abstract, Prev: Attribute descriptions, Up: Attribute descriptions, Next: address
+
+
+Abstract
+========
+
+The `abstract' attribute can supply a short abstract string to
+complement the longer `docstring' entry. This should normally be
+limited to a single paragraph.
+
+For example, large research institutes often prepare an annual
+publication list with abstracts of documents prepared by staff members.
+With care in the preparation of the file headers, and suitable software
+support, much of that annual report could be extracted automatically
+from the file headers.
+
+
+File: filehdr.info Node: address, Prev: abstract, Up: Attribute descriptions, Next: author
+
+
+Address
+=======
+
+The `address' attribute should have a postal address. Be sure to
+include a country in your address; your file may be shared with users
+all around the world.
+
+Here is an example from the file header for this document:
+
+%%% address = "Center for Scientific Computing
+%%% Department of Mathematics
+%%% University of Utah
+%%% Salt Lake City, UT 84112
+%%% USA",
+
+
+File: filehdr.info Node: author, Prev: address, Up: Attribute descriptions, Next: checksum
+
+
+Author
+======
+
+The `author' attribute should give the full name of the author, in the
+order as it is conventionally spoken. In much of the Western world, the
+family name goes last.
+
+If there are multiple authors, separate them by the word `and', rather
+than by commas. The reason for this is that BibTeX has special
+algorithms that use this convention to allow parsing of names in some
+foreign languages, as well as names with qualifiers, like `Jr.', and
+those algorithms could be adapted by other programs that process file
+headers. Even simple programs could separate the names by splitting at
+the word `and'.
+
+Here is the `author' attribute from this document's file header:
+
+%%% author = "Nelson H. F. Beebe",
+
+
+File: filehdr.info Node: checksum, Prev: author, Up: Attribute descriptions, Next: codetable
+
+
+Checksum
+========
+
+The background chapter (*Note Background::) noted that it is important
+to be able to verify the correctness of files that are moved between
+different computing systems. The way that this is traditionally handled
+is to compute a number which depends in some clever way on all of the
+characters in the file, and which will change, with high probability, if
+any character in the file is changed. Such a number is called a
+*checksum*.\c
+
+Good algorithms for computing checksums are not obvious. One
+possibility is to count up the number of characters, words, and lines;
+in the UNIX world, this is easily done with the `wc' program. Another
+possibility is to just add up the numerical values of all the characters
+and use the resulting sum as the checksum. Both of these would change
+if characters were added or removed, but they would not change under
+transposition of characters, words, or lines.
+
+Consequently, a lot of research has been done on algorithms for finding
+checksums, and some have even achieved international standardization.
+One of these standard algorithms is known as a CRC-16 checksum. CRC
+stands for *cyclic redundancy checksum*,and the redundancy of following
+it with the word *checksum* is accepted practice. The CRC-16 checksumis
+capable of detecting error bursts up to 16 bits, and 99 percent of
+bursts greater than 16 bits in length. The checksum number is
+represented as a 16-bit unsigned number, encompassing the range 0
+... 65535. Thus, there is roughly one chance in 65535 of an error not
+being detected, that is, of two different files having the same
+checksum.
+
+Of course, no human should have to compute a checksum; that is a job for
+a computer program. The GNU Emacs support software described in this
+document handles the job for you.
+
+We cannot use just any checksum program, however, for several reasons:
+
+ * The checksum program must itself be portable and freely available,
+ because verification of the checksum may be required on any machine
+ that the file is transported to.
+
+ * File formats change from system to system. On some file systems,
+ text files are represented by fixed-length records. On others,
+ variable length records include a count of the number of characters
+ in each line. On still others, lines end with character terminator
+ sequences like CR, LF, or CR LF.
+
+ * The file must contain the checksum, but somehow, the checksum
+ itself must not be counted when the checksum is computed.
+ Otherwise, we could never achieve self-consistency: each insertion
+ of a new checksum would change the checksum.
+
+ * Because of the varying line representations in file systems,
+ trailing blanks should not be included in the checksum. Such
+ blanks waste space, and should never be significant; they can be
+ lost when text is refilled in a line-wrapping editor, or during
+ electronic mail transmission. It is a good idea to get rid of
+ them; the Emacs file header maintenance functions described
+ elsewhere (*Note GNU Emacs editing support::) do this for you
+ automatically.
+
+ * Horizontal tabs look like spaces on the computer display, but are
+ really separate characters. They are often subject to translation
+ to spaces by electronic mail systems. For most text files, you can
+ safely replace them by blanks, which is easy to do in Emacs: just
+ mark the whole buffer with `C-x h', and then type `M-x untabify'.
+
+ UNIX `Makefile's and `troff' files are notable exceptions to this;
+ tabs are *significant* and cannot be replaced without destroying
+ the meaning of those files. That is why the GNU Emacs file header
+ maintenance functions never touch tabs.
+
+
+These considerations make it clear than existing software for computing
+checksums just will not do. I raised these points in an editorial
+challenge [Beebe:TB11-4-485-487] in the TeX Users Group journal,
+TUGboat, and in the spring of 1991 received a clever solution from
+Robert Solovay at the University of California, Berkeley.
+
+Solovay's program, called simply `checksum', is written in a literate
+programming language called CWEB. The output is C code that conforms to
+the 1989 ANSI/ISO C Standard. In computing the checksum, it ignores
+line terminators, and any previous checksum, and since it has been
+placed in the public domain, it solves all of the problems noted above.
+Besides a CRC-16 checksum,it also produces counts of characters, words,
+and lines. In the event that `checksum' has not yet been installed,
+this information can be compared against the output of the UNIX `wc'
+utility. `wc' is simple enough that it can easily be reimplemented on
+any system.
+
+`checksum' also has an option to verify the correctness of the checksum
+in a file;you could use this to check for corruption after transferring
+a file with standard file headers to your system.
+
+Although `checksum' can be run manually, the GNU Emacs support code does
+it for you, producing an entry in the file header that looks something
+like this:
+
+%%% checksum = "25868 849 3980 28305",
+
+The four numbers are the CRC-16 checksum,line count, word count, and
+character count. You must remember that the character count will change
+if the file is stored with different line terminator conventions; the
+other numbers will remain constant.
+
+
+File: filehdr.info Node: codetable, Prev: checksum, Up: Attribute descriptions, Next: date
+
+
+Codetable
+=========
+
+In the computing world of the 1990s, two major character sets are in
+wide use: EBCDICon IBM mainframes and their clones, and ISO/ASCIIon
+everything else. EBCDIC is an 8-bit character set, offering characters
+in the range 0 ... 255, while ISO/ASCII is a 7-bit character set, with
+characters in the range 0 ... 127. On most machines, ISO/ASCII text is
+stored in 8-bit characters.
+
+In turns of numbers of computers, ISO/ASCII is by far the most common,
+since it is the character set used by all personal computers and
+workstations.
+
+Unfortunately, a 128-character set with 95 printable characters and 33
+control characters is inadequate for most non-English languages. Many
+European languages require accented characters or additional letters,
+and Chinese, Japanese, and Korean have thousands of pictographic
+characters.\c
+
+Consequently, computer vendors have dealt with this by offering ISO
+`code pages'--- variations in the encoding of characters 128 ... 255,
+and sometimes even in the encoding of punctuation characters in the
+range 0 ... 127.
+
+Standards bodies are actively working on the development of a new
+character set that will support all, or almost all, of the world's
+present and past languages. One of these efforts is a 16-bit character
+set called Unicode,and another is a 32-bit character set called ISO
+10646.Efforts are now underway to merge these efforts into a character
+set called ISO 10646M (M for merged).\c
+
+Given the speed at which committees work, and the enormous impact on
+millions of computers, and people, of a change in text encoding, it
+seems unlikely that the impact of these efforts will be felt for another
+decade.
+
+The code page problem, however, does have to be dealt with. The
+standard file headers provide for this with an attribute entry like
+
+%%% codetable = "ISO/ASCII",
+
+If the file is encoded in, say code page ISO-8859-3, then the header
+could say that:
+
+%%% codetable = "ISO-8859-3",
+
+Of course, if an ASCII file were transferred to a system with EBCDIC,
+the file would not be immediately readable until the character values
+were translated to EBCDIC. The checksum described in the preceding
+section would be incorrect, but at least the fact that the file header
+stated that the code was originally ISO/ASCII would explain any
+translation peculiarities that cropped up later.
+
+The attribute name `codetable' was chosen over `codepage' because the
+latter notion is restricted to variants of ISO/ASCII.
+
+
+File: filehdr.info Node: date, Prev: codetable, Up: Attribute descriptions, Next: docstring
+
+
+Date
+====
+
+Computer files should always carry a date-and-time stamp to record time
+of the last modification. Some file systems even store date-and-time
+stamps for last read, last write, last backup, and so on.
+
+Unfortunately, many computers do not have a reliable time standard, and
+if they lack a network connection, have no way of maintaining a correct
+one. Date-and-time stamps are recorded in the file system, rather than
+the file itself, and are usually lost when the file is transferred to
+another system. That is regrettable, but it is a fact of life we still
+have to tolerate.
+
+Consequently, a standard file header should carry a date and time. The
+editing support described here supplies it in the form
+
+%%% date = "07 Oct 1991",
+
+Dates and times are expressed in a variety of formats that depend on the
+country and culture.Some software can deal with a considerable variety
+of formats, ranging from "last Wednesday" to "1991.11.06:12.34.17". The
+important point is that the encoding *must be unambiguous*. In
+particular, forms like `12/06/91' should be avoided: does it mean the
+12th day of the 6th month, or the 6th day of the 12th month? The year
+should *not* be abbreviated to two digits; the new millenium is not far
+away.
+
+
+File: filehdr.info Node: docstring, Prev: date, Up: Attribute descriptions, Next: email
+
+
+Docstring
+=========
+
+For the purposes of cataloging files, and recognizing their contents, it
+is helpful to have a few paragraphs of description. This is provided
+for by the `docstring' attribute, which might look like this:
+
+%%% 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.",
+
+This documentation need not be a user's manual for the file, unless the
+necessary information can be communicated in a few paragraphs of no more
+than a couple of thousand characters. Think of it instead as an
+extended abstract.\c \cindex{abstract}\c
+
+Someday, we may have tools that will extract documentation strings from
+standard file headers and turn them into catalogs.
+
+
+File: filehdr.info Node: email, Prev: docstring, Up: Attribute descriptions, Next: FAX
+
+
+Email
+=====
+
+People who exchange computer files now often have network access, and
+the worldwide Internet is growing rapidly. It will not be long before
+network connections are as commonplace, and important, as telephone
+connections now are. Most networks support electronic mail, and the
+trend is to develop uniform addressing schemes that will work the world
+over. Thus, an electronic mail address, when available, is as important
+as a postal address for the author(s).
+
+Here is an example:
+
+%%% email = "beebe@math.utah.edu (Internet)",
+
+Since there are several networks in existence, with different naming
+conventions, it is helpful to identify the network as in this example.
+
+In the event that there are multiple authors, electronic mail addresses
+should be given in the same order, separated by the word `and', just the
+way the author attribute value is coded. Of course, not all of the
+authors might have such an address, so additional qualification, such as
+by a parenthesized set of initials, could follow each address. Use your
+ingenuity, but in such a way that someone you've never met will still
+understand what you mean.
+
+
+File: filehdr.info Node: FAX, Prev: email, Up: Attribute descriptions, Next: filename
+
+
+FAX
+===
+
+The `FAX' attribute should be formatted just like the `telephone' entry.
+Here is an example:
+
+%%% FAX = "+1 801 581 4148",
+
+FAX machines are now very commonly used in business throughout the
+world, so if you have such a facility, it is a good idea to include it
+in the file header.
+
+
+File: filehdr.info Node: filename, Prev: FAX, Up: Attribute descriptions, Next: keywords
+
+
+Filename
+========
+
+Different computing systems have different file naming conventions; in
+particular, there are significant variations in the naming of files.
+Some systems, like the Apple Macintosh, permit arbitrary strings of
+characters, including blanks. Others, like MS DOS on the IBM PC and
+clones, limit names to two parts, a base name and an extension, or type,
+with the two separated by a period (dot, full stop).
+
+File headers should therefore carry an indication of the original name
+of the file, and if the file is expected to be referenced by other
+files, then it is *imperative* that the name chosen be representable on
+a wide variety of, and preferably all, computing systems. Today, this
+in practice means the 8-character base name and 3-character file
+extension of MS DOS, which runs in tens of millions of personal
+computers.There are still a few survivors of older operating systems
+with more stringent requirements on file names, but they are obsolete
+and rapidly disappearing.
+
+The filename should be case *insensitive*,and in the header, spelled in
+lower-case letters. It should start with a letter, and use only
+letters, digits, and perhaps, hyphens (minus signs) in the rest of the
+name, with no more than a single period in the name.\c
+
+This document's file header contains the attribute entry
+
+%%% filename = "filehdr.ltx",
+
+`filehdr' is an abbreviation for "file header", and `ltx' for "LaTeX",
+the name of the document formatting system that typesets this document.
+
+
+File: filehdr.info Node: keywords, Prev: filename, Up: Attribute descriptions, Next: supported
+
+
+Keywords
+========
+
+Large archives always pose a search problem for human users, and it has
+long been traditional to try to classify members of the archives by
+*keywords* that might come to mind when someone is searching for the
+file. Some journals have standard sets of keywords to classify articles
+by, and include them near the abstract of each paper.
+
+With standard file headers, the range of possible keywords is enormous,
+and authors will just have to be diligent about finding good sets of
+descriptive keywords. They should appear in the attribute value as
+phrases separated by commas, as for this document:
+
+%%% keywords = "file header, checksum",
+
+
+File: filehdr.info Node: supported, Prev: keywords, Up: Attribute descriptions, Next: telephone
+
+
+Supported
+=========
+
+All computer files reach a stage of stagnation, where for various
+reasons, their authors no longer maintain them. Nevertheless, it is
+helpful to know whether the author of a given file is interested in
+hearing of problems or comments, and the file header can say so by an
+entry like this one:
+
+%%% supported = "yes",
+
+If it says `yes', this does not provide any guarantee that any problems
+reported will be fixed, but just that the author's intentions are good,
+and reasonable efforts will be made to do so. Some authors even care so
+much about their work that they offer monetary rewards for reports of
+bugs and errors.
+
+If it says `no', then you are on your own, because the author never
+wants to hear from you on the subject of this particular file.
+
+Other attribute values can be readily imagined, like `only for money,
+cash in advance', but a simple `yes' or `no' is probably adequate for
+most people.
+
+
+File: filehdr.info Node: telephone, Prev: supported, Up: Attribute descriptions, Next: time
+
+
+Telephone
+=========
+
+The `telephone' attribute should include the area code with telephone
+number. If there are multiple values, separate them by commas. Here is
+an example from the file header of this document:
+
+%%% telephone = "+1 801 581 5254",
+Use the international form of the number,
+including the country and cityarea code.
+
+
+File: filehdr.info Node: time, Prev: telephone, Up: Attribute descriptions, Next: version
+
+
+Time
+====
+
+The `time' attribute should be of the form `hh:mm:ss', or if a time zone
+abbreviation (say, `GMT') can be found, `hh:mm:ss GMT'. It is recorded
+separately from the `date' to ease the parsing job of software that
+processes file headers.
+
+Here is a typical example:
+
+%%% time = "18:02:38 MST",
+
+
+File: filehdr.info Node: version, Prev: time, Up: Attribute descriptions, Next: multiple values
+
+
+URL
+===
+
+Since its introduction in the early 1990s, the WorldWide Web has spread
+rapidly, so that most public interest in the Internet is associated with
+it, and so that most Internet sites that previously had electronic mail,
+ftp, and telnet services, now also have a WorldWide Web presence.
+
+The Uniform Resource Locator, or URL, is therefore a suitable addition
+to the standard file headers; the one in this file looks like this:
+
+%%% URL = "http://www.math.utah.edu/~beebe",
+
+Since most sites have found it convenient to name a particular machine
+with the prefix "www.", from an electronic mail address one can often
+guess what the corresponding URL should be. Nevertheless, the host with
+that name is often different from the login host, so the Emacs code in
+`filehdr.el' may not successfully identify it automatically. Thus, you
+can provide an overriding private definition like this in your `.emacs'
+startup file:
+
+(setq file-header-user-URL "http://www.math.utah.edu/~beebe")
+
+
+
+Version
+=======
+
+Computer files created by humans almost inevitably go through many
+revisions, whether they are programs to control a satellite, or just the
+words of a promotion for the latest soap product.
+
+Computer vendors have long dealt with this by attaching *version
+numbers* to software releases. These consist of two or three numbers
+with some separator character, such as a period (full stop, dot). The
+first number is called the *major version number*; it gets changed only
+at long intervals, usually years, when really significant changes have
+been incorporated. A second number is a *minor version number* which is
+incremented as smaller changes and bug fixes are incorporated.
+Sometimes a third number is appended, which is an *edit number*; it gets
+incremented every time any change at all is made to the file.
+
+In careful software production, a change log is kept to record the
+reasons for every change; this is particularly important when commercial
+interests or legal issues are at stake. [Military organizations the
+world over are famous for their paperwork trails; perhaps that is what
+helps to keep them busy during times of peace.]
+
+For smaller files, you can probably get by with just a major version
+number and an edit number; for larger projects, three or more are
+recommended.
+
+Here is what one version of this document had in its standard file
+header:
+
+%%% version = "1.01",
+
+Version numbers are particularly useful when reporting problems to the
+author of a file; they allow rapid verification of whether the author
+and end user are even talking about the same thing.
+
+
+File: filehdr.info Node: multiple values, Prev: version, Up: Attribute descriptions, Next: Attribute descriptions
+
+
+Multiple values
+===============
+
+Keywords like `author' and `address' may be inadequate for files
+prepared by more than one person. If several authors share a common
+address, then using the keyword `and', to separate names in the `author'
+field is unambiguous. However, if the postal address, electronic mail
+address, telephone number, and FAX number vary, it is advisable to
+clarify the header by attaching a hyphen and a numeric suffix to the
+attribute name. Here is an example:
+
+%%% author-1 = "Marie Claire LeBrun",
+%%% author-2 = "Hans Peter Brun",
+%%% author-3 = "Jill Brown",
+%%% address-1 = "...",
+%%% address-2 = "...",
+%%% address-3 = "...",
+%%% email-1 = "...",
+%%% email-2 = "...",
+%%% email-3 = "...",
+%%% telephone-1 = "...",
+%%% telephone-2 = "...",
+%%% telephone-3 = "...",
+%%% FAX = "...",
+
+File-header parsing software must be prepared to handle numeric suffixes
+like this for any keyword. If a keyword doesn't have such a suffix, as
+the `FAX' keyword in this example, then it should be assumed to apply to
+all authors.
+
+
+File: filehdr.info Node: GNU Emacs editing support, Prev: Attribute descriptions, Up: Top, Next: Simple customization
+
+
+GNU Emacs editing support
+*************************
+
+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 `SYS$MANAGER: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,and telephoneand FAX numbers, and possibly, your WorldWide Web
+URL.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")
+
+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' and `system-name' functions is not suitable, you can
+provide an alternative one like this:
+
+(setq file-header-user-email "beebe@math.utah.edu")
+In any of the following situations, you should set
+`file-header-user-email' in your startup `.emacs' file.
+
+ * You work on multiple machines, but prefer to have only one public
+ electronic-mail address.
+
+ * At some sites, `system-name' does not return a fully-qualified
+ Internet host name, so the default address constructed by
+ `file-header-email' is unusable outside your local installation.
+
+ * Your site is not on the Internet, but you can receive electronic
+ mail via some other network.
+
+
+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' will update the date and time
+stamps, the minor version number, the checksum, and save the file.
+
+If the file is a LaTeXfile, 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-date', `update-minor-version', and
+`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' is
+supplied to automate the job.
+
+`update-checksum' will trim trailing whitespace(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, so `update-checksum' on that system calls
+`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' 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.
+
+
+File: filehdr.info Node: Simple customization, Prev: GNU Emacs editing support, Up: Top, Next: Advanced customization
+
+
+Simple customization
+********************
+
+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', 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', 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, comments must begin a line
+with the string `Comment '. For `awk' files, a triple sharp sign and a
+space will begin all file header lines. `yacc' file headers have no
+comment prefix at all.
+
+The third variable, `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', 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'.\c
+
+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', 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'.
+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:\c
+\cpsubindex{customization}{examples}
+
+(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"))
+ ))
+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)' 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'.\c \findex{make-file-header}
+
+You can test the entire collection of code by typing `M-x
+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' and
+`file-header-extra-suffix-and-type'.\c
+\vindex{file-header-extra-suffix-and-type}
+
+To see the settings of the variables named `file-header-standard-xxx'
+and `file-header-extra-xxx', type `M-x 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, but on UNIX systems, it can be obtained from
+the output of the `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'. 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.
+
+
+File: filehdr.info Node: Advanced customization, Prev: Simple customization, Up: Top, Next: Bug reporting
+
+
+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'.
+Here is what its body looks like:
+
+ (file-header-comment-block-begin)
+ (file-header-entry)
+ (mapcar '(lambda (entry)
+ (file-header-key (car entry) (nth 1 entry)))
+ (append file-header-standard-entries
+ file-header-extra-entries))
+ (file-header-exit)
+ (file-header-comment-block-end)
+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' and `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', 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' function called in the body of `make-file-header'
+applies its second argument, here an anonymous `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' and `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."
+ "ISO/ASCII"
+ )
+
+If you want to add a new file header attribute entry, you need to add an
+entry to `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
+attributein 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', 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' 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' is invoked. In such a case, you'll have
+to study its body, and the functions it calls, to make the necessary
+modifications.
+
+
+File: filehdr.info Node: Bug reporting, Prev: Advanced customization, Up: Top, Next: Bibliography
+
+
+Bug reporting
+*************
+
+Bug reports, and comments, are actively solicited. Electronic mail to
+the author is most convenient, but postal mail, preferably accompanied
+by machine-readable material on Apple Macintosh or IBM PC floppy disks,
+are also acceptable. Shorter communications via FAX are also possible.
+Here are the necessary addresses and telephone numbers:
+
+
+Nelson H. F. Beebe
+Center for Scientific Computing
+Department of Mathematics
+University of Utah
+Salt Lake City, UT 84112
+USA
+Tel: +1 801 581 5254
+FAX: +1 801 581 4148
+Email: beebe@math.utah.edu
+URL: http://www.math.utah.edu/~beebe
+
+
+File: filehdr.info Node: Bibliography, Prev: Bug Reporting, Up: Top, Next: Concept Index
+
+Beebe:TB11-4-485-487
+
+ Nelson H. F. Beebe. {{From the President}}. *TUGboat*,
+ 11(4):485--487, November 1990.
+
+Lamport:LDP85
+
+ Leslie Lamport. *{LaTeX}---A Document Preparation System---User's
+ Guide and Reference Manual*. Ad{d}i{s}on-Wes{l}ey, 1985.
+
+Lottor:CACM-34-11-21
+
+ Mark Lottor. Internet domain system. *Communications of the
+ Association for Computing Machinery*, 34(11):21--22, November 1991.
+ This letter reports that the ZONE program at the Network
+ Information Systems Center at SRI International in July 1991 found
+ approximately 535,000 Internet hosts in 16,000 domains. The 10
+ largest domains were EDU (educational)--206,000, COM
+ (commercial)--144,000, GOV (government)---36,000, MIL (military)
+ 26,000, AU (Australia)--22,000, DE (Germany)---21,000, CA
+ (Canada)--19,000, ORG (organizations)---15,000, SE
+ (Sweden)---12,000, and CH (Switzerland)---10,000.\refill
+
+Unilogic:SDP84
+
+ Unilogic, Ltd. *Scribe Document Production System User Manual*,
+ April 1984.
+
+
+
+
+
+
+
+File: filehdr.info Node: Concept index, Prev: Bibliography, Up: Top, Next: Function index
+
+
+Concept index
+*************
+
+
+
+
+* Menu:
+
+* abstract: abstract.
+* address: address.
+* address: multiple values.
+* Adobe Font Metric file: Simple customization.
+* and: author.
+* and: multiple values.
+* ASCII character set: codetable.
+* attribute descriptions: Attribute descriptions.
+* attribute names: Attribute names.
+* attribute values: Attribute values.
+* author: author.
+* author: author.
+* author: multiple values.
+* author: multiple values.
+* Bitnet: Background.
+* bug reporting: Bug reporting.
+* change log: version.
+* character count: checksum.
+* checksum: checksum.
+* Chinese characters: codetable.
+* citation tag: Putting it all together.
+* class name: Class names.
+* codetable: codetable.
+* comment: What's in a header?.
+* concept index: Concept index.
+* cyclic redundancy checksum: checksum.
+* date stamp: date.
+* date: time.
+* docstring: docstring.
+* EBCDIC character set: codetable.
+* editing support: GNU Emacs editing support.
+* electronic mail: email.
+* Emacs editing support: GNU Emacs editing support.
+* FAX: FAX.
+* FAX: multiple values.
+* GNU Emacs editing support: GNU Emacs editing support.
+* Heidelberg University: Background.
+* International Standard Book Number (ISBN): What's in a header?.
+* ISO character set: codetable.
+* Japanese characters: codetable.
+* Korean characters: codetable.
+* LaTeX: filename.
+* LaTeX: What's in a header?.
+* licensing information: Licensing information.
+* line count: checksum.
+* literate programming: checksum.
+* name parsing: author.
+* network file exchange: Background.
+* outline of file header: Outline of file headers.
+* postal address: email.
+* Scribe document formatting system: What's in a header?.
+* tab character: checksum.
+* telephone: FAX.
+* telephone: telephone.
+* TeX Users Group: Background.
+* TeX Users Group: checksum.
+* time stamp: date.
+* time: time.
+* time zone: Simple customization.
+* TUGboat: checksum.
+* Usenet: Background.
+* VAX VMS: GNU Emacs editing support.
+* version number: version.
+* word count: checksum.
+* word count: checksum.
+* word count: checksum.
+
+
+
+File: filehdr.info Node: Function index, Prev: Concept index, Up: Top, Next: Person index
+
+
+Function index
+**************
+
+
+
+
+* Menu:
+
+* append: Advanced customization.
+* car: Advanced customization.
+* concat: Simple customization.
+* file-header-comment-block-begin: Advanced customization.
+* file-header-comment-block-end: Advanced customization.
+* file-header-email: GNU Emacs editing support.
+* file-header-entry: Advanced customization.
+* file-header-entry: Advanced customization.
+* file-header-exit: Advanced customization.
+* file-header-exit: Advanced customization.
+* file-header-key: Advanced customization.
+* file-header-key: Advanced customization.
+* lambda: Advanced customization.
+* lambda: Advanced customization.
+* load: Advanced customization.
+* make-file-header: Advanced customization.
+* make-file-header: Advanced customization.
+* make-file-header: Advanced customization.
+* make-file-header: Simple customization.
+* mapcar: Advanced customization.
+* mapcar: Advanced customization.
+* nth: Advanced customization.
+* setq: Simple customization.
+* show-file-header-variables: Simple customization.
+* system-name: GNU Emacs editing support.
+* system-name: GNU Emacs editing support.
+* test-file-header: Simple customization.
+* update-checksum: GNU Emacs editing support.
+* update-checksum: GNU Emacs editing support.
+* update-checksum: GNU Emacs editing support.
+* update-date: GNU Emacs editing support.
+* update-date-and-minor-version: GNU Emacs editing support.
+* update-file-header-and-save: Advanced customization.
+* update-file-header-and-save: GNU Emacs editing support.
+* update-major-version: GNU Emacs editing support.
+* update-minor-version: GNU Emacs editing support.
+* update-simple-checksum: GNU Emacs editing support.
+* user-login-name: GNU Emacs editing support.
+
+
+
+File: filehdr.info Node: Person index, Prev: Function index, Up: Top, Next: Program index
+
+
+Person index
+************
+
+
+
+
+* Menu:
+
+* Beebe, Nelson H. F.: checksum.
+* Lamport, Leslie: What's in a header?.
+* Lotter, Mark: Background.
+* Patashnik, Oren: What's in a header?.
+* Reid, Brian: What's in a header?.
+* Solovay, Robert: checksum.
+
+
+
+File: filehdr.info Node: Program index, Prev: Person index, Up: Top, Next: Variable index
+
+
+Program index
+*************
+
+
+
+
+* Menu:
+
+* awk: Simple customization.
+* bibtex: Attribute values.
+* bibtex: Putting it all together.
+* bibtex: What's in a header?.
+* checksum: checksum.
+* checksum: checksum.
+* checksum: checksum.
+* checksum: checksum.
+* checksum: GNU Emacs editing support.
+* CWEB: checksum.
+* date: Simple customization.
+* Makefile: checksum.
+* troff: checksum.
+* wc: checksum.
+* wc: checksum.
+* yacc: Simple customization.
+
+
+
+File: filehdr.info Node: Variable index, Prev: Program index, Up: Top, Next: Top
+
+
+Variable index
+**************
+
+
+
+
+* Menu:
+
+* file-header-code-version: Author and version.
+* file-header-extra-at-sign-special-cases: Simple customization.
+* file-header-extra-comment-prefixes: Simple customization.
+* file-header-extra-entries: Advanced customization.
+* file-header-extra-entries: Advanced customization.
+* file-header-extra-entries: Advanced customization.
+* file-header-extra-entries: Simple customization.
+* file-header-extra-paired-comment-delimiter-languages: Simple customization.
+* file-header-extra-suffix-and-type: Simple customization.
+* file-header-extra-xxx: Simple customization.
+* file-header-standard-at-sign-special-cases: Simple customization.
+* file-header-standard-comment-prefixes: Simple customization.
+* file-header-standard-entries: Advanced customization.
+* file-header-standard-entries: Advanced customization.
+* file-header-standard-entries: Simple customization.
+* file-header-standard-paired-comment-delimiter-languages: Simple customization.
+* file-header-standard-suffix-and-type: Simple customization.
+* file-header-standard-suffix-and-type: Simple customization.
+* file-header-standard-xxx: Simple customization.
+* file-header-timezone-string: Simple customization.
+* file-header-user-address: GNU Emacs editing support.
+* file-header-user-email: GNU Emacs editing support.
+* file-header-user-email: GNU Emacs editing support.
+* file-header-user-FAX: GNU Emacs editing support.
+* file-header-user-telephone: GNU Emacs editing support.
+* file-header-user-URL: GNU Emacs editing support.
+* file-header-user-URL: version.
+
+
+
+Tag table:
+Node: Top101
+Node: Licensing information1863
+Node: Author and version3734
+Node: Background4488
+Node: What's in a header?7287
+Node: Putting it all together12415
+Node: Outline of file headers15313
+Node: Class names15814
+Node: Attribute names17562
+Node: Attribute values18245
+Node: Attribute descriptions22167
+Node: abstract22787
+Node: address23379
+Node: author23955
+Node: checksum24782
+Node: codetable30278
+Node: date32867
+Node: docstring34224
+Node: email35963
+Node: FAX37210
+Node: filename37609
+Node: keywords39210
+Node: supported39979
+Node: telephone41021
+Node: time41462
+Node: version41877
+Node: multiple values44594
+Node: GNU Emacs editing support45895
+Node: Simple customization52793
+Node: Advanced customization60960
+Node: Bug reporting65384
+Node: Bibliography66092
+Node: Concept index67295
+Node: Function index69433
+Node: Person index71233
+Node: Program index71575
+Node: Variable index72114
+
+End tag table
diff --git a/support/filehdr/filehdr.ltx b/support/filehdr/filehdr.ltx
new file mode 100644
index 0000000000..c825c4ad9b
--- /dev/null
+++ b/support/filehdr/filehdr.ltx
@@ -0,0 +1,2582 @@
+% -*-latex-*-
+% Document name: /u/sy/beebe/emacs/filehdr.ltx
+% Creator: Nelson H. F. Beebe [beebe@magna.math.utah.edu]
+% Creation Date: Wed Nov 6 20:51:19 1991
+
+%%% ====================================================================
+%%% @LaTeX-file{
+%%% author = "Nelson H. F. Beebe",
+%%% version = "1.28",
+%%% date = "06 March 1996",
+%%% time = "13:34:24 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 = "10578 2582 11023 83232",
+%%% 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.",
+%%% }
+%%% ====================================================================
+
+\documentstyle[latexinfo,rcs]{book}
+
+% Comment out to suppress page footers with RCS version info:
+\RCSID{$Id: filehdr.ltx,v 1.9 1993/08/30 19:41:05 beebe Exp beebe $}
+
+\renewcommand{\i}[1]{{\em #1}} % change from \sl to \em
+\let\emph=\i
+
+\pagestyle{empty}
+
+\newindex{cp} \c concepts
+\newindex{fn} \c functions
+\newindex{pg} \c programs
+\newindex{tp} \c persons
+\newindex{vr} \c variables
+
+\typeout{May need LaTeXinfo submode for latex.el
+for dots, emph, et al if Mike Clarkson hasn't
+fixed the problem yet.}\c
+
+\c \finalout
+
+\title{
+ Standard File Headers
+}
+
+\author{
+ Nelson H. F. Beebe\\
+ Center for Scientific Computing\\
+ Department of Mathematics\\
+ University of Utah\\
+ Salt Lake City, UT 84112\\
+ USA\\
+ Tel: +1 801 581 5254\\
+ FAX: +1 801 581 4148\\
+ E-mail: {\tt beebe@math.utah.edu}
+}
+
+\date{06 March 1996 \\
+Version 1.28}
+
+\c =================================================
+
+\begin{iftex}
+\c We need to allow hyphenation at - characters in
+\c \tt fonts.
+\global\hyphenchar\nintt = `\-
+\global\hyphenchar\tentt = `\-
+\global\hyphenchar\elvtt = `\-
+\global\hyphenchar\twltt = `\-
+\end{iftex}
+
+\begin{document}
+
+\bibliographystyle{plain}
+
+\maketitle
+
+\c =================================================
+
+\clearpage
+\vspace*{0pt plus 1filll}
+Copyright \copyright{} 1991 Free Software Foundation, Inc.
+
+This file documents version 1.28 of the standard
+file header support package for GNU Emacs, version
+18 or later.\refill
+
+Permission is granted to make and distribute
+verbatim copies of this manual provided the
+copyright notice and this permission notice are
+preserved on all copies.\refill
+
+Permission is granted to process this file through
+\TeX{} and print the results, provided the printed
+document carries copying permission notice
+identical to this one except for the removal of
+this paragraph (this paragraph not being relevant
+to the printed manual).\refill
+
+Permission is granted to copy and distribute
+modified versions of this manual under the
+conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under
+the terms of a permission notice identical to this
+one.\refill
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated
+in a translation approved by the Foundation.\refill
+
+\clearpage
+\pagestyle{headings}
+\pagenumbering{roman}
+\tableofcontents
+
+% \listoftables
+
+\clearpage
+\pagenumbering{arabic}
+
+\c =================================================
+\c Anything before the \setfilename will not appear
+\c in the .info file
+\setfilename{filehdr.info}
+
+\node Top, Licensing information, Variable Index, (dir)
+
+\begin{ifinfo}
+This file documents version 1.28 of the standard
+file header support package for GNU Emacs, version 18
+or later.\refill
+
+Copyright (C) 1991 Free Software Foundation, Inc.\refill
+
+Permission is granted to make and distribute
+verbatim copies of this manual provided the
+copyright notice and this permission notice are
+preserved on all copies.\refill
+
+Permission is granted to copy and distribute
+modified versions of this manual under the
+conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under
+the terms of a permission notice identical to this
+one.\refill
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated
+in a translation approved by the Foundation.\refill
+\end{ifinfo}
+
+\begin{menu}
+* Licensing information:: Conditions for use
+* Author and version:: Who wrote this
+* Background:: The origins of all of this
+* What's in a header?::
+* Putting it all together::
+* Outline of file headers::
+* Attribute descriptions:: Details of attributes
+* GNU Emacs editing support:: Letting Emacs do the work for you
+* Simple customization:: Changing things the easy way
+* Advanced customization:: Changing things the hard way
+* Bug reporting:: How to report bugs, comments, etc.
+* Bibliography:: Literature references
+* Concept Index:: General topic index
+* Function Index:: Lisp functions
+* Person Index:: Individuals cited in this text
+* Program Index:: Operating system programs
+* Variable Index:: Lisp variables
+\end{menu}
+
+\c =================================================
+
+\c ===> \node node-name, next, previous, up <===
+\node Licensing information, Author and version, Top, Top
+
+\c =============================================
+\c There appears to be a bug in LaTeXinfo 1.3.5
+\c \unnumberedsec{xxx} is dropped from the
+\c info file. We cannot use \section*{} in
+\c LaTeX mode because tables of contents entries
+\c are then lost.
+\c =============================================
+
+\begin{ifinfo}
+\chapter*{Licensing information}
+\end{ifinfo}
+\begin{tex}
+\unnumbered{Licensing information}
+\end{tex}
+\cindex{licensing information}
+The program currently being distributed that
+relates to standard file headers is contained in
+the file \file{filehdr.el}. It consists of
+numerous support functions for to the creation and
+maintenance of file headers. This program is
+\dfn{free}; this means that everyone is free to
+use it and free to redistribute it on a free
+basis.\refill
+
+Specifically, we want to make sure that you have
+the right to give away copies of the programs that
+relate to \file{filehdr.el}, that you receive
+source code or else can get it if you want it,
+that you can change these programs or use pieces
+of them in new free programs, and that you know
+you can do these things.\refill
+
+To make sure that everyone has such rights, we
+have to forbid you to deprive anyone else of these
+rights. For example, if you distribute copies of
+the file \file{filehdr.el}, you must give the
+recipients all the rights that you have. You must
+make sure that they, too, receive or can get the
+source code. And you must tell them their
+rights.\refill
+
+Also, for our own protection, we must make certain
+that everyone finds out that there is no warranty
+for the programs that relate to \file{filehdr.el}.
+If these programs are modified by someone else and
+passed on, we want their recipients to know that
+what they have is not what we distributed, so that
+any problems introduced by others will not reflect
+on our reputation.\refill
+
+The precise conditions of the licenses for the
+programs currently being distributed that relate
+to \file{filehdr.el} are found in the General Public
+Licenses that accompany them. The programs that
+are part of GNU Emacs are covered by the GNU Emacs
+copying terms
+(\pxref{License, , , emacs, The GNU Emacs Manual}),
+and other programs are covered by licenses that
+are contained in their source files.\refill
+
+\node Author and version, Background, Licensing information, Top
+
+\c We only include this section in the info file,
+\c because the printed manual has a title page
+\c with author information.
+\begin{ifinfo}
+The GNU Emacs Lisp file \file{filehdr.el}
+was developed by\refill
+\begin{verbatim}
+Nelson H. F. Beebe
+Center for Scientific Computing
+Department of Mathematics
+University of Utah
+Salt Lake City, UT 84112
+USA
+Tel: +1 801 581 5254
+FAX: +1 801 581 4148
+E-mail: beebe@math.utah.edu
+URL: http://www.math.utah.edu/~beebe
+\end{verbatim}
+
+\noindent
+in the summer of 1991, and contributed to the Free
+Software Foundation.\refill
+
+This documentation corresponds to version 1.28 of
+\file{filehdr.el}. This should match the code
+version that is stored in the Emacs variable
+\code{file-header-code-version}.\c
+\vindex{file-header-code-version}
+The author information is similarly stored in the variable
+\code{file-header-code-author}.\refill\c
+\vindex{file-header-code-author}
+\end{ifinfo}
+
+\node Background, What's in a header?, Author and version, Top
+
+\chapter{Background}
+
+With the rapid spread of the global Internet,
+which by 1991 reaches more than a half-million
+computers\c
+\cpsubindex{Internet}{size of}
+all around the world \cite{Lottor:CACM-34-11-21},\c
+\tindex{Lotter, Mark}
+the opportunities for free exchange of software
+and textual data are greatly enhanced.\refill
+
+While this brings exciting new capabilities to
+many people, not just those involved in academic
+research, it is hampered by several factors.\refill
+
+First, not all network file exchange\c
+\cindex{network file exchange}
+is error-free. Electronic mail\c
+\cpsubindex{electronic mail}{corruption problems}
+systems in particular are notorious for corrupting
+information, either by truncation of lines or
+message bodies, or by transliteration or other
+altering of certain characters. These problems
+are most severe for mail exchanges \emph{between}
+major networks, such as between the Internet and
+Usenet\c
+\cindex{Usenet}
+or Bitnet.\refill\c
+\cindex{Bitnet}
+
+Second, no standards yet exist for describing the
+contents of files. While this is an area of
+research at some academic institutions, the wide
+variety of operating systems in use, and the growing
+numbers of computers (approaching 100 million
+on a world-wide basis in 1991), suggest that such
+standards may never exist, any more than products
+on the commercial market, from soup to saltines,
+have standard labels.\refill
+
+Third, without a record of origin of software and
+data, it is impossible for users to verify that
+they have up-to-date copies, or to contribute
+improvements and additions back to the original
+authors.\refill
+
+Fourth, without a standard means of encoding
+information in file headers, there is no hope of
+automating the process of collecting information
+from file headers to produce enhanced file archive
+summaries, catalogs, and the like.\refill
+
+During the author's 1991--92 tenure as President of the
+\TeX{} Users Group,\c
+\cindex{TeX Users Group}
+efforts were undertaken to improve the quality and
+quantity of electronic distribution of
+\TeX{}-related software and data. While this work
+had a narrow focus, it has quite general
+ramifications, and the GNU Emacs support code here
+is quite general, and capable of handling almost
+any type of computer-readable textual
+material.\refill
+
+It does \emph{not}, however, address the issue of
+exchange of binary (non-textual) data; that has a
+number of difficulties associated with it, the two
+most severe being rigid formats intolerant of
+extension, and machine-specific encoding and byte
+order.\refill
+
+During a visit to Heidelberg University\c
+\cindex{Heidelberg University}
+in June
+1990, the author spent a pleasant brain-storming
+session that lasted until 3am with a dozen
+colleagues (who names, alas, were unrecorded) from
+Heidelberg, Mainz, Darmstadt, and Goettingen.\refill
+
+We discussed many things that evening, but one
+topic in particular led to this work: an informal
+proposal for standard file headers that could
+address all of the problems noted above.\refill
+
+\node What's in a header?, Putting it all together, Background, Top
+
+\chapter{What's in a header?}\c
+\cpsubindex{file header}{contents}
+
+The Bib\TeX{}\c
+\pindex{bibtex}
+system for support of bibliographic data bases was
+developed by Oren Patashnik\c
+\tindex{Patashnik, Oren}
+at Stanford University, based on earlier work by
+Brian Reid\c
+\tindex{Reid, Brian}
+at Carnegie Mellon University on the
+Scribe document formatting system\c
+\cindex{Scribe document formatting system}
+\cite{Unilogic:SDP84}. Bib\TeX{} is described in
+Leslie Lamport's\c
+\tindex{Lamport, Leslie}
+book \cite{Lamport:LDP85} on
+\LaTeX{}.\c
+\cindex{LaTeX}
+It is based on the notion that bibliographic items
+can be divided into distinct \emph{classes}:
+articles, books, reports, theses, and so
+on.\refill
+
+Each class of documents has certain features in
+common. For example, journal articles have
+authors, titles, volume numbers, often issue
+numbers, page numbers, and dates of publications.
+Theses and reports would have the name of an
+institution attached.\refill
+
+The number of classes of documents is not fixed;
+indeed, it may change with time, or between
+cultures and languages. Thus, a bibliographic
+system must be \emph{extensible}. Bib\TeX{}
+provides this critical feature by an
+implementation in a programming language that
+knows how to parse the general structure of a
+bibliographic data base entry, without particular
+knowledge of the classes, or attributes of
+classes. That information is instead encoded in a
+\emph{style file}, which is written in a much more
+compact form that is specialized for its job, and
+is presumably easier for users to change than
+Bib\TeX{} itself is.\refill
+
+The style file can specify which attributes are
+required to be present in a class (e.g.\ a Ph.D.
+thesis must have an institution), and which
+attributes are optional (a book may or may not
+have an International Standard Book Number,\c
+\cindex{International Standard Book Number (ISBN)}
+ISBN).\refill
+
+Some styles may not require all attributes in a
+particular class, so Bib\TeX{} simply
+\emph{ignores} attributes not required by the
+current style, checking them only cursorily for
+proper syntax.\refill
+
+In addition, the style file can specify how individual
+bibliographic entries extracted by Bib\TeX{} from
+data base files are to be formatted. In a
+typesetting application, this flexibility is
+important, because there are a great many
+bibliography formatting styles, and each journal
+or publisher often has rather strict (and
+arbitrary) rules that authors must adhere to.\refill
+
+How does this relate to the question of file
+headers?\refill
+
+Clearly, the notion of classes and attributes
+applies to all computer files as well. The class
+is the file type, such as Lisp file, Pascal code
+file, and national census data file. The
+attributes are things like author(s), author's
+address, date of last modification, file name,
+revision history, character set name, and so on.\refill
+
+In many operating systems, file naming conventions
+have been adopted by which the name encodes
+information about the class to which the file
+belongs. For example, if the file name ends in
+\file{.c}, it is assumed to contain code written
+in the C programming language. Unfortunately,
+few file systems are general enough to permit the
+creators of computer files to encode additional
+header information that might be more detailed.\refill
+
+Since this additional information cannot be
+standardly encoded in the file system, it must be
+supplied in some way inside the files themselves.
+This is not universally possible, particularly
+with binary files.\refill
+
+However, textual data tends to be much more
+portable between computer systems, and all
+reasonable programming languages and text
+processing systems make some provision for
+\emph{comments},\c
+\cindex{comment}
+that is, explanatory material inserted into the
+file which is otherwise ignored by the program
+which processes the file.\refill
+
+Such comments are generally identified by a unique
+start symbol, followed by the comment text, and a
+unique end symbol.\refill
+
+The start symbol is usually a particular special
+character, or special short character sequence,
+not otherwise required in the language in which
+the file is encoded. Sometimes the start symbol
+must begin in a certain column of the line, such
+as Fortran's \code{C} or \code{*} in column 1, or
+is implicitly present at a certain column
+(assembly languages for older computers often
+decreed something like ``a comment starts in
+column 32 of the input record'').\refill
+
+The end symbol is frequently an end-of-line
+condition, which need not be an actual character.
+This convention is simple, but limits comments to
+single lines. If a comment end symbol other than
+end-of-line is chosen, the comment body may span
+multiple lines. Thus, the PL/1 and C programming
+languages delimit comments by \code{/*} and
+\code{*/}, and Pascal by \code{(*} and \code{*)},
+or by paired braces. Some programming languages
+even permit comments to be properly \emph{nested},
+so that one can comment out a block of code that
+itself contains comments.\refill
+
+Ideally, a comment syntax should be simple, yet
+permit \emph{any} processor-representable
+characters to appear in the comment text, so as
+not to hinder freedom of expression.\refill
+
+In any event, with most programming languages, we
+should be able to encode file header information
+as comments in such a way that expression is not
+restricted, yet both humans and suitable computer
+programs can recognize the presence of the file
+header.\refill
+
+\node Putting it all together, Outline of file headers, What's in a header?, Top
+
+\chapter{Putting it all together}
+
+The preceding sections have outlined the notions
+of \emph{classes}, \emph{attributes}, and
+\emph{comment embedding}. What we want to do is
+to borrow the syntax used by Bib\TeX{}\c
+\pindex{bibtex}
+for bibliography data base files, and encode the
+file header as comment body text in whatever
+syntax the programming language allows, but to do
+so in such a way that it can be readily recognized
+by both humans and computer programs.\refill
+
+Thus, in a Fortran file, for which comments run
+from a \code{C} in column 1 to end of line, our
+file header might look something like this:\refill
+\begin{verbatim}
+C @Class{
+C attribute1 = "value1",
+C attribute2 = {value2},
+C attribute3 = {value3 with {extra braces}},
+C attribute4 = {value4 with "quotation marks"},
+C attribute5 = "value5 with ""quotation marks""",
+C ...
+C }
+\end{verbatim}
+
+The key to programmatic recognition of the header
+is the syntax \emph{name followed by an opening
+brace, zero or more attribute assignments, and a
+closing brace}. The attribute value fields can be
+enclosed in quotation marks, or balanced
+braces, as shown above.\refill
+
+In the event that braces otherwise have special
+significance (such as in one of Pascal's comment
+forms), other distinct paired delimiters could be
+used; in the ASCII character set, this means
+parentheses, square brackets, or angle
+brackets.\refill
+
+The order of attributes is significant only in the
+event of duplications; in such a case, the
+\emph{last} value assignment is the one to be
+used. Conventions for the order of attributes
+will make file headers easier to read,
+however.\refill
+
+Readers familiar with Bib\TeX{}\c
+\cindex{citation tag}
+will note the absence of a \emph{tag} following
+the opening brace. In the bibliography data base
+application, the tag serves as a unique citation
+key that can be placed in other documents to
+uniquely identify the bibliographic reference. In
+the current application for file headers, we have
+no need of such a tag.\refill
+
+For languages in which comments continue from a
+start symbol to end of line, it will be useful,
+though not essential, to make the comment section
+containing the file header more visible. This can
+be done in a variety of ways, such as by doubling
+or tripling the comment start symbol, or putting a
+distinctive character sequence, like several
+asterisks or an arrow, \code{==>}, after it. The
+essential point is that if each line begins with a
+comment start symbol, \emph{that same prefix must
+be used on every line of the header}. Not only
+does this enhance visibility, it makes it possible
+for a relatively simple computer program to
+identify the first line of the header and
+recognize the comment syntax automatically, and
+then collect the remainder of the header by
+discarding identical comment prefixes\c
+\cpsubindex{comment}{prefix stripping}
+from succeeding lines until a complete header has
+been collected.\refill
+
+\node Outline of file headers, Attribute descriptions, Putting it all together, Top
+
+\chapter{Outline of file headers}\c
+\cpsubindex{file header}{outline}\c
+\cindex{outline of file header}
+
+This chapter briefly describes what the file
+headers contain: class names, attribute names, and
+attribute values. Each is treated in a separate
+section. Detailed descriptions of attributes will
+be found in the next chapter (\pxref{Attribute
+descriptions}).\refill
+
+\begin{menu}
+* Class names::
+* Attribute names::
+* Attribute values::
+\end{menu}
+
+\node Class names, Attribute names, Outline of file headers, Top
+
+\section{Class names}\c
+\cindex{class name}
+
+What should the class name in a file header be?
+We want it to be indicative of the file contents,
+even to a reader unfamiliar with the computer
+system from which it originated. Here are some
+desirable criteria:\refill
+\begin{itemize}
+
+\item
+The class name should \emph{not} be restricted by
+the length constraints of many file systems, and
+it should not use abbreviations, because they are
+often unintelligible to readers unfamiliar with
+the originating computer system, or with the
+language in which the header is written.\refill
+
+\item
+It must also be possible to generate the class
+name automatically from knowledge of what the file
+name is, at least for those many classes of files
+that are distinguished by particular phrases in
+their file names.\refill
+
+\item
+Class names must be standard across different
+operating systems, so that when files are moved
+between such systems, they can be readily
+associated with the correct class.\refill
+
+\item
+Class names must be recognizable by a simple
+computer program, and thus must conform to an
+agreed-upon syntax.\refill
+\end{itemize}
+
+I therefore propose that class names consist of an
+optional at-sign, \code{@}, immediately followed
+by an initial letter, optionally followed by
+letters, digits, and hyphens, followed by the
+phrase \code{-file}.\refill
+
+Letter case may be mixed for readability,
+\emph{but is not otherwise significant}:
+\code{@LATEX-FILE} and \code{@LaTeX-file}
+represent the same file class.\refill
+
+This style of naming is common to many programming
+languages. Hyphens between words improve
+readability, while avoiding ambiguities introduced
+when spaces are allowed to be part of
+names.\refill
+
+\node Attribute names, Attribute values, Class names, Top
+
+\section{Attribute names}\c
+\cindex{attribute names}
+
+What file header attributes do we need? Here are
+several that are desirable:
+abstract,
+author(s),
+checksum,
+code table,
+date,
+documentation,
+filename,
+keywords (for later indexing and cross-referencing),
+postal, electronic mail, and WorldWide Web addresses,
+and
+version.\refill
+
+Attribute names have the same syntax as class
+names, except that an at-sign, \code{@}, is never
+present. New attribute names can be added as
+needed, with the understanding that the file
+header processing software will ignore attributes
+that it has not been programmed to deal
+with.\refill
+
+\node Attribute values, Outline of file headers, Attribute names, Top
+
+\section{Attribute values}\c
+\cindex{attribute values}
+
+What about attribute values? These are for the
+most part arbitrary text strings, usually
+delimited by quotation marks. In the event that
+quotation marks are needed in the text itself,
+braces (or parentheses, square brackets, or angle
+brackets) may be used instead, provided that they
+are properly nested. The value text should
+\emph{not} presuppose the existence of any
+particular text formatting system;\c
+\cpsubindex{attribute value}{no formatting system}
+in particular,
+it should be understandable to a human reader when
+it is displayed in the 95 printable characters of
+the ASCII character set.\refill
+
+Attribute values may span multiple lines, and in
+most cases, newlines can be treated like spaces.\c
+\cpsubindex{attribute value}{newlines in}
+However, file header processing software
+\emph{must} distinguish between spaces and
+newlines, and in some cases, such as for address
+values, newlines will be preserved in the
+output.\refill
+
+Since file headers are encoded inside language
+comments, each line will often begin with a
+comment start symbol and white space chosen to
+provide neat formatting of the header to enhance
+its readability. Thus, after stripping the
+comment start symbol, leading white space (blanks
+and horizontal tabs) may be ignored.\refill\c
+\cpsubindex{attribute value}{leading white space in}
+
+File header processing software \emph{may} choose
+to eliminate common prefix strings consisting of a
+comment start symbol and following white space
+from successive lines of a single value, but
+preserve additional indentation space. Thus, the
+input\refill
+\begin{verbatim}
+;;; name = "Blah blah blah blah blah blah
+;;; blah blah blah blah blah blah.
+;;;
+;;; Blah blah blah blah blah.
+;;; blah blah blah blah blah blah.
+;;;
+;;; Blah blah blah blah blah."
+\end{verbatim}
+
+\noindent
+could produce the value string\refill
+\begin{verbatim}
+Blah blah blah blah blah blah
+blah blah blah blah blah blah.
+
+ Blah blah blah blah blah.
+blah blah blah blah blah blah.
+
+ Blah blah blah blah blah.
+\end{verbatim}
+
+\noindent
+if common prefixes are stripped, or\refill
+\begin{verbatim}
+Blah blah blah blah blah blah
+blah blah blah blah blah blah.
+
+Blah blah blah blah blah.
+blah blah blah blah blah blah.
+
+Blah blah blah blah blah.
+\end{verbatim}
+
+\noindent
+if all leading white space is discarded.\refill
+
+Bib\TeX{}\c
+\pindex{bibtex}
+adopts that convention that braced
+groups inside a value string are protected from
+certain actions, such as letter case conversion,
+or sorting. In particular, a single quotation
+mark may be enclosed in braces to prevent its
+recognition as a value string terminator, assuming
+the string was started by a quotation mark. Since
+Bib\TeX{} expects that its output will be
+processed by the \TeX{} typesetting system, where
+braces serve as grouping commands, and are not
+normally themselves printable, this is a
+reasonable choice: the value string \code{"A
+quotation mark, \{"\}, must be braced"} will be
+reduced by \TeX{} to \code{A quotation mark, ",
+must be braced}.\refill
+
+In the context of general file headers, this
+convention is not reasonable, because the value
+strings will not in general be processed by
+\TeX{}, but instead, will be treated as verbatim
+strings.\refill
+
+Similarly, although the C programming language has
+character escape conventions to permit encoding of
+non-printable characters in printable form, such
+as \code{\back n} for newline and \code{\back t}
+for horizontal tab, such usages are undesirable in
+the context of general file headers that must
+serve for many different programming languages and
+file types.\refill
+
+Several programming languages adopt the convention
+that a quote inside a quoted string is represented
+by an adjacent pair of quotes. This convention is
+easy to understand, requires no additional escape
+characters, and permits unrestricted
+representation of all printable characters, and of
+course, white space (blanks and horizontal tabs).
+We adopt this convention for attribute value
+strings, but note that since balanced braces
+(parentheses, square brackets, angle brackets) can
+also be used to delimit value strings, the need
+for such doubling will be rare.\refill\c
+\cpsubindex{attribute value}{quote characters in}
+
+\node Attribute descriptions, GNU Emacs editing support, Attribute values, Top
+
+\chapter{Attribute descriptions}\c
+\cindex{attribute descriptions}
+
+In this chapter, we go into the details of each of
+the currently-defined attributes in a standard
+file header. Attributes are treated in
+alphabetical order in the following sections; they
+need not occur in that order in file headers.\refill
+
+\begin{menu}
+* abstract::
+* address::
+* author::
+* checksum::
+* codetable::
+* date::
+* docstring::
+* email::
+* FAX::
+* filename::
+* keywords::
+* supported::
+* telephone::
+* time::
+* URL::
+* version::
+* multiple values::
+\end{menu}
+
+\node abstract, address, Attribute descriptions, Attribute descriptions
+
+\section{Abstract}\c
+\cpsubindex{attribute}{abstract}
+
+The \code{abstract}\c
+\cindex{abstract}
+attribute can supply a short abstract string to
+complement the longer \code{docstring} entry.
+This should normally be limited to a single
+paragraph.\refill
+
+For example, large research institutes often
+prepare an annual publication list with abstracts
+of documents prepared by staff members. With care
+in the preparation of the file headers, and
+suitable software support, much of that annual
+report could be extracted automatically from the
+file headers.\refill
+
+\node address, author, abstract, Attribute descriptions
+
+\section{Address}\c
+\cpsubindex{attribute}{address}
+
+The \code{address}\c
+\cindex{address}
+attribute should have a postal
+address. Be sure to include a country in your
+address; your file may be shared with users all
+around the world.\refill
+
+Here is an example from the file header for this
+document:\refill
+\begin{verbatim}
+%%% address = "Center for Scientific Computing
+%%% Department of Mathematics
+%%% University of Utah
+%%% Salt Lake City, UT 84112
+%%% USA",
+\end{verbatim}
+
+\node author, checksum, address, Attribute descriptions
+
+\section{Author}\c
+\cpsubindex{attribute}{author}
+
+The \code{author}\c
+\cindex{author}
+attribute should give the full
+name of the author, in the order as it is
+conventionally spoken. In much of the Western
+world, the family name goes last.\refill
+
+If there are multiple authors, separate them by
+the word \code{and},\c
+\cindex{and}
+rather than by commas. The
+reason for this is that Bib\TeX{}\c
+\cindex{name parsing}
+has special algorithms that use this convention to
+allow parsing of names in some foreign languages,
+as well as names with qualifiers, like \code{Jr.},
+and those algorithms could be adapted by other
+programs that process file headers. Even simple
+programs could separate the names by splitting at
+the word \code{and}.\refill
+
+Here is the \code{author}\c
+\cindex{author}
+attribute from this
+document's file header:\refill
+\begin{verbatim}
+%%% author = "Nelson H. F. Beebe",
+\end{verbatim}
+
+\node checksum, codetable, author, Attribute descriptions
+
+\section{Checksum}\c
+\cpsubindex{attribute}{checksum}
+
+The background chapter
+(\pxref{Background})
+noted that it is important to be
+able to verify the correctness of files that are
+moved between different computing systems. The
+way that this is traditionally handled is to
+compute a number which depends in some clever way
+on all of the characters in the file, and which
+will change, with high probability, if any
+character in the file is changed.
+Such a number is called a \emph{checksum}.\refill\c
+\cindex{checksum}
+
+Good algorithms for computing checksums are not
+obvious. One possibility is to count up the
+number of characters, words, and lines; in the
+UNIX world, this is easily done with the
+\code{wc}\c
+\pindex{wc}\c
+\cindex{word count}
+program. Another possibility is to just add up
+the numerical values of all the characters and use
+the resulting sum as the checksum. Both of these
+would change if characters were added or removed,
+but they would not change under transposition of
+characters, words, or lines.\refill
+
+Consequently, a lot of research has been done on
+algorithms for finding checksums, and some have
+even achieved international standardization. One
+of these standard algorithms is known as a CRC-16
+checksum. CRC stands for \emph{cyclic redundancy
+checksum},\c
+\cindex{cyclic redundancy checksum}\c
+\cpsubindex{checksum}{cyclic redundancy}
+and the redundancy of following it with
+the word \emph{checksum} is accepted practice.
+The CRC-16 checksum\c
+\cpsubindex{checksum}{CRC-16}
+is capable of detecting error bursts up to 16
+bits, and 99 percent of bursts greater than 16
+bits in length. The checksum number is
+represented as a 16-bit unsigned number,
+encompassing the range 0 \dots{} 65535. Thus,
+there is roughly one chance in 65535 of an error
+not being detected, that is, of two different
+files having the same checksum.\refill
+
+Of course, no human should have to compute a
+checksum; that is a job for a computer program.
+The GNU Emacs support software described in this
+document handles the job for you.\refill
+
+We cannot use just any checksum program, however,
+for several reasons:\refill
+\begin{itemize}
+
+\item
+The checksum program must itself be portable and
+freely available, because verification of the
+checksum may be required on any machine that the
+file is transported to.\refill
+
+\item
+File formats change from system to system. On
+some file systems, text files are represented by
+fixed-length records. On others, variable
+length records include a count of the number of
+characters in each line. On still others, lines
+end with character terminator sequences like CR,
+LF, or CR LF.\refill
+
+\item
+The file must contain the checksum, but somehow,
+the checksum itself must not be counted when the
+checksum is computed. Otherwise, we could never
+achieve self-consistency: each insertion of a new
+checksum would change the checksum.\refill
+
+\item
+Because of the varying line representations in
+file systems, trailing blanks should not be
+included in the checksum. Such blanks waste
+space, and should never be significant; they can
+be lost when text is refilled in a line-wrapping
+editor, or during electronic mail transmission.
+It is a good idea to get rid of them; the Emacs
+file header maintenance functions described
+elsewhere (\pxref{GNU Emacs editing support})
+do this for you automatically.\refill
+
+\item
+Horizontal tabs\c
+\cindex{tab character}
+look like spaces on the computer
+display, but are really separate characters.
+They are often subject to translation to spaces by
+electronic mail systems. For most text files, you
+can safely replace them by blanks, which is easy
+to do in Emacs: just mark the whole buffer with
+\kbd{C-x h}, and then type \kbd{M-x untabify}.\refill
+
+UNIX \code{Makefile}s\c
+\pindex{Makefile}
+and \code{troff}\c
+\pindex{troff}
+files are
+notable exceptions to this; tabs are
+\emph{significant} and cannot be replaced without
+destroying the meaning of those files. That is
+why the GNU Emacs file header maintenance
+functions never touch tabs.\refill
+\end{itemize}
+
+These considerations make it clear than existing
+software for computing checksums just will not do.
+I raised these points in an editorial challenge
+\cite{Beebe:TB11-4-485-487}\c
+\tindex{Beebe, Nelson H. F.}
+in the \TeX{} Users Group\c
+\cindex{TeX Users Group}
+journal, TUGboat,\c
+\cindex{TUGboat}
+and in the spring of 1991 received a clever
+solution from Robert Solovay\c
+\tindex{Solovay, Robert}
+at the University of California,
+Berkeley.\refill
+
+Solovay's program, called simply \code{checksum},\c
+\pindex{checksum}
+is written in a literate programming
+\cindex{literate programming}
+language called CWEB.\c
+\pindex{CWEB}
+The output is C code that conforms
+to the 1989 ANSI/ISO C Standard. In computing the
+checksum, it ignores line terminators, and any
+previous checksum, and since it has been placed in
+the public domain, it solves all of the problems
+noted above. Besides a CRC-16 checksum,\c
+\cpsubindex{checksum}{CRC-16}
+it also produces counts of characters, words, and
+lines. In the event that \code{checksum}\c
+\pindex{checksum}
+has not yet been installed, this information can
+be compared against the output of the UNIX
+\code{wc}\c
+\pindex{wc}\c
+\cindex{word count}
+utility. \code{wc} is simple enough that it can
+easily be reimplemented on any system.\refill
+
+\code{checksum}\c
+\pindex{checksum}
+also has an option to verify the
+correctness of the checksum in a file;\c
+\cpsubindex{checksum}{validation of}
+you could use this to check for corruption after
+transferring a file with standard file headers to
+your system.\refill
+
+Although \code{checksum}\c
+\pindex{checksum}
+can be run manually, the
+GNU Emacs support code does it for you, producing
+an entry in the file header that looks something
+like this:\refill
+\begin{verbatim}
+%%% checksum = "25868 849 3980 28305",
+\end{verbatim}
+
+\noindent
+The four numbers are the CRC-16 checksum,\c
+\cpsubindex{checksum}{CRC-16}
+line count,\c
+\cindex{line count}
+word count,\c
+\cindex{word count}
+and character count.\c
+\cindex{character count}
+You must remember that the character count will
+change if the file is stored with different line
+terminator conventions; the other numbers will
+remain constant.\refill
+
+\node codetable, date, checksum, Attribute descriptions
+
+\section{Codetable}\c
+\cpsubindex{attribute}{codetable}
+
+In the computing world of the 1990s, two major
+character sets are in wide use: EBCDIC\c
+\cindex{EBCDIC character set}\c
+\cpsubindex{character set}{EBCDIC}
+on IBM mainframes and their clones, and
+ISO/ASCII\c
+\cindex{ASCII character set}\c
+\cindex{ISO character set}\c
+\cpsubindex{character set}{ISO}\c
+\cpsubindex{character set}{ASCII}
+on everything else. EBCDIC is an 8-bit character
+set, offering characters in the range 0 \dots{}
+255, while ISO/ASCII is a 7-bit character set,
+with characters in the range 0 \dots{} 127. On
+most machines, ISO/ASCII text is stored in 8-bit
+characters.\refill
+
+In turns of numbers of computers, ISO/ASCII is by
+far the most common, since it is the character set
+used by all personal computers and
+workstations.\refill
+
+Unfortunately, a 128-character set with 95
+printable characters and 33 control characters is
+inadequate for most non-English languages.
+Many European languages require accented
+characters or additional letters, and
+Chinese,\c
+\cindex{Chinese characters}
+Japanese,\c
+\cindex{Japanese characters}
+and Korean\c
+\cindex{Korean characters}
+have thousands of pictographic
+characters.\refill\c
+\cpsubindex{character set}{pictographic}
+
+Consequently, computer vendors have dealt with
+this by offering ISO `code pages'\c
+\cpsubindex{character set}{code pages}
+--- variations
+in the encoding of characters 128 \dots{} 255, and
+sometimes even in the encoding of punctuation
+characters in the range 0 \dots{} 127.\refill
+
+Standards bodies are actively working on the
+development of a new character set that will
+support all, or almost all, of the world's present
+and past languages. One of these efforts is a
+16-bit character set called Unicode,\c
+\cpsubindex{character set}{Unicode}
+and another
+is a 32-bit character set called ISO 10646.\c
+\cpsubindex{character set}{ISO 10646}
+Efforts are now underway to merge these efforts
+into a character set called ISO 10646M (M for
+merged).\refill\c
+\cpsubindex{character set}{ISO 10646M}
+
+Given the speed at which committees work, and the
+enormous impact on millions of computers, and
+people, of a change in text encoding, it seems
+unlikely that the impact of these efforts will be
+felt for another decade.\refill
+
+The code page problem, however, does have to be
+dealt with. The standard file headers provide for
+this with an attribute entry like\refill
+\begin{verbatim}
+%%% codetable = "ISO/ASCII",
+\end{verbatim}
+
+\noindent
+If the file is encoded in, say code page
+ISO-8859-3, then the header could say that:\refill
+\begin{verbatim}
+%%% codetable = "ISO-8859-3",
+\end{verbatim}
+
+\noindent
+Of course, if an ASCII file were transferred to a
+system with EBCDIC, the file would not be
+immediately readable until the character values
+were translated to EBCDIC. The checksum described
+in the preceding section would be incorrect, but
+at least the fact that the file header stated that
+the code was originally ISO/ASCII would explain
+any translation peculiarities that cropped up
+later.\refill
+
+The attribute name \code{codetable}\c
+\cindex{codetable}
+was chosen
+over \code{codepage} because the latter notion is
+restricted to variants of ISO/ASCII.\refill
+
+\node date, docstring, codetable, Attribute descriptions
+
+\section{Date}\c
+\cpsubindex{attribute}{date}
+
+Computer files should always carry a date-and-time\c
+\cindex{time stamp}\c
+\cindex{date stamp}
+stamp to record time of the last modification.
+Some file systems even store date-and-time stamps
+for last read, last write, last backup, and so
+on.\refill
+
+Unfortunately, many computers do not have a
+reliable time standard, and if they lack a network
+connection, have no way of maintaining a correct
+one. Date-and-time stamps are recorded in the
+file system, rather than the file itself, and are
+usually lost when the file is transferred to
+another system. That is regrettable, but it is a
+fact of life we still have to tolerate.\refill
+
+Consequently, a standard file header should carry
+a date and time. The editing support described
+here supplies it in the form\refill
+\begin{verbatim}
+%%% date = "07 Oct 1991",
+\end{verbatim}
+
+Dates and times are expressed in a variety of
+formats that depend on the country and culture.\c
+\cpsubindex{date}{cultural dependence}\c
+\cpsubindex{time}{cultural dependence}
+Some software can deal with a considerable variety
+of formats, ranging from ``last Wednesday'' to
+``1991.11.06:12.34.17''. The important point is
+that the encoding \emph{must be unambiguous}. In
+particular, forms like \code{12/06/91} should be
+avoided: does it mean the 12th day of the 6th
+month, or the 6th day of the 12th month? The year
+should \emph{not} be abbreviated to two digits;
+the new millenium is not far away.\refill
+
+\node docstring, email, date, Attribute descriptions
+
+\section{Docstring}\c
+\cpsubindex{attribute}{docstring}
+
+For the purposes of cataloging files, and
+recognizing their contents, it is helpful to have
+a few paragraphs of description. This is provided
+for by the \code{docstring}\c
+\cindex{docstring}
+attribute, which might
+look like this:\refill
+\begin{verbatim}
+%%% 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.",
+\end{verbatim}
+
+This documentation need not be a user's manual for
+the file, unless the necessary information can be
+communicated in a few paragraphs of no more than a
+couple of thousand characters. Think of it
+instead as an extended abstract.\refill\c
+\cindex{abstract}\c
+\cpsubindex{documentation string}{as abstract}
+
+Someday, we may have tools that will extract
+documentation strings from standard file headers
+and turn them into catalogs.\refill
+
+\node email, FAX, docstring, Attribute descriptions
+
+\section{Email}\c
+\cpsubindex{attribute}{email}
+
+People who exchange computer files now often have
+network access, and the worldwide Internet is
+growing rapidly. It will not be long before
+network connections are as commonplace, and
+important, as telephone connections now are. Most
+networks support electronic mail, and the trend is
+to develop uniform addressing schemes that will
+work the world over. Thus, an electronic mail\c
+\cindex{electronic mail}
+address, when available, is as important as a
+postal address\c
+\cindex{postal address}
+for the author(s).\refill
+
+Here is an example:\refill
+\begin{verbatim}
+%%% email = "beebe@math.utah.edu (Internet)",
+\end{verbatim}
+
+\noindent
+Since there are several networks in existence,
+with different naming conventions, it is helpful
+to identify the network as in this example.\refill
+
+In the event that there are multiple authors,
+electronic mail addresses should be given in the
+same order, separated by the word \code{and}, just
+the way the author attribute value is coded. Of
+course, not all of the authors might have such an
+address, so additional qualification, such as by a
+parenthesized set of initials, could follow each
+address. Use your ingenuity, but in such a way
+that someone you've never met will still
+understand what you mean.\refill
+
+\node FAX, filename, email, Attribute descriptions
+
+\section{FAX}\c
+\cpsubindex{attribute}{fax}
+
+The \code{FAX}\c
+\cindex{FAX}
+attribute should be formatted just
+like the \code{telephone}\c
+\cindex{telephone}
+entry. Here is an
+example:\refill
+\begin{verbatim}
+%%% FAX = "+1 801 581 4148",
+\end{verbatim}
+
+FAX machines are now very commonly used in
+business throughout the world, so if you have such
+a facility, it is a good idea to include it in the
+file header.\refill
+
+\node filename, keywords, FAX, Attribute descriptions
+
+\section{Filename}\c
+\cpsubindex{attribute}{filename}
+
+Different computing systems have different file
+naming conventions; in particular, there are
+significant variations in the naming of files.
+Some systems, like the Apple Macintosh, permit
+arbitrary strings of characters, including blanks.
+Others, like MS DOS on the IBM PC and clones,
+limit names to two parts, a base name and an
+extension, or type, with the two separated by a
+period (dot, full stop).\refill
+
+File headers should therefore carry an indication
+of the original name of the file, and if the file
+is expected to be referenced by other files, then
+it is \emph{imperative} that the name chosen be
+representable on a wide variety of, and preferably
+all, computing systems. Today, this in practice
+means the 8-character base name and 3-character
+file extension of MS DOS, which runs in tens of
+millions of personal computers.\c
+\cpsubindex{filename}{portable subset}
+There are still a few survivors of older operating
+systems with more stringent requirements on file
+names, but they are obsolete and rapidly
+disappearing.\refill
+
+The filename should be case \emph{insensitive},\c
+\cpsubindex{filename}{case insensitivity}
+and in the header, spelled in lower-case letters.
+It should start with a letter, and use only
+letters, digits, and perhaps, hyphens (minus
+signs) in the rest of the name, with no more than
+a single period in the name.\refill\c
+\cpsubindex{filename}{characters allowed in}
+
+This document's file header contains the attribute
+entry\refill
+\begin{verbatim}
+%%% filename = "filehdr.ltx",
+\end{verbatim}
+
+\noindent
+\code{filehdr} is an abbreviation for ``file
+header'', and \code{ltx} for ``\LaTeX{}'',\c
+\cindex{LaTeX}
+the name of the document formatting system that
+typesets this document.\refill
+
+\node keywords, supported, filename, Attribute descriptions
+
+\section{Keywords}\c
+\cpsubindex{attribute}{keywords}
+
+Large archives always pose a search problem for
+human users, and it has long been traditional to
+try to classify members of the archives by
+\emph{keywords} that might come to mind when
+someone is searching for the file. Some journals
+have standard sets of keywords to classify
+articles by, and include them near the abstract of
+each paper.\refill
+
+With standard file headers, the range of possible
+keywords is enormous, and authors will just have
+to be diligent about finding good sets of
+descriptive keywords. They should appear in the
+attribute value as phrases separated by commas, as
+for this document:\refill
+\begin{verbatim}
+%%% keywords = "file header, checksum",
+\end{verbatim}
+
+\node supported, telephone, keywords, Attribute descriptions
+
+\section{Supported}\c
+\cpsubindex{attribute}{supported}
+
+All computer files reach a stage of stagnation,
+where for various reasons, their authors no longer
+maintain them. Nevertheless, it is helpful to
+know whether the author of a given file is
+interested in hearing of problems or comments, and
+the file header can say so by an entry like this
+one:\refill
+\begin{verbatim}
+%%% supported = "yes",
+\end{verbatim}
+
+If it says \code{yes}, this does not provide any
+guarantee that any problems reported will be
+fixed, but just that the author's intentions are
+good, and reasonable efforts will be made to do
+so. Some authors even care so much about their
+work that they offer monetary rewards for reports
+of bugs and errors.\refill
+
+If it says \code{no}, then you are on your own,
+because the author never wants to hear from you on
+the subject of this particular file.\refill
+
+Other attribute values can be readily imagined,
+like \code{only for money, cash in advance}, but a
+simple \code{yes} or \code{no} is probably
+adequate for most people.\refill
+
+\node telephone, time, supported, Attribute descriptions
+
+\section{Telephone}\c
+\cpsubindex{attribute}{telephone}
+
+The \code{telephone}\c
+\cindex{telephone}
+attribute should include the
+area code with telephone number. If there are
+multiple values, separate them by commas. Here is
+an example from the file header of this document:\refill
+\begin{verbatim}
+%%% telephone = "+1 801 581 5254",
+\end{verbatim}
+Use the international form of the number,
+including the country and city\slash area code.
+
+\node time, version, telephone, Attribute descriptions
+
+\section{Time}\c
+\cpsubindex{attribute}{time}
+
+The \code{time}\c
+\cindex{time}
+attribute should be of the form
+\code{hh:mm:ss}, or if a time zone abbreviation
+(say, \code{GMT}) can be found, \code{hh:mm:ss
+GMT}. It is recorded separately from the
+\code{date}\c
+\cindex{date}
+to ease the parsing job of software
+that processes file headers.\refill
+
+Here is a typical example:\refill
+\begin{verbatim}
+%%% time = "18:02:38 MST",
+\end{verbatim}
+
+\node version, multiple values, time, Attribute descriptions
+
+\section{URL}\c
+\cpsubindex{attribute}{URL}
+
+Since its introduction in the early 1990s, the
+WorldWide Web has spread rapidly, so that most
+public interest in the Internet is associated with
+it, and so that most Internet sites that
+previously had electronic mail, ftp, and telnet
+services, now also have a WorldWide Web presence.\refill
+
+The Uniform Resource Locator, or URL, is therefore
+a suitable addition to the standard file headers;
+the one in this file looks like this:\refill
+\begin{verbatim}
+%%% URL = "http://www.math.utah.edu/~beebe",
+\end{verbatim}
+
+Since most sites have found it convenient to name
+a particular machine with the prefix ``www.'',
+from an electronic mail address one can often
+guess what the corresponding URL should be.
+Nevertheless, the host with that name is often
+different from the login host, so the Emacs code
+in \file{filehdr.el} may not successfully identify
+it automatically. Thus, you can provide an
+overriding private definition like this in your
+\file{.emacs} startup file:\refill
+\begin{verbatim}
+(setq file-header-user-URL "http://www.math.utah.edu/~beebe")
+\end{verbatim}
+\vindex{file-header-user-URL}
+
+
+\section{Version}\c
+\cpsubindex{attribute}{version}
+
+Computer files created by humans almost inevitably
+go through many revisions, whether they are
+programs to control a satellite, or just the words
+of a promotion for the latest soap product.\refill
+
+Computer vendors have long dealt with this by
+attaching \emph{version numbers}\c
+\cindex{version number}
+to software releases. These consist of two or
+three numbers with some separator character, such
+as a period (full stop, dot). The first number is
+called the \emph{major version number}; it gets
+changed only at long intervals, usually years,
+when really significant changes have been
+incorporated. A second number is a \emph{minor
+version number} which is incremented as smaller
+changes and bug fixes are incorporated. Sometimes
+a third number is appended, which is an \emph{edit
+number}; it gets incremented every time any change
+at all is made to the file.\refill
+
+In careful software production, a change log\c
+\cindex{change log}
+is kept to record the reasons for every change;
+this is particularly important when commercial
+interests or legal issues are at stake. [Military
+organizations the world over are famous for their
+paperwork trails; perhaps that is what helps to
+keep them busy during times of peace.]\refill
+
+For smaller files, you can probably get by with
+just a major version number and an edit number;
+for larger projects, three or more are
+recommended.\refill
+
+Here is what one version of this document had in
+its standard file header:\refill
+\begin{verbatim}
+%%% version = "1.01",
+\end{verbatim}
+
+Version numbers are particularly useful when
+reporting problems to the author of a file; they
+allow rapid verification of whether the author and
+end user are even talking about the same
+thing.\refill
+
+\node multiple values, Attribute descriptions, version, Attribute descriptions
+
+\section{Multiple values}\c
+\cpsubindex{attribute}{multiple values}
+
+Keywords like \code{author}\c
+\cindex{author}
+and \code{address}\c
+\cindex{address}
+may be inadequate for files prepared by more than
+one person. If several authors share a common
+address, then using the keyword \code{and},\c
+\cindex{and}
+to separate names in the \code{author}\c
+\cindex{author}
+field is unambiguous. However, if the postal
+address, electronic mail address, telephone
+number, and FAX number vary, it is advisable to
+clarify the header by attaching a hyphen and a
+numeric suffix to the attribute name. Here is an
+example:\refill
+\begin{verbatim}
+%%% author-1 = "Marie Claire LeBrun",
+%%% author-2 = "Hans Peter Brun",
+%%% author-3 = "Jill Brown",
+%%% address-1 = "...",
+%%% address-2 = "...",
+%%% address-3 = "...",
+%%% email-1 = "...",
+%%% email-2 = "...",
+%%% email-3 = "...",
+%%% telephone-1 = "...",
+%%% telephone-2 = "...",
+%%% telephone-3 = "...",
+%%% FAX = "...",
+\end{verbatim}
+
+File-header parsing software must be prepared to
+handle numeric suffixes like this for any keyword.
+If a keyword doesn't have such a suffix, as the
+\code{FAX}\c
+\cindex{FAX}
+keyword in this example, then it should be assumed
+to apply to all authors.\refill
+
+\node GNU Emacs editing support, Simple customization, Attribute descriptions, Top
+
+\chapter{GNU Emacs editing support}\c
+\cindex{editing support}\c
+\cindex{Emacs editing support}\c
+\cindex{GNU Emacs editing support}
+
+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.\refill
+
+The GNU Emacs file
+\file{filehdr.el} contains the following
+user-callable functions:\refill
+\begin{verbatim}
+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
+\end{verbatim}
+
+There are several other functions in that file,
+but they are for internal use only, and will not
+be further documented here.\refill
+
+When you want to add a new file header to an
+existing file, you just type \kbd{M-x
+make-file-header}; this produces something like
+this at the top of your file:\refill
+\begin{verbatim}
+%%% ====================================================================
+%%% @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.",
+%%% }
+%%% ====================================================================
+\end{verbatim}
+
+\noindent
+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 \file{/etc/passwd}; on
+VAX VMS, it will come from the file
+\file{SYS$MANAGER:SYSUAF.DAT}.\refill
+
+The comment syntax was determined from the file
+extension, and we'll say more about it
+later.\refill
+
+The only information above that Emacs cannot
+determine is your postal address,\c
+\cpsubindex{postal address}{defining}
+and telephone\c
+\cpsubindex{telephone number}{defining}
+and FAX numbers, and possibly, your WorldWide Web
+URL.\c
+\cpsubindex{FAX number}{defining}
+These only have to be supplied once, usually in
+your GNU Emacs startup file, \file{.emacs}. This
+is most easily done with Lisp code that looks
+something like this:\refill
+\begin{verbatim}
+(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")
+\end{verbatim}
+\vindex{file-header-user-address}\c
+\vindex{file-header-user-telephone}\c
+\vindex{file-header-user-FAX}
+\vindex{file-header-user-URL}
+
+Once this is installed in the \file{.emacs} file,
+GNU Emacs will find it every time it starts up.\refill
+
+If the electronic-mail address constructed from
+the Emacs
+\code{user-login-name}\c
+\findex{user-login-name}
+and
+\code{system-name}\c
+\findex{system-name}
+functions is not suitable, you can provide an
+alternative one like this:\refill
+\begin{verbatim}
+(setq file-header-user-email "beebe@math.utah.edu")
+\end{verbatim}
+\vindex{file-header-user-email}\c
+
+\noindent
+In any of the following situations, you
+should set \code{file-header-user-email}\c
+\vindex{file-header-user-email}
+in your startup \file{.emacs} file.\refill
+\begin{itemize}
+
+\item
+You work on multiple machines, but prefer to have
+only one public electronic-mail address.\refill
+
+\item
+At some sites, \code{system-name}\c
+\findex{system-name}
+does not return a fully-qualified Internet host
+name, so the default address constructed by
+\code{file-header-email}\c
+\findex{file-header-email}
+is unusable outside your local
+installation.\refill
+
+\item
+Your site is not on the Internet, but you can
+receive electronic mail via some other
+network.\refill
+\end{itemize}
+
+The version number is left empty; you can manually
+insert an appropriate one, perhaps 1.00, or if you
+are just starting, 0.00.\refill
+
+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.\refill
+
+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 \kbd{M-x
+update-file-header-and-save}, and with Emacs'
+normal command completion, you can probably hit
+the tab key after the \kbd{f} in \kbd{file}.\refill
+
+The function \code{update-file-header-and-save}\c
+\findex{update-file-header-and-save}
+will update the date and time stamps, the minor
+version number, the checksum, and save the
+file.\refill
+
+If the file is a \LaTeX{}\c
+\cpsubindex{LaTeX}{date update}
+file, the date update
+will also search forward for text that looks
+something like\refill
+\begin{verbatim}
+\\date{29 November 1991 \\
+Version 1.01}
+\end{verbatim}
+
+\noindent
+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.\refill
+
+You can do these updates manually if you like by
+invoking the functions
+\code{update-checksum},\c
+\findex{update-checksum}
+\code{update-date},\c
+\findex{update-date}
+\code{update-minor-version},\c
+\findex{update-minor-version}
+and
+\code{update-date-and-minor-version}\c
+\findex{update-date-and-minor-version}
+explicitly.\refill
+
+Major version numbers are rarely changed, and you
+could easily do the job manually. Nevertheless,
+for completeness, \code{update-major-version}\c
+\findex{update-major-version}
+is supplied to automate the job.\refill
+
+\code{update-checksum}\c
+\findex{update-checksum}
+will trim trailing
+whitespace\c
+\cpsubindex{whitespace}{discarding trailing}
+(but leave embedded tabs intact), send the buffer
+to the \file{checksum} program, and replace it
+with the output. Don't interrupt it while it is
+working, or you might lose your file!\refill
+\typeout{Check interruption of update-checksum;
+maybe use save-for-undo}\c
+\typeout{Maybe should have man pages for checksum
+in an appendix?}\c
+
+The Emacs interface to \file{checksum} has not yet
+been tested on VAX VMS,\c
+\cindex{VAX VMS}
+so
+\code{update-checksum}\c
+\findex{update-checksum}
+on that system calls
+\code{update-simple-checksum}\c
+\findex{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 \code{checksum}\c
+\pindex{checksum}
+installed yet.
+\code{checksum} should be available from the same
+place you got \file{filehdr.el}; eventually it
+will be on dozens of \TeX{} archive machines
+around the world.\refill
+
+\node Simple customization, Advanced customization, GNU Emacs editing support, Top
+
+\chapter{Simple customization}\c
+\cpsubindex{customization}{simple}
+
+The GNU Emacs Lisp code in \file{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!\refill
+
+The code contains several large tables stored in Lisp
+variables:\refill
+\begin{verbatim}
+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
+\end{verbatim}
+
+\noindent
+These are not intended to be modified by users, as
+the phrase \code{-standard-} in their names
+indicates.\refill
+
+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.\refill
+
+The first of them,
+\code{file-header-standard-at-sign-special-cases},\c
+\vindex{file-header-standard-at-sign-special-cases}
+is used to handle those few exceptional file
+classes that do not permit at-signs, \code{@}, to
+be used in comments without special handling.
+Here is the current value of this variable:\refill
+\begin{verbatim}
+(
+ ("BibTeX" " at ")
+ ("C-Web" "@@")
+ ("Web" "@@")
+ ("Web-change" "@@")
+)
+\end{verbatim}
+
+\noindent
+This means that when a header for a file in class
+\samp{BibTeX} is created, at-signs should be
+replaced by the string \samp{ at }. For the other
+classes, at-signs must be doubled.\refill
+
+The second variable,
+\code{file-header-standard-comment-prefixes},\c
+\vindex{file-header-standard-comment-prefixes}
+has
+a very long value, so we show only a portion
+here:\refill
+\begin{verbatim}
+(
+ ("Adobe-Font-Metric" "Comment ")
+ ("AmSTeX" "%%% ")
+ ("Awk" "### ")
+...
+ ("Web-change" "%%% ")
+ ("Yacc" "")
+)
+\end{verbatim}
+
+\noindent
+This means that in an Adobe Font Metric file,\c
+\cindex{Adobe Font Metric file}
+comments must begin a line with the string
+\samp{Comment }. For \code{awk}\c
+\pindex{awk}
+files, a triple
+sharp sign and a space will begin all file header
+lines. \code{yacc}\c
+\pindex{yacc}
+file headers have no comment
+prefix at all.\refill
+
+The third variable,
+\code{file-header-standard-entries},\c
+\vindex{file-header-standard-entries}
+contains pairs of entry names and functions to
+supply values for them. It looks something like
+this: \refill
+\begin{verbatim}
+(
+ ("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)
+)
+\end{verbatim}
+
+\noindent
+The file header is created by processing these
+entry names in order.\refill
+
+The fourth variable, with the name
+\code{file-header-standard-paired-comment-delimiter-languages},\c
+\vindex{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:\refill
+\begin{verbatim}
+(
+ ("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"))
+ )
+)
+\end{verbatim}
+
+\noindent
+To avoid the need for long constant strings in the
+code, several of them are generated dynamically
+by the Lisp concatenation operator,
+\code{concat}.\refill\c
+\findex{concat}
+
+Class names in this variable do \emph{not} include
+the phrase \code{-file} that appears in the file
+header; that suffix is supplied automatically by
+the Emacs functions.\refill
+
+The last variable,
+\code{file-header-standard-suffix-and-type},\c
+\vindex{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:\refill
+\begin{verbatim}
+(
+ ("1" "Troff-man")
+ ("1l" "Troff-man")
+ ("2" "Troff-man")
+...
+ ("afm" "Adobe-Font-Metric")
+...
+ ("web" "Web")
+ ("y" "Yacc")
+ ("yacc" "Yacc")
+)
+\end{verbatim}
+
+\noindent
+Observe that the extensions do \emph{not} include
+a leading period.\refill
+
+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 \code{UNKNOWN}.\refill
+
+Here now is how you can customize the behavior of
+\code{make-file-header}.\c
+\findex{make-file-header}
+For each Lisp variable with
+the phrase \code{-standard-}, there is a
+corresponding one with the phrase \code{-extra-}
+instead. These new variables are intended for
+user customization; you can initialize them in
+your startup \file{.emacs} file, and they will
+automatically be added to the standard ones at run
+time.\refill
+
+Here is a set of sample customizations:\refill\c
+\cpsubindex{customization}{examples}
+\begin{verbatim}
+(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"))
+ ))
+\end{verbatim}
+\vindex{file-header-extra-at-sign-special-cases}\c
+\vindex{file-header-extra-comment-prefixes}\c
+\vindex{file-header-extra-entries}\c
+\vindex{file-header-extra-suffix-and-type}\c
+\vindex{file-header-extra-paired-comment-delimiter-languages}\c
+
+\noindent
+These would define a new file class \code{Foo-Bar}
+attached to files with extension \code{.foobar},
+for which comments are delimited by \code{/# \dots{} #/},
+and by \code{!} to end-of-line. The file header body
+lines would all begin with \code{!FB!}.\refill
+
+The Lisp form \code{(setq var value)}\c
+\findex{setq}
+assigns \code{value} to the variable \code{var}; most
+other programming languages would write this as
+\code{var = value}.\refill
+
+The extra values set in these variables are
+appended to the end of the standard ones, so they
+can augment, \emph{but not replace}, the standard
+values. This design choice was made intentionally
+to encourage \emph{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.\refill
+
+You can test your additions by visiting
+files with the new extensions, and then running
+\kbd{M-x make-file-header}.\refill\c
+\findex{make-file-header}
+
+You can test the entire collection of code by
+typing \kbd{M-x test-file-header}.\c
+\findex{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
+\code{file-header-standard-suffix-and-type}\c
+\vindex{file-header-standard-suffix-and-type}
+and
+\code{file-header-extra-suffix-and-type}.\refill\c
+\vindex{file-header-extra-suffix-and-type}
+
+To see the settings of the variables named
+\code{file-header-standard-xxx}\c
+\vindex{file-header-standard-xxx}
+and
+\code{file-header-extra-xxx},\c
+\vindex{file-header-extra-xxx}
+type
+\kbd{M-x show-file-header-variables}.\c
+\findex{show-file-header-variables}
+The results will appear in a temporary
+buffer.\refill
+
+Prior to version 19 (released in early summer of
+1993), GNU Emacs did not provide the time zone,\c
+\cindex{time zone}
+but on UNIX systems, it can
+be obtained from the output of the \code{date}\c
+\pindex{date}
+command. Since this takes a few seconds to run as
+a subprocess, the result is saved in a global
+variable, \code{file-header-timezone-string}.\c
+\vindex{file-header-timezone-string}
+Subsequent file headers will be produced much more
+rapidly. With Version 19 or later, this delay is
+eliminated.
+\refill
+
+If you find the delay on the first use
+objectionable, you can set the time zone in your
+\file{.emacs} file:\refill
+\begin{verbatim}
+(setq file-header-timezone-string "MST")
+\end{verbatim}
+
+\noindent
+This practice is not recommended, since you'll
+have to change it twice a year, or if you work in
+a different time zone.\refill
+
+\node Advanced customization, Bug reporting, Simple customization, Top
+
+\chapter{Advanced customization}\c
+\cpsubindex{customization}{advanced}
+
+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 \file{filehdr.el}. \emph{Under no
+circumstances should you modify \file{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.\refill
+
+If you are a real Lisp wizard, you can just read
+the code in \file{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.''\refill
+
+The most likely function you'll want to modify is
+\code{make-file-header}.\c
+\findex{make-file-header}
+Here is what its body
+looks like:\refill
+\begin{verbatim}
+ (file-header-comment-block-begin)
+ (file-header-entry)
+ (mapcar '(lambda (entry)
+ (file-header-key (car entry) (nth 1 entry)))
+ (append file-header-standard-entries
+ file-header-extra-entries))
+ (file-header-exit)
+ (file-header-comment-block-end)
+\end{verbatim}
+\vindex{file-header-standard-entries}\c
+\vindex{file-header-extra-entries}\c
+\findex{file-header-comment-block-begin}\c
+\findex{file-header-entry}\c
+\findex{lambda}\c
+\findex{mapcar}\c
+\findex{append}\c
+\findex{file-header-key}\c
+\findex{car}\c
+\findex{nth}\c
+\findex{file-header-exit}\c
+\findex{file-header-comment-block-end}\c
+
+\noindent
+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.\refill
+
+The first and last function calls provide a full
+line comment start and end, if the file class
+requires it.\refill
+
+The \code{file-header-entry}\c
+\findex{file-header-entry}
+and \code{file-header-exit}\c
+\findex{file-header-exit}
+functions supply the class name tag and the final
+closing brace. That is, they generate something
+like this:\refill
+\begin{verbatim}
+%%% @LaTeX-file{
+%%% }
+\end{verbatim}
+
+\noindent
+The individual file attributes are then supplied
+by calls to the generic function
+\code{file-header-key},\c
+\findex{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
+\code{file-header-key}.\refill
+
+The Lisp \code{mapcar}\c
+\findex{mapcar}
+function called in the body
+of \code{make-file-header}\c
+\findex{make-file-header}
+applies its second argument, here an anonymous
+\code{lambda}\c
+\findex{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 \code{file-header-standard-entries}\c
+\vindex{file-header-standard-entries}
+and
+\code{file-header-extra-entries},\c
+\vindex{file-header-extra-entries}
+which are
+appended into one big list.\refill
+
+Here is a simple example of one of these
+initial value-returning functions:\refill
+\begin{verbatim}
+(defun file-header-codetable ()
+ "Return as a string the default codetable value."
+ "ISO/ASCII"
+ )
+\end{verbatim}
+
+If you want to add a new file header attribute
+entry, you need to add an entry to
+\code{file-header-extra-entries},\c
+\vindex{file-header-extra-entries}
+and write a
+function to return an appropriate initial
+value.\refill
+
+This is best illustrated by a real example---the
+addition of a copyright attribute\c
+\cpsubindex{attribute}{copyright}
+in the file header.\refill
+
+First we insert the lines\refill
+\begin{verbatim}
+(setq file-header-extra-entries
+ '(
+ ("copyright" file-header-copyright)
+ ))
+\end{verbatim}
+
+\noindent
+in the \file{.emacs} file.\refill
+
+Next, we write the function to return the initial
+value:\refill
+\begin{verbatim}
+(defun file-header-copyright ()
+ "Return as a string the default copyright value."
+ "None. This file is PUBLIC DOMAIN."
+)
+\end{verbatim}
+
+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 \kbd{ESC C-x} with the
+cursor inside the function, and then run it by
+name from the minibuffer:
+\kbd{ESC ESC (file-header-copyright)}.\refill
+
+When you run \code{make-file-header},\c
+\findex{make-file-header}
+it should now produce an attribute entry
+like\refill
+\begin{verbatim}
+%%% copyright = "None. This file is PUBLIC DOMAIN.",
+\end{verbatim}
+
+When everything is working, save the new Emacs
+Lisp file, and run \kbd{M-x byte-compile-file} on
+it. You can then load it interactively with
+\kbd{M-x load-file}, or better, automatically at
+Emacs start-up time by adding the line\refill
+\begin{verbatim}
+(load "myfilhdr" t t nil)
+\end{verbatim}
+
+\noindent
+assuming you called the modified file \file{myfilhdr.el}.\refill
+
+If the code in \file{myfilhdr.el} is short, you
+can keep it in your \file{.emacs} instead, and
+altogether avoid the need for a separate file and
+the byte compilation and \code{load}\c
+\findex{load}
+command.
+Compilation is only useful for speeding up the
+loading of large files of Emacs Lisp code.\refill
+
+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
+\code{update-file-header-and-save}\c
+\findex{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.\refill
+
+\node Bug reporting, Bibliography, Advanced customization, Top
+
+\chapter{Bug reporting}\c
+\cindex{bug reporting}
+
+Bug reports, and comments, are actively solicited.
+Electronic mail to the author is most convenient,
+but postal mail, preferably accompanied by
+machine-readable material on Apple Macintosh or
+IBM PC floppy disks, are also acceptable. Shorter
+communications via FAX are also possible. Here
+are the necessary addresses and telephone numbers:\refill
+
+\begin{verbatim}
+Nelson H. F. Beebe
+Center for Scientific Computing
+Department of Mathematics
+University of Utah
+Salt Lake City, UT 84112
+USA
+Tel: +1 801 581 5254
+FAX: +1 801 581 4148
+Email: beebe@math.utah.edu
+URL: http://www.math.utah.edu/~beebe
+\end{verbatim}
+
+\node Bibliography, Concept Index, Bug Reporting, Top
+
+\begin{ifinfo}
+\begin{description}
+\item[Beebe:TB11-4-485-487]
+Nelson H. F. Beebe.
+{{From the President}}.
+\emph{TUGboat}, 11(4):485--487, November
+1990.\refill
+
+\item[Lamport:LDP85]
+Leslie Lamport.
+\emph{{\LaTeX}---A Document Preparation
+System---User's Guide and Reference Manual}.
+Ad{\-d}i{\-s}on-Wes{\-l}ey, 1985.\refill
+
+\item[Lottor:CACM-34-11-21]
+Mark Lottor.
+Internet domain system.
+\emph{Communications of the Association for Computing Machinery},
+34(11):21--22, November 1991.\refill
+This letter reports that the ZONE program at the
+Network Information Systems Center at SRI
+International in July 1991 found approximately
+535,000 Internet hosts in 16,000 domains. The 10
+largest domains were EDU (educational)--206,000,
+COM (commercial)--144,000, GOV
+(government)---36,000, MIL (military) 26,000, AU
+(Australia)--22,000, DE (Germany)---21,000, CA
+(Canada)--19,000, ORG (organizations)---15,000, SE
+(Sweden)---12,000, and CH
+(Switzerland)---10,000.\refill
+
+\item[Unilogic:SDP84]
+Unilogic, Ltd.
+\emph{Scribe Document Production System User
+Manual}, April 1984.\refill
+\end{description}
+\end{ifinfo}
+
+\begin{iftex}
+\bibliography{filehdr}
+\end{iftex}
+
+\onecolumn
+
+\node Concept index, Function index, Bibliography, Top
+
+\begin{ifinfo}
+\chapter*{Concept index}
+\end{ifinfo}
+\begin{iftex}
+\unnumbered{Concept index}
+\end{iftex}
+\cindex{concept index}
+\cpsubindex{index}{concept}
+\printindex{cp}
+
+\onecolumn
+\node Function index, Person index, Concept index, Top
+
+\begin{ifinfo}
+\chapter*{Function index}
+\end{ifinfo}
+\begin{iftex}
+\unnumbered{Function index}
+\end{iftex}
+\cindex{function index}
+\cpsubindex{index}{function}
+\printindex{fn}
+
+\onecolumn
+\node Person index, Program index, Function index, Top
+
+\begin{ifinfo}
+\chapter*{Person index}
+\end{ifinfo}
+\begin{iftex}
+\unnumbered{Person index}
+\end{iftex}
+\cindex{person index}
+\cpsubindex{index}{person}
+\printindex{tp}
+
+\onecolumn
+\node Program index, Variable index, Person index, Top
+
+\begin{ifinfo}
+\chapter*{Program index}
+\end{ifinfo}
+\begin{iftex}
+\unnumbered{Program index}
+\end{iftex}
+\cindex{program index}
+\cpsubindex{index}{program}
+\printindex{pg}
+
+\onecolumn
+\node Variable index, Top, Program index, Top
+
+\begin{ifinfo}
+\chapter*{Variable index}
+\end{ifinfo}
+\begin{iftex}
+\unnumbered{Variable index}
+\end{iftex}
+\cindex{variable index}
+\cpsubindex{index}{variable}
+\printindex{vr}
+
+\end{document}
+%%% This is for GNU Emacs file-specific customization:
+%%% Local Variables:
+%%% fill-column: 50
+%%% End:
diff --git a/support/filehdr/filehdr.pdf b/support/filehdr/filehdr.pdf
new file mode 100644
index 0000000000..47a91a9a99
--- /dev/null
+++ b/support/filehdr/filehdr.pdf
Binary files differ
diff --git a/support/filehdr/filehdr.sok b/support/filehdr/filehdr.sok
new file mode 100644
index 0000000000..b18191bcdf
--- /dev/null
+++ b/support/filehdr/filehdr.sok
@@ -0,0 +1,176 @@
+0pt
+10646M
+12th
+1990s
+1filll
+3am
+ANSI
+Berkeley
+Bitnet
+Blah
+Brian
+Brun
+C
+CR
+CRC
+CWEB
+Carnegie
+Clarkson
+Codetable
+DOS
+Darmstadt
+Docstring
+E
+EBCDIC
+Emacs
+Email
+F
+FAX
+Filename
+Fortran's
+GMT
+GNU
+Goettingen
+H
+Heidelberg
+IBM
+ISBN
+ISO
+Inc
+Internet
+Jr
+Korean
+LF
+LaTeX
+LaTeXinfo
+Lamport
+Lamport's
+LeBrun
+Leslie
+Lotter
+M
+Macintosh
+Mainz
+Makefile
+Mellon
+Mike
+Nelson
+Oren
+PC
+PL
+Pascal's
+Patashnik
+Ph
+Ph.D
+Reid
+Robert
+SYS
+Solovay
+Solovay's
+Stanford
+TMZ
+TUGboat
+TeX
+Tel
+UNIX
+URL
+USA
+UT
+Unicode
+Usenet
+VAX
+VMS
+Wednesday'
+WorldWide
+al
+arabic
+attribute1
+attribute2
+attribute3
+attribute4
+attribute5
+author's
+beebe
+bibtex
+blah
+c
+callable
+codepage
+codetable
+cp
+dir
+docstring
+document's
+edu
+emacs
+email
+emph
+et
+fax
+filehdr
+filehdr.el
+filehdr.info
+filename
+filll
+fn
+formatted
+ftp
+h
+header'
+hh
+hh:mm:ss
+http
+hyphenation
+iftex
+info
+ky
+latex.el
+latexinfo
+latexinfo,rcs
+ltx
+mainframes
+math.utah.edu
+millenium
+millions
+mm
+n
+newline
+newlines
+passwd
+pg
+pictographic
+programmatic
+pt
+rcs
+record'
+reimplemented
+roman
+s
+saltines
+setq
+ss
+stagnation
+t
+telnet
+th
+tp
+transliteration
+troff
+typesets
+typesetting
+unrecorded
+untabify
+utah
+value1
+value2
+value3
+value4
+value5
+verbatim
+vr
+wc
+workstations
+www
+www.math.utah.edu
+x
+xxx
diff --git a/support/filehdr/makeinfo b/support/filehdr/makeinfo
new file mode 100644
index 0000000000..2f8b5e7868
--- /dev/null
+++ b/support/filehdr/makeinfo
@@ -0,0 +1,25 @@
+#!/bin/sh
+# Convert a TeXinfo or LaTeXinfo file to a GNU Emacs info file.
+# The file type is determined automatically.
+# [06-Mar-1996] -- update to remove absolute paths from -load options
+# [04-Oct-1991] -- original version
+for f in $*
+do
+ if grep -s '^\\input texinfo' $f
+ then
+ echo "Processing TeXinfo file: $f"
+ emacs-19.29 -batch -funcall batch-texinfo-format $f
+ elif grep -s '^\\documentstyle.*latexinfo' $f
+ then
+ echo "Processing LaTeXinfo file: $f"
+ emacs-19.29 -batch \
+ -load latexinfomd.el \
+ -load latexinfo.el \
+ -funcall batch-latexinfo-format \
+ $f | egrep -v '^Mark set|^Done'
+ else
+ echo "Don't know what kind of file this is: $f"
+ fi
+done
+
+
diff --git a/support/filehdr/rcs b/support/filehdr/rcs
new file mode 120000
index 0000000000..960f5a0e1c
--- /dev/null
+++ b/support/filehdr/rcs
@@ -0,0 +1 @@
+../../macros/latex/contrib/rcs \ No newline at end of file