diff options
Diffstat (limited to 'support/filehdr')
-rw-r--r-- | support/filehdr/Makefile | 182 | ||||
-rw-r--r-- | support/filehdr/filehdr.bbl | 31 | ||||
-rw-r--r-- | support/filehdr/filehdr.bib | 89 | ||||
-rw-r--r-- | support/filehdr/filehdr.el | 1733 | ||||
-rw-r--r-- | support/filehdr/filehdr.info | 1940 | ||||
-rw-r--r-- | support/filehdr/filehdr.ltx | 2582 | ||||
-rw-r--r-- | support/filehdr/filehdr.pdf | bin | 0 -> 206397 bytes | |||
-rw-r--r-- | support/filehdr/filehdr.sok | 176 | ||||
-rw-r--r-- | support/filehdr/makeinfo | 25 | ||||
l--------- | support/filehdr/rcs | 1 |
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 Binary files differnew file mode 100644 index 0000000000..47a91a9a99 --- /dev/null +++ b/support/filehdr/filehdr.pdf 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 |