diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/filehdr/filehdr.info |
Initial commit
Diffstat (limited to 'support/filehdr/filehdr.info')
-rw-r--r-- | support/filehdr/filehdr.info | 1940 |
1 files changed, 1940 insertions, 0 deletions
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 |