-\input texinfo @c -*-texinfo-*-\r
-@c %**start of header\r
-@setfilename standards.info\r
-@settitle GNU Coding Standards\r
-@c This date is automagically updated when you save this file:\r
-@set lastupdate June 27, 2000\r
-@c %**end of header\r
-\r
-@ifinfo\r
-@format\r
-START-INFO-DIR-ENTRY\r
-* Standards: (standards). GNU coding standards.\r
-END-INFO-DIR-ENTRY\r
-@end format\r
-@end ifinfo\r
-\r
-@c @setchapternewpage odd\r
-@setchapternewpage off\r
-\r
-@c This is used by a cross ref in make-stds.texi\r
-@set CODESTD 1\r
-@iftex\r
-@set CHAPTER chapter\r
-@end iftex\r
-@ifinfo\r
-@set CHAPTER node\r
-@end ifinfo\r
-\r
-@ifinfo\r
-GNU Coding Standards\r
-Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.\r
-\r
-Permission is granted to make and distribute verbatim copies of\r
-this manual provided the copyright notice and this permission notice\r
-are preserved on all copies.\r
-\r
-@ignore\r
-Permission is granted to process this file through TeX and print the\r
-results, provided the printed document carries copying permission\r
-notice identical to this one except for the removal of this paragraph\r
-(this paragraph not being relevant to the printed manual).\r
-@end ignore\r
-\r
-Permission is granted to copy and distribute modified versions of this\r
-manual under the conditions for verbatim copying, provided that the entire\r
-resulting derived work is distributed under the terms of a permission\r
-notice identical to this one.\r
-\r
-Permission is granted to copy and distribute translations of this manual\r
-into another language, under the above conditions for modified versions,\r
-except that this permission notice may be stated in a translation approved\r
-by the Free Software Foundation.\r
-@end ifinfo\r
-\r
-@titlepage\r
-@title GNU Coding Standards\r
-@author Richard Stallman\r
-@author last updated @value{lastupdate}\r
-@page\r
-\r
-@vskip 0pt plus 1filll\r
-Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.\r
-\r
-Permission is granted to make and distribute verbatim copies of\r
-this manual provided the copyright notice and this permission notice\r
-are preserved on all copies.\r
-\r
-Permission is granted to copy and distribute modified versions of this\r
-manual under the conditions for verbatim copying, provided that the entire\r
-resulting derived work is distributed under the terms of a permission\r
-notice identical to this one.\r
-\r
-Permission is granted to copy and distribute translations of this manual\r
-into another language, under the above conditions for modified versions,\r
-except that this permission notice may be stated in a translation approved\r
-by the Free Software Foundation.\r
-@end titlepage\r
-\r
-@ifinfo\r
-@node Top, Preface, (dir), (dir)\r
-@top Version\r
-\r
-Last updated @value{lastupdate}.\r
-@end ifinfo\r
-\r
-@menu\r
-* Preface:: About the GNU Coding Standards\r
-* Legal Issues:: Keeping Free Software Free\r
-* Design Advice:: General Program Design\r
-* Program Behavior:: Program Behavior for All Programs\r
-* Writing C:: Making The Best Use of C\r
-* Documentation:: Documenting Programs\r
-* Managing Releases:: The Release Process\r
-* References:: References to Non-Free Software or Documentation\r
-* Index::\r
-@end menu\r
-\r
-@node Preface\r
-@chapter About the GNU Coding Standards\r
-\r
-The GNU Coding Standards were written by Richard Stallman and other GNU\r
-Project volunteers. Their purpose is to make the GNU system clean,\r
-consistent, and easy to install. This document can also be read as a\r
-guide to writing portable, robust and reliable programs. It focuses on\r
-programs written in C, but many of the rules and principles are useful\r
-even if you write in another programming language. The rules often\r
-state reasons for writing in a certain way.\r
-\r
-Corrections or suggestions for this document should be sent to\r
-@email{gnu@@gnu.org}. If you make a suggestion, please include a\r
-suggested new wording for it; our time is limited. We prefer a context\r
-diff to the @file{standards.texi} or @file{make-stds.texi} files, but if\r
-you don't have those files, please mail your suggestion anyway.\r
-\r
-This release of the GNU Coding Standards was last updated\r
-@value{lastupdate}.\r
-\r
-If you did not obtain this file directly from the GNU project and\r
-recently, please check for a newer version. You can ftp the GNU Coding\r
-Standards from any GNU FTP host in the directory\r
-@file{/pub/gnu/standards/}. The GNU Coding Standards are available\r
-there in several different formats: @file{standards.text},\r
-@file{standards.texi}, @file{standards.info}, and @file{standards.dvi}.\r
-The GNU Coding Standards are also available on the GNU World Wide Web\r
-server: @uref{http://www.gnu.org/prep/standards_toc.html}.\r
-\r
-@node Legal Issues\r
-@chapter Keeping Free Software Free\r
-\r
-This @value{CHAPTER} discusses how you can make sure that GNU software\r
-avoids legal difficulties, and other related issues.\r
-\r
-@menu\r
-* Reading Non-Free Code:: Referring to Proprietary Programs\r
-* Contributions:: Accepting Contributions\r
-* Trademarks:: How We Deal with Trademark Issues\r
-@end menu\r
-\r
-@node Reading Non-Free Code\r
-@section Referring to Proprietary Programs\r
-\r
-Don't in any circumstances refer to Unix source code for or during\r
-your work on GNU! (Or to any other proprietary programs.)\r
-\r
-If you have a vague recollection of the internals of a Unix program,\r
-this does not absolutely mean you can't write an imitation of it, but\r
-do try to organize the imitation internally along different lines,\r
-because this is likely to make the details of the Unix version\r
-irrelevant and dissimilar to your results.\r
-\r
-For example, Unix utilities were generally optimized to minimize\r
-memory use; if you go for speed instead, your program will be very\r
-different. You could keep the entire input file in core and scan it\r
-there instead of using stdio. Use a smarter algorithm discovered more\r
-recently than the Unix program. Eliminate use of temporary files. Do\r
-it in one pass instead of two (we did this in the assembler).\r
-\r
-Or, on the contrary, emphasize simplicity instead of speed. For some\r
-applications, the speed of today's computers makes simpler algorithms\r
-adequate.\r
-\r
-Or go for generality. For example, Unix programs often have static\r
-tables or fixed-size strings, which make for arbitrary limits; use\r
-dynamic allocation instead. Make sure your program handles NULs and\r
-other funny characters in the input files. Add a programming language\r
-for extensibility and write part of the program in that language.\r
-\r
-Or turn some parts of the program into independently usable libraries.\r
-Or use a simple garbage collector instead of tracking precisely when\r
-to free memory, or use a new GNU facility such as obstacks.\r
-\r
-@node Contributions\r
-@section Accepting Contributions\r
-\r
-If the program you are working on is copyrighted by the Free Software\r
-Foundation, then when someone else sends you a piece of code to add to\r
-the program, we need legal papers to use it---just as we asked you to\r
-sign papers initially. @emph{Each} person who makes a nontrivial\r
-contribution to a program must sign some sort of legal papers in order\r
-for us to have clear title to the program; the main author alone is not\r
-enough.\r
-\r
-So, before adding in any contributions from other people, please tell\r
-us, so we can arrange to get the papers. Then wait until we tell you\r
-that we have received the signed papers, before you actually use the\r
-contribution.\r
-\r
-This applies both before you release the program and afterward. If\r
-you receive diffs to fix a bug, and they make significant changes, we\r
-need legal papers for that change.\r
-\r
-This also applies to comments and documentation files. For copyright\r
-law, comments and code are just text. Copyright applies to all kinds of\r
-text, so we need legal papers for all kinds.\r
-\r
-We know it is frustrating to ask for legal papers; it's frustrating for\r
-us as well. But if you don't wait, you are going out on a limb---for\r
-example, what if the contributor's employer won't sign a disclaimer?\r
-You might have to take that code out again!\r
-\r
-You don't need papers for changes of a few lines here or there, since\r
-they are not significant for copyright purposes. Also, you don't need\r
-papers if all you get from the suggestion is some ideas, not actual code\r
-which you use. For example, if someone send you one implementation, but\r
-you write a different implementation of the same idea, you don't need to\r
-get papers.\r
-\r
-The very worst thing is if you forget to tell us about the other\r
-contributor. We could be very embarrassed in court some day as a\r
-result.\r
-\r
-We have more detailed advice for maintainers of programs; if you have\r
-reached the stage of actually maintaining a program for GNU (whether\r
-released or not), please ask us for a copy.\r
-\r
-@node Trademarks\r
-@section Trademarks\r
-\r
-Please do not include any trademark acknowledgements in GNU software\r
-packages or documentation.\r
-\r
-Trademark acknowledgements are the statements that such-and-such is a\r
-trademark of so-and-so. The GNU Project has no objection to the basic\r
-idea of trademarks, but these acknowledgements feel like kowtowing, so\r
-we don't use them. There is no legal requirement for them.\r
-\r
-What is legally required, as regards other people's trademarks, is to\r
-avoid using them in ways which a reader might read as naming or labeling\r
-our own programs or activities. For example, since ``Objective C'' is\r
-(or at least was) a trademark, we made sure to say that we provide a\r
-``compiler for the Objective C language'' rather than an ``Objective C\r
-compiler''. The latter is meant to be short for the former, but it does\r
-not explicitly state the relationship, so it could be misinterpreted as\r
-using ``Objective C'' as a label for the compiler rather than for the\r
-language.\r
-\r
-@node Design Advice\r
-@chapter General Program Design\r
-\r
-This @value{CHAPTER} discusses some of the issues you should take into\r
-account when designing your program.\r
-\r
-@c Standard or ANSI C\r
-@c\r
-@c In 1989 the American National Standards Institute (ANSI) standardized\r
-@c C as standard X3.159-1989. In December of that year the\r
-@c International Standards Organization ISO adopted the ANSI C standard\r
-@c making minor changes. In 1990 ANSI then re-adopted ISO standard\r
-@c C. This version of C is known as either ANSI C or Standard C.\r
-\r
-@menu\r
-* Source Language:: Which languges to use.\r
-* Compatibility:: Compatibility with other implementations\r
-* Using Extensions:: Using non-standard features\r
-* Standard C:: Using Standard (ANSI 1989) C features\r
-@end menu\r
-\r
-@node Source Language\r
-@section Which Languages to Use\r
-\r
-When you want to use a language that gets compiled and runs at high\r
-speed, the best language to use is C. Using another language is like\r
-using a non-standard feature: it will cause trouble for users. Even if\r
-GCC supports the other language, users may find it inconvenient to have\r
-to install the compiler for that other language in order to build your\r
-program. For example, if you write your program in C++, people will\r
-have to install the GNU C++ compiler in order to compile your program.\r
-\r
-C has one other advantage over C++ and other compiled languages: more\r
-people know C, so more people will find it easy to read and modify the\r
-program if it is written in C.\r
-\r
-So in general it is much better to use use C, rather than the\r
-comparable alternatives.\r
-\r
-But there are two exceptions to that conclusion:\r
-\r
-@itemize @bullet\r
-@item\r
-It is no problem to use another language to write a tool specifically\r
-intended for use with that language. That is because the only people\r
-who want to build the tool will be those who have installed the other\r
-language anyway.\r
-\r
-@item\r
-If an application is of interest only to a narrow part of the community,\r
-then the question of which language it is written in has less effect on\r
-other people, so you may as well please yourself.\r
-@end itemize\r
-\r
-Many programs are designed to be extensible: they include an interpreter\r
-for a language that is higher level than C. Often much of the program\r
-is written in that language, too. The Emacs editor pioneered this\r
-technique.\r
-\r
-The standard extensibility interpreter for GNU software is GUILE, which\r
-implements the language Scheme (an especially clean and simple dialect\r
-of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject\r
-programs written in other ``scripting languages'' such as Perl and\r
-Python, but using GUILE is very important for the overall consistency of\r
-the GNU system.\r
-\r
-@node Compatibility\r
-@section Compatibility with Other Implementations\r
-\r
-With occasional exceptions, utility programs and libraries for GNU\r
-should be upward compatible with those in Berkeley Unix, and upward\r
-compatible with 1989 Standard C if 1989 Standard C specifies their\r
-behavior, and upward compatible with @sc{posix} if @sc{posix} specifies\r
-their behavior.\r
-\r
-When these standards conflict, it is useful to offer compatibility\r
-modes for each of them.\r
-\r
-1989 Standard C and @sc{posix} prohibit many kinds of extensions. Feel\r
-free to make the extensions anyway, and include a @samp{--ansi},\r
-@samp{--posix}, or @samp{--compatible} option to turn them off.\r
-However, if the extension has a significant chance of breaking any real\r
-programs or scripts, then it is not really upward compatible. So you\r
-should try to redesign its interface to make it upward compatible.\r
-\r
-Many GNU programs suppress extensions that conflict with @sc{posix} if the\r
-environment variable @code{POSIXLY_CORRECT} is defined (even if it is\r
-defined with a null value). Please make your program recognize this\r
-variable if appropriate.\r
-\r
-When a feature is used only by users (not by programs or command\r
-files), and it is done poorly in Unix, feel free to replace it\r
-completely with something totally different and better. (For example,\r
-@code{vi} is replaced with Emacs.) But it is nice to offer a compatible\r
-feature as well. (There is a free @code{vi} clone, so we offer it.)\r
-\r
-Additional useful features are welcome regardless of whether\r
-there is any precedent for them.\r
-\r
-@node Using Extensions\r
-@section Using Non-standard Features\r
-\r
-Many GNU facilities that already exist support a number of convenient\r
-extensions over the comparable Unix facilities. Whether to use these\r
-extensions in implementing your program is a difficult question.\r
-\r
-On the one hand, using the extensions can make a cleaner program.\r
-On the other hand, people will not be able to build the program\r
-unless the other GNU tools are available. This might cause the\r
-program to work on fewer kinds of machines.\r
-\r
-With some extensions, it might be easy to provide both alternatives.\r
-For example, you can define functions with a ``keyword'' @code{INLINE}\r
-and define that as a macro to expand into either @code{inline} or\r
-nothing, depending on the compiler.\r
-\r
-In general, perhaps it is best not to use the extensions if you can\r
-straightforwardly do without them, but to use the extensions if they\r
-are a big improvement.\r
-\r
-An exception to this rule are the large, established programs (such as\r
-Emacs) which run on a great variety of systems. Using GNU extensions in\r
-such programs would make many users unhappy, so we don't do that.\r
-\r
-Another exception is for programs that are used as part of compilation:\r
-anything that must be compiled with other compilers in order to\r
-bootstrap the GNU compilation facilities. If these require the GNU\r
-compiler, then no one can compile them without having them installed\r
-already. That would be extremely troublesome in certain cases.\r
-\r
-@node Standard C\r
-@section 1989 Standard C and Pre-Standard C\r
-\r
-1989 Standard C is widespread enough now that it is ok to use its\r
-features in new programs. There is one exception: do not ever use the\r
-``trigraph'' feature of 1989 Standard C.\r
-\r
-However, it is easy to support pre-standard compilers in most programs,\r
-so if you know how to do that, feel free. If a program you are\r
-maintaining has such support, you should try to keep it working.\r
-\r
-To support pre-standard C, instead of writing function definitions in\r
-standard prototype form,\r
-\r
-@example\r
-int\r
-foo (int x, int y)\r
-@dots{}\r
-@end example\r
-\r
-@noindent\r
-write the definition in pre-standard style like this,\r
-\r
-@example\r
-int\r
-foo (x, y)\r
- int x, y;\r
-@dots{}\r
-@end example\r
-\r
-@noindent\r
-and use a separate declaration to specify the argument prototype:\r
-\r
-@example\r
-int foo (int, int);\r
-@end example\r
-\r
-You need such a declaration anyway, in a header file, to get the benefit\r
-of prototypes in all the files where the function is called. And once\r
-you have the declaration, you normally lose nothing by writing the\r
-function definition in the pre-standard style.\r
-\r
-This technique does not work for integer types narrower than @code{int}.\r
-If you think of an argument as being of a type narrower than @code{int},\r
-declare it as @code{int} instead.\r
-\r
-There are a few special cases where this technique is hard to use. For\r
-example, if a function argument needs to hold the system type\r
-@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than\r
-@code{int} on some machines; but you cannot use @code{int} instead,\r
-because @code{dev_t} is wider than @code{int} on some machines. There\r
-is no type you can safely use on all machines in a non-standard\r
-definition. The only way to support non-standard C and pass such an\r
-argument is to check the width of @code{dev_t} using Autoconf and choose\r
-the argument type accordingly. This may not be worth the trouble.\r
-\r
-In order to support pre-standard compilers that do not recognize\r
-prototypes, you may want to use a preprocessor macro like this:\r
-\r
-@example\r
-/* Declare the prototype for a general external function. */\r
-#if defined (__STDC__) || defined (WINDOWSNT)\r
-#define P_(proto) proto\r
-#else\r
-#define P_(proto) ()\r
-#endif\r
-@end example\r
-\r
-@node Program Behavior\r
-@chapter Program Behavior for All Programs\r
-\r
-This @value{CHAPTER} describes conventions for writing robust\r
-software. It also describes general standards for error messages, the\r
-command line interface, and how libraries should behave.\r
-\r
-@menu\r
-* Semantics:: Writing robust programs\r
-* Libraries:: Library behavior\r
-* Errors:: Formatting error messages\r
-* User Interfaces:: Standards about interfaces generally\r
-* Graphical Interfaces:: Standards for graphical interfaces\r
-* Command-Line Interfaces:: Standards for command line interfaces\r
-* Option Table:: Table of long options.\r
-* Memory Usage:: When and how to care about memory needs\r
-@end menu\r
-\r
-@node Semantics\r
-@section Writing Robust Programs\r
-\r
-Avoid arbitrary limits on the length or number of @emph{any} data\r
-structure, including file names, lines, files, and symbols, by allocating\r
-all data structures dynamically. In most Unix utilities, ``long lines\r
-are silently truncated''. This is not acceptable in a GNU utility.\r
-\r
-Utilities reading files should not drop NUL characters, or any other\r
-nonprinting characters @emph{including those with codes above 0177}.\r
-The only sensible exceptions would be utilities specifically intended\r
-for interface to certain types of terminals or printers\r
-that can't handle those characters.\r
-Whenever possible, try to make programs work properly with\r
-sequences of bytes that represent multibyte characters, using encodings\r
-such as UTF-8 and others.\r
-\r
-Check every system call for an error return, unless you know you wish to\r
-ignore errors. Include the system error text (from @code{perror} or\r
-equivalent) in @emph{every} error message resulting from a failing\r
-system call, as well as the name of the file if any and the name of the\r
-utility. Just ``cannot open foo.c'' or ``stat failed'' is not\r
-sufficient.\r
-\r
-Check every call to @code{malloc} or @code{realloc} to see if it\r
-returned zero. Check @code{realloc} even if you are making the block\r
-smaller; in a system that rounds block sizes to a power of 2,\r
-@code{realloc} may get a different block if you ask for less space.\r
-\r
-In Unix, @code{realloc} can destroy the storage block if it returns\r
-zero. GNU @code{realloc} does not have this bug: if it fails, the\r
-original block is unchanged. Feel free to assume the bug is fixed. If\r
-you wish to run your program on Unix, and wish to avoid lossage in this\r
-case, you can use the GNU @code{malloc}.\r
-\r
-You must expect @code{free} to alter the contents of the block that was\r
-freed. Anything you want to fetch from the block, you must fetch before\r
-calling @code{free}.\r
-\r
-If @code{malloc} fails in a noninteractive program, make that a fatal\r
-error. In an interactive program (one that reads commands from the\r
-user), it is better to abort the command and return to the command\r
-reader loop. This allows the user to kill other processes to free up\r
-virtual memory, and then try the command again.\r
-\r
-Use @code{getopt_long} to decode arguments, unless the argument syntax\r
-makes this unreasonable.\r
-\r
-When static storage is to be written in during program execution, use\r
-explicit C code to initialize it. Reserve C initialized declarations\r
-for data that will not be changed.\r
-@c ADR: why?\r
-\r
-Try to avoid low-level interfaces to obscure Unix data structures (such\r
-as file directories, utmp, or the layout of kernel memory), since these\r
-are less likely to work compatibly. If you need to find all the files\r
-in a directory, use @code{readdir} or some other high-level interface.\r
-These are supported compatibly by GNU.\r
-\r
-The preferred signal handling facilities are the BSD variant of\r
-@code{signal}, and the @sc{posix} @code{sigaction} function; the\r
-alternative USG @code{signal} interface is an inferior design.\r
-\r
-Nowadays, using the @sc{posix} signal functions may be the easiest way\r
-to make a program portable. If you use @code{signal}, then on GNU/Linux\r
-systems running GNU libc version 1, you should include\r
-@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD\r
-behavior. It is up to you whether to support systems where\r
-@code{signal} has only the USG behavior, or give up on them.\r
-\r
-In error checks that detect ``impossible'' conditions, just abort.\r
-There is usually no point in printing any message. These checks\r
-indicate the existence of bugs. Whoever wants to fix the bugs will have\r
-to read the source code and run a debugger. So explain the problem with\r
-comments in the source. The relevant data will be in variables, which\r
-are easy to examine with the debugger, so there is no point moving them\r
-elsewhere.\r
-\r
-Do not use a count of errors as the exit status for a program.\r
-@emph{That does not work}, because exit status values are limited to 8\r
-bits (0 through 255). A single run of the program might have 256\r
-errors; if you try to return 256 as the exit status, the parent process\r
-will see 0 as the status, and it will appear that the program succeeded.\r
-\r
-If you make temporary files, check the @code{TMPDIR} environment\r
-variable; if that variable is defined, use the specified directory\r
-instead of @file{/tmp}.\r
-\r
-In addition, be aware that there is a possible security problem when\r
-creating temporary files in world-writable directories. In C, you can\r
-avoid this problem by creating temporary files in this manner:\r
-\r
-@example\r
-fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);\r
-@end example\r
-\r
-@noindent\r
-or by using the @code{mkstemps} function from libiberty.\r
-\r
-In bash, use @code{set -C} to avoid this problem.\r
-\r
-@node Libraries\r
-@section Library Behavior\r
-\r
-Try to make library functions reentrant. If they need to do dynamic\r
-storage allocation, at least try to avoid any nonreentrancy aside from\r
-that of @code{malloc} itself.\r
-\r
-Here are certain name conventions for libraries, to avoid name\r
-conflicts.\r
-\r
-Choose a name prefix for the library, more than two characters long.\r
-All external function and variable names should start with this\r
-prefix. In addition, there should only be one of these in any given\r
-library member. This usually means putting each one in a separate\r
-source file.\r
-\r
-An exception can be made when two external symbols are always used\r
-together, so that no reasonable program could use one without the\r
-other; then they can both go in the same file.\r
-\r
-External symbols that are not documented entry points for the user\r
-should have names beginning with @samp{_}. They should also contain\r
-the chosen name prefix for the library, to prevent collisions with\r
-other libraries. These can go in the same files with user entry\r
-points if you like.\r
-\r
-Static functions and variables can be used as you like and need not\r
-fit any naming convention.\r
-\r
-@node Errors\r
-@section Formatting Error Messages\r
-\r
-Error messages from compilers should look like this:\r
-\r
-@example\r
-@var{source-file-name}:@var{lineno}: @var{message}\r
-@end example\r
-\r
-@noindent\r
-If you want to mention the column number, use this format:\r
-\r
-@example\r
-@var{source-file-name}:@var{lineno}:@var{column}: @var{message}\r
-@end example\r
-\r
-@noindent\r
-Line numbers should start from 1 at the beginning of the file, and\r
-column numbers should start from 1 at the beginning of the line. (Both\r
-of these conventions are chosen for compatibility.) Calculate column\r
-numbers assuming that space and all ASCII printing characters have\r
-equal width, and assuming tab stops every 8 columns.\r
-\r
-Error messages from other noninteractive programs should look like this:\r
-\r
-@example\r
-@var{program}:@var{source-file-name}:@var{lineno}: @var{message}\r
-@end example\r
-\r
-@noindent\r
-when there is an appropriate source file, or like this:\r
-\r
-@example\r
-@var{program}: @var{message}\r
-@end example\r
-\r
-@noindent\r
-when there is no relevant source file.\r
-\r
-If you want to mention the column number, use this format:\r
-\r
-@example\r
-@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}\r
-@end example\r
-\r
-In an interactive program (one that is reading commands from a\r
-terminal), it is better not to include the program name in an error\r
-message. The place to indicate which program is running is in the\r
-prompt or with the screen layout. (When the same program runs with\r
-input from a source other than a terminal, it is not interactive and\r
-would do best to print error messages using the noninteractive style.)\r
-\r
-The string @var{message} should not begin with a capital letter when\r
-it follows a program name and/or file name. Also, it should not end\r
-with a period.\r
-\r
-Error messages from interactive programs, and other messages such as\r
-usage messages, should start with a capital letter. But they should not\r
-end with a period.\r
-\r
-@node User Interfaces\r
-@section Standards for Interfaces Generally\r
-\r
-Please don't make the behavior of a utility depend on the name used\r
-to invoke it. It is useful sometimes to make a link to a utility\r
-with a different name, and that should not change what it does.\r
-\r
-Instead, use a run time option or a compilation switch or both\r
-to select among the alternate behaviors.\r
-\r
-Likewise, please don't make the behavior of the program depend on the\r
-type of output device it is used with. Device independence is an\r
-important principle of the system's design; do not compromise it merely\r
-to save someone from typing an option now and then. (Variation in error\r
-message syntax when using a terminal is ok, because that is a side issue\r
-that people do not depend on.)\r
-\r
-If you think one behavior is most useful when the output is to a\r
-terminal, and another is most useful when the output is a file or a\r
-pipe, then it is usually best to make the default behavior the one that\r
-is useful with output to a terminal, and have an option for the other\r
-behavior.\r
-\r
-Compatibility requires certain programs to depend on the type of output\r
-device. It would be disastrous if @code{ls} or @code{sh} did not do so\r
-in the way all users expect. In some of these cases, we supplement the\r
-program with a preferred alternate version that does not depend on the\r
-output device type. For example, we provide a @code{dir} program much\r
-like @code{ls} except that its default output format is always\r
-multi-column format.\r
-\r
-@node Graphical Interfaces\r
-@section Standards for Graphical Interfaces\r
-\r
-When you write a program that provides a graphical user interface,\r
-please make it work with X Windows and the GTK toolkit unless the\r
-functionality specifically requires some alternative (for example,\r
-``displaying jpeg images while in console mode'').\r
-\r
-In addition, please provide a command-line interface to control the\r
-functionality. (In many cases, the graphical user interface can be a\r
-separate program which invokes the command-line program.) This is\r
-so that the same jobs can be done from scripts.\r
-\r
-Please also consider providing a CORBA interface (for use from GNOME), a\r
-library interface (for use from C), and perhaps a keyboard-driven\r
-console interface (for use by users from console mode). Once you are\r
-doing the work to provide the functionality and the graphical interface,\r
-these won't be much extra work.\r
-\r
-@node Command-Line Interfaces\r
-@section Standards for Command Line Interfaces\r
-\r
-It is a good idea to follow the @sc{posix} guidelines for the\r
-command-line options of a program. The easiest way to do this is to use\r
-@code{getopt} to parse them. Note that the GNU version of @code{getopt}\r
-will normally permit options anywhere among the arguments unless the\r
-special argument @samp{--} is used. This is not what @sc{posix}\r
-specifies; it is a GNU extension.\r
-\r
-Please define long-named options that are equivalent to the\r
-single-letter Unix-style options. We hope to make GNU more user\r
-friendly this way. This is easy to do with the GNU function\r
-@code{getopt_long}.\r
-\r
-One of the advantages of long-named options is that they can be\r
-consistent from program to program. For example, users should be able\r
-to expect the ``verbose'' option of any GNU program which has one, to be\r
-spelled precisely @samp{--verbose}. To achieve this uniformity, look at\r
-the table of common long-option names when you choose the option names\r
-for your program (@pxref{Option Table}).\r
-\r
-It is usually a good idea for file names given as ordinary arguments to\r
-be input files only; any output files would be specified using options\r
-(preferably @samp{-o} or @samp{--output}). Even if you allow an output\r
-file name as an ordinary argument for compatibility, try to provide an\r
-option as another way to specify it. This will lead to more consistency\r
-among GNU utilities, and fewer idiosyncracies for users to remember.\r
-\r
-All programs should support two standard options: @samp{--version}\r
-and @samp{--help}.\r
-\r
-@table @code\r
-@item --version\r
-This option should direct the program to print information about its name,\r
-version, origin and legal status, all on standard output, and then exit\r
-successfully. Other options and arguments should be ignored once this\r
-is seen, and the program should not perform its normal function.\r
-\r
-The first line is meant to be easy for a program to parse; the version\r
-number proper starts after the last space. In addition, it contains\r
-the canonical name for this program, in this format:\r
-\r
-@example\r
-GNU Emacs 19.30\r
-@end example\r
-\r
-@noindent\r
-The program's name should be a constant string; @emph{don't} compute it\r
-from @code{argv[0]}. The idea is to state the standard or canonical\r
-name for the program, not its file name. There are other ways to find\r
-out the precise file name where a command is found in @code{PATH}.\r
-\r
-If the program is a subsidiary part of a larger package, mention the\r
-package name in parentheses, like this:\r
-\r
-@example\r
-emacsserver (GNU Emacs) 19.30\r
-@end example\r
-\r
-@noindent\r
-If the package has a version number which is different from this\r
-program's version number, you can mention the package version number\r
-just before the close-parenthesis.\r
-\r
-If you @strong{need} to mention the version numbers of libraries which\r
-are distributed separately from the package which contains this program,\r
-you can do so by printing an additional line of version info for each\r
-library you want to mention. Use the same format for these lines as for\r
-the first line.\r
-\r
-Please do not mention all of the libraries that the program uses ``just\r
-for completeness''---that would produce a lot of unhelpful clutter.\r
-Please mention library version numbers only if you find in practice that\r
-they are very important to you in debugging.\r
-\r
-The following line, after the version number line or lines, should be a\r
-copyright notice. If more than one copyright notice is called for, put\r
-each on a separate line.\r
-\r
-Next should follow a brief statement that the program is free software,\r
-and that users are free to copy and change it on certain conditions. If\r
-the program is covered by the GNU GPL, say so here. Also mention that\r
-there is no warranty, to the extent permitted by law.\r
-\r
-It is ok to finish the output with a list of the major authors of the\r
-program, as a way of giving credit.\r
-\r
-Here's an example of output that follows these rules:\r
-\r
-@smallexample\r
-GNU Emacs 19.34.5\r
-Copyright (C) 1996 Free Software Foundation, Inc.\r
-GNU Emacs comes with NO WARRANTY,\r
-to the extent permitted by law.\r
-You may redistribute copies of GNU Emacs\r
-under the terms of the GNU General Public License.\r
-For more information about these matters,\r
-see the files named COPYING.\r
-@end smallexample\r
-\r
-You should adapt this to your program, of course, filling in the proper\r
-year, copyright holder, name of program, and the references to\r
-distribution terms, and changing the rest of the wording as necessary.\r
-\r
-This copyright notice only needs to mention the most recent year in\r
-which changes were made---there's no need to list the years for previous\r
-versions' changes. You don't have to mention the name of the program in\r
-these notices, if that is inconvenient, since it appeared in the first\r
-line.\r
-\r
-@item --help\r
-This option should output brief documentation for how to invoke the\r
-program, on standard output, then exit successfully. Other options and\r
-arguments should be ignored once this is seen, and the program should\r
-not perform its normal function.\r
-\r
-Near the end of the @samp{--help} option's output there should be a line\r
-that says where to mail bug reports. It should have this format:\r
-\r
-@example\r
-Report bugs to @var{mailing-address}.\r
-@end example\r
-@end table\r
-\r
-@node Option Table\r
-@section Table of Long Options\r
-\r
-Here is a table of long options used by GNU programs. It is surely\r
-incomplete, but we aim to list all the options that a new program might\r
-want to be compatible with. If you use names not already in the table,\r
-please send @email{gnu@@gnu.org} a list of them, with their\r
-meanings, so we can update the table.\r
-\r
-@c Please leave newlines between items in this table; it's much easier\r
-@c to update when it isn't completely squashed together and unreadable.\r
-@c When there is more than one short option for a long option name, put\r
-@c a semicolon between the lists of the programs that use them, not a\r
-@c period. --friedman\r
-\r
-@table @samp\r
-@item after-date\r
-@samp{-N} in @code{tar}.\r
-\r
-@item all\r
-@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},\r
-and @code{unexpand}.\r
-\r
-@item all-text\r
-@samp{-a} in @code{diff}.\r
-\r
-@item almost-all\r
-@samp{-A} in @code{ls}.\r
-\r
-@item append\r
-@samp{-a} in @code{etags}, @code{tee}, @code{time};\r
-@samp{-r} in @code{tar}.\r
-\r
-@item archive\r
-@samp{-a} in @code{cp}.\r
-\r
-@item archive-name\r
-@samp{-n} in @code{shar}.\r
-\r
-@item arglength\r
-@samp{-l} in @code{m4}.\r
-\r
-@item ascii\r
-@samp{-a} in @code{diff}.\r
-\r
-@item assign\r
-@samp{-v} in @code{gawk}.\r
-\r
-@item assume-new\r
-@samp{-W} in Make.\r
-\r
-@item assume-old\r
-@samp{-o} in Make.\r
-\r
-@item auto-check\r
-@samp{-a} in @code{recode}.\r
-\r
-@item auto-pager\r
-@samp{-a} in @code{wdiff}.\r
-\r
-@item auto-reference\r
-@samp{-A} in @code{ptx}.\r
-\r
-@item avoid-wraps\r
-@samp{-n} in @code{wdiff}.\r
-\r
-@item background\r
-For server programs, run in the background.\r
-\r
-@item backward-search\r
-@samp{-B} in @code{ctags}.\r
-\r
-@item basename\r
-@samp{-f} in @code{shar}.\r
-\r
-@item batch\r
-Used in GDB.\r
-\r
-@item baud\r
-Used in GDB.\r
-\r
-@item before\r
-@samp{-b} in @code{tac}.\r
-\r
-@item binary\r
-@samp{-b} in @code{cpio} and @code{diff}.\r
-\r
-@item bits-per-code\r
-@samp{-b} in @code{shar}.\r
-\r
-@item block-size\r
-Used in @code{cpio} and @code{tar}.\r
-\r
-@item blocks\r
-@samp{-b} in @code{head} and @code{tail}.\r
-\r
-@item break-file\r
-@samp{-b} in @code{ptx}.\r
-\r
-@item brief\r
-Used in various programs to make output shorter.\r
-\r
-@item bytes\r
-@samp{-c} in @code{head}, @code{split}, and @code{tail}.\r
-\r
-@item c@t{++}\r
-@samp{-C} in @code{etags}.\r
-\r
-@item catenate\r
-@samp{-A} in @code{tar}.\r
-\r
-@item cd\r
-Used in various programs to specify the directory to use.\r
-\r
-@item changes\r
-@samp{-c} in @code{chgrp} and @code{chown}.\r
-\r
-@item classify\r
-@samp{-F} in @code{ls}.\r
-\r
-@item colons\r
-@samp{-c} in @code{recode}.\r
-\r
-@item command\r
-@samp{-c} in @code{su};\r
-@samp{-x} in GDB.\r
-\r
-@item compare\r
-@samp{-d} in @code{tar}.\r
-\r
-@item compat\r
-Used in @code{gawk}.\r
-\r
-@item compress\r
-@samp{-Z} in @code{tar} and @code{shar}.\r
-\r
-@item concatenate\r
-@samp{-A} in @code{tar}.\r
-\r
-@item confirmation\r
-@samp{-w} in @code{tar}.\r
-\r
-@item context\r
-Used in @code{diff}.\r
-\r
-@item copyleft\r
-@samp{-W copyleft} in @code{gawk}.\r
-\r
-@item copyright\r
-@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};\r
-@samp{-W copyright} in @code{gawk}.\r
-\r
-@item core\r
-Used in GDB.\r
-\r
-@item count\r
-@samp{-q} in @code{who}.\r
-\r
-@item count-links\r
-@samp{-l} in @code{du}.\r
-\r
-@item create\r
-Used in @code{tar} and @code{cpio}.\r
-\r
-@item cut-mark\r
-@samp{-c} in @code{shar}.\r
-\r
-@item cxref\r
-@samp{-x} in @code{ctags}.\r
-\r
-@item date\r
-@samp{-d} in @code{touch}.\r
-\r
-@item debug\r
-@samp{-d} in Make and @code{m4};\r
-@samp{-t} in Bison.\r
-\r
-@item define\r
-@samp{-D} in @code{m4}.\r
-\r
-@item defines\r
-@samp{-d} in Bison and @code{ctags}.\r
-\r
-@item delete\r
-@samp{-D} in @code{tar}.\r
-\r
-@item dereference\r
-@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},\r
-@code{ls}, and @code{tar}.\r
-\r
-@item dereference-args\r
-@samp{-D} in @code{du}.\r
-\r
-@item device\r
-Specify an I/O device (special file name).\r
-\r
-@item diacritics\r
-@samp{-d} in @code{recode}.\r
-\r
-@item dictionary-order\r
-@samp{-d} in @code{look}.\r
-\r
-@item diff\r
-@samp{-d} in @code{tar}.\r
-\r
-@item digits\r
-@samp{-n} in @code{csplit}.\r
-\r
-@item directory\r
-Specify the directory to use, in various programs. In @code{ls}, it\r
-means to show directories themselves rather than their contents. In\r
-@code{rm} and @code{ln}, it means to not treat links to directories\r
-specially.\r
-\r
-@item discard-all\r
-@samp{-x} in @code{strip}.\r
-\r
-@item discard-locals\r
-@samp{-X} in @code{strip}.\r
-\r
-@item dry-run\r
-@samp{-n} in Make.\r
-\r
-@item ed\r
-@samp{-e} in @code{diff}.\r
-\r
-@item elide-empty-files\r
-@samp{-z} in @code{csplit}.\r
-\r
-@item end-delete\r
-@samp{-x} in @code{wdiff}.\r
-\r
-@item end-insert\r
-@samp{-z} in @code{wdiff}.\r
-\r
-@item entire-new-file\r
-@samp{-N} in @code{diff}.\r
-\r
-@item environment-overrides\r
-@samp{-e} in Make.\r
-\r
-@item eof\r
-@samp{-e} in @code{xargs}.\r
-\r
-@item epoch\r
-Used in GDB.\r
-\r
-@item error-limit\r
-Used in @code{makeinfo}.\r
-\r
-@item error-output\r
-@samp{-o} in @code{m4}.\r
-\r
-@item escape\r
-@samp{-b} in @code{ls}.\r
-\r
-@item exclude-from\r
-@samp{-X} in @code{tar}.\r
-\r
-@item exec\r
-Used in GDB.\r
-\r
-@item exit\r
-@samp{-x} in @code{xargs}.\r
-\r
-@item exit-0\r
-@samp{-e} in @code{unshar}.\r
-\r
-@item expand-tabs\r
-@samp{-t} in @code{diff}.\r
-\r
-@item expression\r
-@samp{-e} in @code{sed}.\r
-\r
-@item extern-only\r
-@samp{-g} in @code{nm}.\r
-\r
-@item extract\r
-@samp{-i} in @code{cpio};\r
-@samp{-x} in @code{tar}.\r
-\r
-@item faces\r
-@samp{-f} in @code{finger}.\r
-\r
-@item fast\r
-@samp{-f} in @code{su}.\r
-\r
-@item fatal-warnings\r
-@samp{-E} in @code{m4}.\r
-\r
-@item file\r
-@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};\r
-@samp{-n} in @code{sed};\r
-@samp{-r} in @code{touch}.\r
-\r
-@item field-separator\r
-@samp{-F} in @code{gawk}.\r
-\r
-@item file-prefix\r
-@samp{-b} in Bison.\r
-\r
-@item file-type\r
-@samp{-F} in @code{ls}.\r
-\r
-@item files-from\r
-@samp{-T} in @code{tar}.\r
-\r
-@item fill-column\r
-Used in @code{makeinfo}.\r
-\r
-@item flag-truncation\r
-@samp{-F} in @code{ptx}.\r
-\r
-@item fixed-output-files\r
-@samp{-y} in Bison.\r
-\r
-@item follow\r
-@samp{-f} in @code{tail}.\r
-\r
-@item footnote-style\r
-Used in @code{makeinfo}.\r
-\r
-@item force\r
-@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.\r
-\r
-@item force-prefix\r
-@samp{-F} in @code{shar}.\r
-\r
-@item foreground\r
-For server programs, run in the foreground;\r
-in other words, don't do anything special to run the server\r
-in the background.\r
-\r
-@item format\r
-Used in @code{ls}, @code{time}, and @code{ptx}.\r
-\r
-@item freeze-state\r
-@samp{-F} in @code{m4}.\r
-\r
-@item fullname\r
-Used in GDB.\r
-\r
-@item gap-size\r
-@samp{-g} in @code{ptx}.\r
-\r
-@item get\r
-@samp{-x} in @code{tar}.\r
-\r
-@item graphic\r
-@samp{-i} in @code{ul}.\r
-\r
-@item graphics\r
-@samp{-g} in @code{recode}.\r
-\r
-@item group\r
-@samp{-g} in @code{install}.\r
-\r
-@item gzip\r
-@samp{-z} in @code{tar} and @code{shar}.\r
-\r
-@item hashsize\r
-@samp{-H} in @code{m4}.\r
-\r
-@item header\r
-@samp{-h} in @code{objdump} and @code{recode}\r
-\r
-@item heading\r
-@samp{-H} in @code{who}.\r
-\r
-@item help\r
-Used to ask for brief usage information.\r
-\r
-@item here-delimiter\r
-@samp{-d} in @code{shar}.\r
-\r
-@item hide-control-chars\r
-@samp{-q} in @code{ls}.\r
-\r
-@item html\r
-In @code{makeinfo}, output HTML. \r
-\r
-@item idle\r
-@samp{-u} in @code{who}.\r
-\r
-@item ifdef\r
-@samp{-D} in @code{diff}.\r
-\r
-@item ignore\r
-@samp{-I} in @code{ls};\r
-@samp{-x} in @code{recode}.\r
-\r
-@item ignore-all-space\r
-@samp{-w} in @code{diff}.\r
-\r
-@item ignore-backups\r
-@samp{-B} in @code{ls}.\r
-\r
-@item ignore-blank-lines\r
-@samp{-B} in @code{diff}.\r
-\r
-@item ignore-case\r
-@samp{-f} in @code{look} and @code{ptx};\r
-@samp{-i} in @code{diff} and @code{wdiff}.\r
-\r
-@item ignore-errors\r
-@samp{-i} in Make.\r
-\r
-@item ignore-file\r
-@samp{-i} in @code{ptx}.\r
-\r
-@item ignore-indentation\r
-@samp{-I} in @code{etags}.\r
-\r
-@item ignore-init-file\r
-@samp{-f} in Oleo.\r
-\r
-@item ignore-interrupts\r
-@samp{-i} in @code{tee}.\r
-\r
-@item ignore-matching-lines\r
-@samp{-I} in @code{diff}.\r
-\r
-@item ignore-space-change\r
-@samp{-b} in @code{diff}.\r
-\r
-@item ignore-zeros\r
-@samp{-i} in @code{tar}.\r
-\r
-@item include\r
-@samp{-i} in @code{etags};\r
-@samp{-I} in @code{m4}.\r
-\r
-@item include-dir\r
-@samp{-I} in Make.\r
-\r
-@item incremental\r
-@samp{-G} in @code{tar}.\r
-\r
-@item info\r
-@samp{-i}, @samp{-l}, and @samp{-m} in Finger.\r
-\r
-@item init-file\r
-In some programs, specify the name of the file to read as the user's\r
-init file.\r
-\r
-@item initial\r
-@samp{-i} in @code{expand}.\r
-\r
-@item initial-tab\r
-@samp{-T} in @code{diff}.\r
-\r
-@item inode\r
-@samp{-i} in @code{ls}.\r
-\r
-@item interactive\r
-@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};\r
-@samp{-e} in @code{m4};\r
-@samp{-p} in @code{xargs};\r
-@samp{-w} in @code{tar}.\r
-\r
-@item intermix-type\r
-@samp{-p} in @code{shar}.\r
-\r
-@item iso-8601\r
-Used in @code{date}\r
-\r
-@item jobs\r
-@samp{-j} in Make.\r
-\r
-@item just-print\r
-@samp{-n} in Make.\r
-\r
-@item keep-going\r
-@samp{-k} in Make.\r
-\r
-@item keep-files\r
-@samp{-k} in @code{csplit}.\r
-\r
-@item kilobytes\r
-@samp{-k} in @code{du} and @code{ls}.\r
-\r
-@item language\r
-@samp{-l} in @code{etags}.\r
-\r
-@item less-mode\r
-@samp{-l} in @code{wdiff}.\r
-\r
-@item level-for-gzip\r
-@samp{-g} in @code{shar}.\r
-\r
-@item line-bytes\r
-@samp{-C} in @code{split}.\r
-\r
-@item lines\r
-Used in @code{split}, @code{head}, and @code{tail}.\r
-\r
-@item link\r
-@samp{-l} in @code{cpio}.\r
-\r
-@item lint\r
-@itemx lint-old\r
-Used in @code{gawk}.\r
-\r
-@item list\r
-@samp{-t} in @code{cpio};\r
-@samp{-l} in @code{recode}.\r
-\r
-@item list\r
-@samp{-t} in @code{tar}.\r
-\r
-@item literal\r
-@samp{-N} in @code{ls}.\r
-\r
-@item load-average\r
-@samp{-l} in Make.\r
-\r
-@item login\r
-Used in @code{su}.\r
-\r
-@item machine\r
-No listing of which programs already use this;\r
-someone should check to\r
-see if any actually do, and tell @email{gnu@@gnu.org}.\r
-\r
-@item macro-name\r
-@samp{-M} in @code{ptx}.\r
-\r
-@item mail\r
-@samp{-m} in @code{hello} and @code{uname}.\r
-\r
-@item make-directories\r
-@samp{-d} in @code{cpio}.\r
-\r
-@item makefile\r
-@samp{-f} in Make.\r
-\r
-@item mapped\r
-Used in GDB.\r
-\r
-@item max-args\r
-@samp{-n} in @code{xargs}.\r
-\r
-@item max-chars\r
-@samp{-n} in @code{xargs}.\r
-\r
-@item max-lines\r
-@samp{-l} in @code{xargs}.\r
-\r
-@item max-load\r
-@samp{-l} in Make.\r
-\r
-@item max-procs\r
-@samp{-P} in @code{xargs}.\r
-\r
-@item mesg\r
-@samp{-T} in @code{who}.\r
-\r
-@item message\r
-@samp{-T} in @code{who}.\r
-\r
-@item minimal\r
-@samp{-d} in @code{diff}.\r
-\r
-@item mixed-uuencode\r
-@samp{-M} in @code{shar}.\r
-\r
-@item mode\r
-@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.\r
-\r
-@item modification-time\r
-@samp{-m} in @code{tar}.\r
-\r
-@item multi-volume\r
-@samp{-M} in @code{tar}.\r
-\r
-@item name-prefix\r
-@samp{-a} in Bison.\r
-\r
-@item nesting-limit\r
-@samp{-L} in @code{m4}.\r
-\r
-@item net-headers\r
-@samp{-a} in @code{shar}.\r
-\r
-@item new-file\r
-@samp{-W} in Make.\r
-\r
-@item no-builtin-rules\r
-@samp{-r} in Make.\r
-\r
-@item no-character-count\r
-@samp{-w} in @code{shar}.\r
-\r
-@item no-check-existing\r
-@samp{-x} in @code{shar}.\r
-\r
-@item no-common\r
-@samp{-3} in @code{wdiff}.\r
-\r
-@item no-create\r
-@samp{-c} in @code{touch}.\r
-\r
-@item no-defines\r
-@samp{-D} in @code{etags}.\r
-\r
-@item no-deleted\r
-@samp{-1} in @code{wdiff}.\r
-\r
-@item no-dereference\r
-@samp{-d} in @code{cp}.\r
-\r
-@item no-inserted\r
-@samp{-2} in @code{wdiff}.\r
-\r
-@item no-keep-going\r
-@samp{-S} in Make.\r
-\r
-@item no-lines\r
-@samp{-l} in Bison.\r
-\r
-@item no-piping\r
-@samp{-P} in @code{shar}.\r
-\r
-@item no-prof\r
-@samp{-e} in @code{gprof}.\r
-\r
-@item no-regex\r
-@samp{-R} in @code{etags}.\r
-\r
-@item no-sort\r
-@samp{-p} in @code{nm}.\r
-\r
-@item no-split\r
-Used in @code{makeinfo}.\r
-\r
-@item no-static\r
-@samp{-a} in @code{gprof}.\r
-\r
-@item no-time\r
-@samp{-E} in @code{gprof}.\r
-\r
-@item no-timestamp\r
-@samp{-m} in @code{shar}.\r
-\r
-@item no-validate\r
-Used in @code{makeinfo}.\r
-\r
-@item no-wait\r
-Used in @code{emacsclient}.\r
-\r
-@item no-warn\r
-Used in various programs to inhibit warnings.\r
-\r
-@item node\r
-@samp{-n} in @code{info}.\r
-\r
-@item nodename\r
-@samp{-n} in @code{uname}.\r
-\r
-@item nonmatching\r
-@samp{-f} in @code{cpio}.\r
-\r
-@item nstuff\r
-@samp{-n} in @code{objdump}.\r
-\r
-@item null\r
-@samp{-0} in @code{xargs}.\r
-\r
-@item number\r
-@samp{-n} in @code{cat}.\r
-\r
-@item number-nonblank\r
-@samp{-b} in @code{cat}.\r
-\r
-@item numeric-sort\r
-@samp{-n} in @code{nm}.\r
-\r
-@item numeric-uid-gid\r
-@samp{-n} in @code{cpio} and @code{ls}.\r
-\r
-@item nx\r
-Used in GDB.\r
-\r
-@item old-archive\r
-@samp{-o} in @code{tar}.\r
-\r
-@item old-file\r
-@samp{-o} in Make.\r
-\r
-@item one-file-system\r
-@samp{-l} in @code{tar}, @code{cp}, and @code{du}.\r
-\r
-@item only-file\r
-@samp{-o} in @code{ptx}.\r
-\r
-@item only-prof\r
-@samp{-f} in @code{gprof}.\r
-\r
-@item only-time\r
-@samp{-F} in @code{gprof}.\r
-\r
-@item options\r
-@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},\r
-@code{fdmountd}, and @code{fdumount}.\r
-\r
-@item output\r
-In various programs, specify the output file name.\r
-\r
-@item output-prefix\r
-@samp{-o} in @code{shar}.\r
-\r
-@item override\r
-@samp{-o} in @code{rm}.\r
-\r
-@item overwrite\r
-@samp{-c} in @code{unshar}.\r
-\r
-@item owner\r
-@samp{-o} in @code{install}.\r
-\r
-@item paginate\r
-@samp{-l} in @code{diff}.\r
-\r
-@item paragraph-indent\r
-Used in @code{makeinfo}.\r
-\r
-@item parents\r
-@samp{-p} in @code{mkdir} and @code{rmdir}.\r
-\r
-@item pass-all\r
-@samp{-p} in @code{ul}.\r
-\r
-@item pass-through\r
-@samp{-p} in @code{cpio}.\r
-\r
-@item port\r
-@samp{-P} in @code{finger}.\r
-\r
-@item portability\r
-@samp{-c} in @code{cpio} and @code{tar}.\r
-\r
-@item posix\r
-Used in @code{gawk}.\r
-\r
-@item prefix-builtins\r
-@samp{-P} in @code{m4}.\r
-\r
-@item prefix\r
-@samp{-f} in @code{csplit}.\r
-\r
-@item preserve\r
-Used in @code{tar} and @code{cp}.\r
-\r
-@item preserve-environment\r
-@samp{-p} in @code{su}.\r
-\r
-@item preserve-modification-time\r
-@samp{-m} in @code{cpio}.\r
-\r
-@item preserve-order\r
-@samp{-s} in @code{tar}.\r
-\r
-@item preserve-permissions\r
-@samp{-p} in @code{tar}.\r
-\r
-@item print\r
-@samp{-l} in @code{diff}.\r
-\r
-@item print-chars\r
-@samp{-L} in @code{cmp}.\r
-\r
-@item print-data-base\r
-@samp{-p} in Make.\r
-\r
-@item print-directory\r
-@samp{-w} in Make.\r
-\r
-@item print-file-name\r
-@samp{-o} in @code{nm}.\r
-\r
-@item print-symdefs\r
-@samp{-s} in @code{nm}.\r
-\r
-@item printer\r
-@samp{-p} in @code{wdiff}.\r
-\r
-@item prompt\r
-@samp{-p} in @code{ed}.\r
-\r
-@item proxy\r
-Specify an HTTP proxy.\r
-\r
-@item query-user\r
-@samp{-X} in @code{shar}.\r
-\r
-@item question\r
-@samp{-q} in Make.\r
-\r
-@item quiet\r
-Used in many programs to inhibit the usual output. @strong{Note:} every\r
-program accepting @samp{--quiet} should accept @samp{--silent} as a\r
-synonym.\r
-\r
-@item quiet-unshar\r
-@samp{-Q} in @code{shar}\r
-\r
-@item quote-name\r
-@samp{-Q} in @code{ls}.\r
-\r
-@item rcs\r
-@samp{-n} in @code{diff}.\r
-\r
-@item re-interval\r
-Used in @code{gawk}.\r
-\r
-@item read-full-blocks\r
-@samp{-B} in @code{tar}.\r
-\r
-@item readnow\r
-Used in GDB.\r
-\r
-@item recon\r
-@samp{-n} in Make.\r
-\r
-@item record-number\r
-@samp{-R} in @code{tar}.\r
-\r
-@item recursive\r
-Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},\r
-and @code{rm}.\r
-\r
-@item reference-limit\r
-Used in @code{makeinfo}.\r
-\r
-@item references\r
-@samp{-r} in @code{ptx}.\r
-\r
-@item regex\r
-@samp{-r} in @code{tac} and @code{etags}.\r
-\r
-@item release\r
-@samp{-r} in @code{uname}.\r
-\r
-@item reload-state\r
-@samp{-R} in @code{m4}.\r
-\r
-@item relocation\r
-@samp{-r} in @code{objdump}.\r
-\r
-@item rename\r
-@samp{-r} in @code{cpio}.\r
-\r
-@item replace\r
-@samp{-i} in @code{xargs}.\r
-\r
-@item report-identical-files\r
-@samp{-s} in @code{diff}.\r
-\r
-@item reset-access-time\r
-@samp{-a} in @code{cpio}.\r
-\r
-@item reverse\r
-@samp{-r} in @code{ls} and @code{nm}.\r
-\r
-@item reversed-ed\r
-@samp{-f} in @code{diff}.\r
-\r
-@item right-side-defs\r
-@samp{-R} in @code{ptx}.\r
-\r
-@item same-order\r
-@samp{-s} in @code{tar}.\r
-\r
-@item same-permissions\r
-@samp{-p} in @code{tar}.\r
-\r
-@item save\r
-@samp{-g} in @code{stty}.\r
-\r
-@item se\r
-Used in GDB.\r
-\r
-@item sentence-regexp\r
-@samp{-S} in @code{ptx}.\r
-\r
-@item separate-dirs\r
-@samp{-S} in @code{du}.\r
-\r
-@item separator\r
-@samp{-s} in @code{tac}.\r
-\r
-@item sequence\r
-Used by @code{recode} to chose files or pipes for sequencing passes.\r
-\r
-@item shell\r
-@samp{-s} in @code{su}.\r
-\r
-@item show-all\r
-@samp{-A} in @code{cat}.\r
-\r
-@item show-c-function\r
-@samp{-p} in @code{diff}.\r
-\r
-@item show-ends\r
-@samp{-E} in @code{cat}.\r
-\r
-@item show-function-line\r
-@samp{-F} in @code{diff}.\r
-\r
-@item show-tabs\r
-@samp{-T} in @code{cat}.\r
-\r
-@item silent\r
-Used in many programs to inhibit the usual output.\r
-@strong{Note:} every program accepting\r
-@samp{--silent} should accept @samp{--quiet} as a synonym.\r
-\r
-@item size\r
-@samp{-s} in @code{ls}.\r
-\r
-@item socket\r
-Specify a file descriptor for a network server to use for its socket,\r
-instead of opening and binding a new socket. This provides a way to\r
-run, in a nonpriveledged process, a server that normally needs a\r
-reserved port number.\r
-\r
-@item sort\r
-Used in @code{ls}.\r
-\r
-@item source\r
-@samp{-W source} in @code{gawk}.\r
-\r
-@item sparse\r
-@samp{-S} in @code{tar}.\r
-\r
-@item speed-large-files\r
-@samp{-H} in @code{diff}.\r
-\r
-@item split-at\r
-@samp{-E} in @code{unshar}.\r
-\r
-@item split-size-limit\r
-@samp{-L} in @code{shar}.\r
-\r
-@item squeeze-blank\r
-@samp{-s} in @code{cat}.\r
-\r
-@item start-delete\r
-@samp{-w} in @code{wdiff}.\r
-\r
-@item start-insert\r
-@samp{-y} in @code{wdiff}.\r
-\r
-@item starting-file\r
-Used in @code{tar} and @code{diff} to specify which file within\r
-a directory to start processing with.\r
-\r
-@item statistics\r
-@samp{-s} in @code{wdiff}.\r
-\r
-@item stdin-file-list\r
-@samp{-S} in @code{shar}.\r
-\r
-@item stop\r
-@samp{-S} in Make.\r
-\r
-@item strict\r
-@samp{-s} in @code{recode}.\r
-\r
-@item strip\r
-@samp{-s} in @code{install}.\r
-\r
-@item strip-all\r
-@samp{-s} in @code{strip}.\r
-\r
-@item strip-debug\r
-@samp{-S} in @code{strip}.\r
-\r
-@item submitter\r
-@samp{-s} in @code{shar}.\r
-\r
-@item suffix\r
-@samp{-S} in @code{cp}, @code{ln}, @code{mv}.\r
-\r
-@item suffix-format\r
-@samp{-b} in @code{csplit}.\r
-\r
-@item sum\r
-@samp{-s} in @code{gprof}.\r
-\r
-@item summarize\r
-@samp{-s} in @code{du}.\r
-\r
-@item symbolic\r
-@samp{-s} in @code{ln}.\r
-\r
-@item symbols\r
-Used in GDB and @code{objdump}.\r
-\r
-@item synclines\r
-@samp{-s} in @code{m4}.\r
-\r
-@item sysname\r
-@samp{-s} in @code{uname}.\r
-\r
-@item tabs\r
-@samp{-t} in @code{expand} and @code{unexpand}.\r
-\r
-@item tabsize\r
-@samp{-T} in @code{ls}.\r
-\r
-@item terminal\r
-@samp{-T} in @code{tput} and @code{ul}.\r
-@samp{-t} in @code{wdiff}.\r
-\r
-@item text\r
-@samp{-a} in @code{diff}.\r
-\r
-@item text-files\r
-@samp{-T} in @code{shar}.\r
-\r
-@item time\r
-Used in @code{ls} and @code{touch}.\r
-\r
-@item timeout\r
-Specify how long to wait before giving up on some operation.\r
-\r
-@item to-stdout\r
-@samp{-O} in @code{tar}.\r
-\r
-@item total\r
-@samp{-c} in @code{du}.\r
-\r
-@item touch\r
-@samp{-t} in Make, @code{ranlib}, and @code{recode}.\r
-\r
-@item trace\r
-@samp{-t} in @code{m4}.\r
-\r
-@item traditional\r
-@samp{-t} in @code{hello};\r
-@samp{-W traditional} in @code{gawk};\r
-@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.\r
-\r
-@item tty\r
-Used in GDB.\r
-\r
-@item typedefs\r
-@samp{-t} in @code{ctags}.\r
-\r
-@item typedefs-and-c++\r
-@samp{-T} in @code{ctags}.\r
-\r
-@item typeset-mode\r
-@samp{-t} in @code{ptx}.\r
-\r
-@item uncompress\r
-@samp{-z} in @code{tar}.\r
-\r
-@item unconditional\r
-@samp{-u} in @code{cpio}.\r
-\r
-@item undefine\r
-@samp{-U} in @code{m4}.\r
-\r
-@item undefined-only\r
-@samp{-u} in @code{nm}.\r
-\r
-@item update\r
-@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.\r
-\r
-@item usage\r
-Used in @code{gawk}; same as @samp{--help}.\r
-\r
-@item uuencode\r
-@samp{-B} in @code{shar}.\r
-\r
-@item vanilla-operation\r
-@samp{-V} in @code{shar}.\r
-\r
-@item verbose\r
-Print more information about progress. Many programs support this.\r
-\r
-@item verify\r
-@samp{-W} in @code{tar}.\r
-\r
-@item version\r
-Print the version number.\r
-\r
-@item version-control\r
-@samp{-V} in @code{cp}, @code{ln}, @code{mv}.\r
-\r
-@item vgrind\r
-@samp{-v} in @code{ctags}.\r
-\r
-@item volume\r
-@samp{-V} in @code{tar}.\r
-\r
-@item what-if\r
-@samp{-W} in Make.\r
-\r
-@item whole-size-limit\r
-@samp{-l} in @code{shar}.\r
-\r
-@item width\r
-@samp{-w} in @code{ls} and @code{ptx}.\r
-\r
-@item word-regexp\r
-@samp{-W} in @code{ptx}.\r
-\r
-@item writable\r
-@samp{-T} in @code{who}.\r
-\r
-@item zeros\r
-@samp{-z} in @code{gprof}.\r
-@end table\r
-\r
-@node Memory Usage\r
-@section Memory Usage\r
-\r
-If it typically uses just a few meg of memory, don't bother making any\r
-effort to reduce memory usage. For example, if it is impractical for\r
-other reasons to operate on files more than a few meg long, it is\r
-reasonable to read entire input files into core to operate on them.\r
-\r
-However, for programs such as @code{cat} or @code{tail}, that can\r
-usefully operate on very large files, it is important to avoid using a\r
-technique that would artificially limit the size of files it can handle.\r
-If a program works by lines and could be applied to arbitrary\r
-user-supplied input files, it should keep only a line in memory, because\r
-this is not very hard and users will want to be able to operate on input\r
-files that are bigger than will fit in core all at once.\r
-\r
-If your program creates complicated data structures, just make them in\r
-core and give a fatal error if @code{malloc} returns zero.\r
-\r
-@node Writing C\r
-@chapter Making The Best Use of C\r
-\r
-This @value{CHAPTER} provides advice on how best to use the C language\r
-when writing GNU software.\r
-\r
-@menu\r
-* Formatting:: Formatting Your Source Code\r
-* Comments:: Commenting Your Work\r
-* Syntactic Conventions:: Clean Use of C Constructs\r
-* Names:: Naming Variables and Functions\r
-* System Portability:: Portability between different operating systems\r
-* CPU Portability:: Supporting the range of CPU types\r
-* System Functions:: Portability and ``standard'' library functions\r
-* Internationalization:: Techniques for internationalization\r
-* Mmap:: How you can safely use @code{mmap}.\r
-@end menu\r
-\r
-@node Formatting\r
-@section Formatting Your Source Code\r
-@cindex formatting source code\r
-\r
-It is important to put the open-brace that starts the body of a C\r
-function in column zero, and avoid putting any other open-brace or\r
-open-parenthesis or open-bracket in column zero. Several tools look\r
-for open-braces in column zero to find the beginnings of C functions.\r
-These tools will not work on code not formatted that way.\r
-\r
-It is also important for function definitions to start the name of the\r
-function in column zero. This helps people to search for function\r
-definitions, and may also help certain tools recognize them. Thus,\r
-the proper format is this:\r
-\r
-@example\r
-static char *\r
-concat (s1, s2) /* Name starts in column zero here */\r
- char *s1, *s2;\r
-@{ /* Open brace in column zero here */\r
- @dots{}\r
-@}\r
-@end example\r
-\r
-@noindent\r
-or, if you want to use Standard C syntax, format the definition like\r
-this:\r
-\r
-@example\r
-static char *\r
-concat (char *s1, char *s2)\r
-@{\r
- @dots{}\r
-@}\r
-@end example\r
-\r
-In Standard C, if the arguments don't fit nicely on one line,\r
-split it like this:\r
-\r
-@example\r
-int\r
-lots_of_args (int an_integer, long a_long, short a_short,\r
- double a_double, float a_float)\r
-@dots{}\r
-@end example\r
-\r
-The rest of this section gives our recommendations for other aspects of\r
-C formatting style. We don't think of them as requirements, because it\r
-causes no problems for users if two different programs have different\r
-formatting styles.\r
-\r
-But whatever style you use, please use it consistently, since a mixture\r
-of styles within one program tends to look ugly. If you are\r
-contributing changes to an existing program, please follow the style of\r
-that program.\r
-\r
-For the body of the function, our recommended style looks like this:\r
-\r
-@example\r
-if (x < foo (y, z))\r
- haha = bar[4] + 5;\r
-else\r
- @{\r
- while (z)\r
- @{\r
- haha += foo (z, z);\r
- z--;\r
- @}\r
- return ++x + bar ();\r
- @}\r
-@end example\r
-\r
-@cindex spaces before open-paren\r
-We find it easier to read a program when it has spaces before the\r
-open-parentheses and after the commas. Especially after the commas.\r
-\r
-When you split an expression into multiple lines, split it\r
-before an operator, not after one. Here is the right way:\r
-\r
-@cindex expressions, splitting\r
-@example\r
-if (foo_this_is_long && bar > win (x, y, z)\r
- && remaining_condition)\r
-@end example\r
-\r
-Try to avoid having two operators of different precedence at the same\r
-level of indentation. For example, don't write this:\r
-\r
-@example\r
-mode = (inmode[j] == VOIDmode\r
- || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])\r
- ? outmode[j] : inmode[j]);\r
-@end example\r
-\r
-Instead, use extra parentheses so that the indentation shows the nesting:\r
-\r
-@example\r
-mode = ((inmode[j] == VOIDmode\r
- || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))\r
- ? outmode[j] : inmode[j]);\r
-@end example\r
-\r
-Insert extra parentheses so that Emacs will indent the code properly.\r
-For example, the following indentation looks nice if you do it by hand,\r
-\r
-@example\r
-v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000\r
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;\r
-@end example\r
-\r
-@noindent\r
-but Emacs would alter it. Adding a set of parentheses produces\r
-something that looks equally nice, and which Emacs will preserve:\r
-\r
-@example\r
-v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000\r
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);\r
-@end example\r
-\r
-Format do-while statements like this:\r
-\r
-@example\r
-do\r
- @{\r
- a = foo (a);\r
- @}\r
-while (a > 0);\r
-@end example\r
-\r
-@cindex formfeed\r
-@cindex control-L\r
-Please use formfeed characters (control-L) to divide the program into\r
-pages at logical places (but not within a function). It does not matter\r
-just how long the pages are, since they do not have to fit on a printed\r
-page. The formfeeds should appear alone on lines by themselves.\r
-\r
-@node Comments\r
-@section Commenting Your Work\r
-@cindex commenting\r
-\r
-Every program should start with a comment saying briefly what it is for.\r
-Example: @samp{fmt - filter for simple filling of text}.\r
-\r
-Please write the comments in a GNU program in English, because English\r
-is the one language that nearly all programmers in all countries can\r
-read. If you do not write English well, please write comments in\r
-English as well as you can, then ask other people to help rewrite them.\r
-If you can't write comments in English, please find someone to work with\r
-you and translate your comments into English.\r
-\r
-Please put a comment on each function saying what the function does,\r
-what sorts of arguments it gets, and what the possible values of\r
-arguments mean and are used for. It is not necessary to duplicate in\r
-words the meaning of the C argument declarations, if a C type is being\r
-used in its customary fashion. If there is anything nonstandard about\r
-its use (such as an argument of type @code{char *} which is really the\r
-address of the second character of a string, not the first), or any\r
-possible values that would not work the way one would expect (such as,\r
-that strings containing newlines are not guaranteed to work), be sure\r
-to say so.\r
-\r
-Also explain the significance of the return value, if there is one.\r
-\r
-Please put two spaces after the end of a sentence in your comments, so\r
-that the Emacs sentence commands will work. Also, please write\r
-complete sentences and capitalize the first word. If a lower-case\r
-identifier comes at the beginning of a sentence, don't capitalize it!\r
-Changing the spelling makes it a different identifier. If you don't\r
-like starting a sentence with a lower case letter, write the sentence\r
-differently (e.g., ``The identifier lower-case is @dots{}'').\r
-\r
-The comment on a function is much clearer if you use the argument\r
-names to speak about the argument values. The variable name itself\r
-should be lower case, but write it in upper case when you are speaking\r
-about the value rather than the variable itself. Thus, ``the inode\r
-number NODE_NUM'' rather than ``an inode''.\r
-\r
-There is usually no purpose in restating the name of the function in\r
-the comment before it, because the reader can see that for himself.\r
-There might be an exception when the comment is so long that the function\r
-itself would be off the bottom of the screen.\r
-\r
-There should be a comment on each static variable as well, like this:\r
-\r
-@example\r
-/* Nonzero means truncate lines in the display;\r
- zero means continue them. */\r
-int truncate_lines;\r
-@end example\r
-\r
-Every @samp{#endif} should have a comment, except in the case of short\r
-conditionals (just a few lines) that are not nested. The comment should\r
-state the condition of the conditional that is ending, @emph{including\r
-its sense}. @samp{#else} should have a comment describing the condition\r
-@emph{and sense} of the code that follows. For example:\r
-\r
-@example\r
-@group\r
-#ifdef foo\r
- @dots{}\r
-#else /* not foo */\r
- @dots{}\r
-#endif /* not foo */\r
-@end group\r
-@group\r
-#ifdef foo\r
- @dots{}\r
-#endif /* foo */\r
-@end group\r
-@end example\r
-\r
-@noindent\r
-but, by contrast, write the comments this way for a @samp{#ifndef}:\r
-\r
-@example\r
-@group\r
-#ifndef foo\r
- @dots{}\r
-#else /* foo */\r
- @dots{}\r
-#endif /* foo */\r
-@end group\r
-@group\r
-#ifndef foo\r
- @dots{}\r
-#endif /* not foo */\r
-@end group\r
-@end example\r
-\r
-@node Syntactic Conventions\r
-@section Clean Use of C Constructs\r
-\r
-@cindex function argument, declaring\r
-Please explicitly declare all arguments to functions.\r
-Don't omit them just because they are @code{int}s.\r
-\r
-@cindex compiler warnings\r
-Some programmers like to use the GCC @samp{-Wall} option, and change the\r
-code whenever it issues a warning. If you want to do this, then do.\r
-Other programmers prefer not to use @samp{-Wall}, because it gives\r
-warnings for valid and legitimate code which they do not want to change.\r
-If you want to do this, then do. The compiler should be your servant,\r
-not your master.\r
-\r
-Declarations of external functions and functions to appear later in the\r
-source file should all go in one place near the beginning of the file\r
-(somewhere before the first function definition in the file), or else\r
-should go in a header file. Don't put @code{extern} declarations inside\r
-functions.\r
-\r
-It used to be common practice to use the same local variables (with\r
-names like @code{tem}) over and over for different values within one\r
-function. Instead of doing this, it is better declare a separate local\r
-variable for each distinct purpose, and give it a name which is\r
-meaningful. This not only makes programs easier to understand, it also\r
-facilitates optimization by good compilers. You can also move the\r
-declaration of each local variable into the smallest scope that includes\r
-all its uses. This makes the program even cleaner.\r
-\r
-Don't use local variables or parameters that shadow global identifiers.\r
-\r
-@cindex multiple variables in a line\r
-Don't declare multiple variables in one declaration that spans lines.\r
-Start a new declaration on each line, instead. For example, instead\r
-of this:\r
-\r
-@example\r
-@group\r
-int foo,\r
- bar;\r
-@end group\r
-@end example\r
-\r
-@noindent\r
-write either this:\r
-\r
-@example\r
-int foo, bar;\r
-@end example\r
-\r
-@noindent\r
-or this:\r
-\r
-@example\r
-int foo;\r
-int bar;\r
-@end example\r
-\r
-@noindent\r
-(If they are global variables, each should have a comment preceding it\r
-anyway.)\r
-\r
-When you have an @code{if}-@code{else} statement nested in another\r
-@code{if} statement, always put braces around the @code{if}-@code{else}.\r
-Thus, never write like this:\r
-\r
-@example\r
-if (foo)\r
- if (bar)\r
- win ();\r
- else\r
- lose ();\r
-@end example\r
-\r
-@noindent\r
-always like this:\r
-\r
-@example\r
-if (foo)\r
- @{\r
- if (bar)\r
- win ();\r
- else\r
- lose ();\r
- @}\r
-@end example\r
-\r
-If you have an @code{if} statement nested inside of an @code{else}\r
-statement, either write @code{else if} on one line, like this,\r
-\r
-@example\r
-if (foo)\r
- @dots{}\r
-else if (bar)\r
- @dots{}\r
-@end example\r
-\r
-@noindent\r
-with its @code{then}-part indented like the preceding @code{then}-part,\r
-or write the nested @code{if} within braces like this:\r
-\r
-@example\r
-if (foo)\r
- @dots{}\r
-else\r
- @{\r
- if (bar)\r
- @dots{}\r
- @}\r
-@end example\r
-\r
-Don't declare both a structure tag and variables or typedefs in the\r
-same declaration. Instead, declare the structure tag separately\r
-and then use it to declare the variables or typedefs.\r
-\r
-Try to avoid assignments inside @code{if}-conditions. For example,\r
-don't write this:\r
-\r
-@example\r
-if ((foo = (char *) malloc (sizeof *foo)) == 0)\r
- fatal ("virtual memory exhausted");\r
-@end example\r
-\r
-@noindent\r
-instead, write this:\r
-\r
-@example\r
-foo = (char *) malloc (sizeof *foo);\r
-if (foo == 0)\r
- fatal ("virtual memory exhausted");\r
-@end example\r
-\r
-Don't make the program ugly to placate @code{lint}. Please don't insert any\r
-casts to @code{void}. Zero without a cast is perfectly fine as a null\r
-pointer constant, except when calling a varargs function.\r
-\r
-@node Names\r
-@section Naming Variables and Functions\r
-\r
-@cindex names of variables and functions\r
-The names of global variables and functions in a program serve as\r
-comments of a sort. So don't choose terse names---instead, look for\r
-names that give useful information about the meaning of the variable or\r
-function. In a GNU program, names should be English, like other\r
-comments.\r
-\r
-Local variable names can be shorter, because they are used only within\r
-one context, where (presumably) comments explain their purpose.\r
-\r
-Try to limit your use of abbreviations in symbol names. It is ok to\r
-make a few abbreviations, explain what they mean, and then use them\r
-frequently, but don't use lots of obscure abbreviations.\r
-\r
-Please use underscores to separate words in a name, so that the Emacs\r
-word commands can be useful within them. Stick to lower case; reserve\r
-upper case for macros and @code{enum} constants, and for name-prefixes\r
-that follow a uniform convention.\r
-\r
-For example, you should use names like @code{ignore_space_change_flag};\r
-don't use names like @code{iCantReadThis}.\r
-\r
-Variables that indicate whether command-line options have been\r
-specified should be named after the meaning of the option, not after\r
-the option-letter. A comment should state both the exact meaning of\r
-the option and its letter. For example,\r
-\r
-@example\r
-@group\r
-/* Ignore changes in horizontal whitespace (-b). */\r
-int ignore_space_change_flag;\r
-@end group\r
-@end example\r
-\r
-When you want to define names with constant integer values, use\r
-@code{enum} rather than @samp{#define}. GDB knows about enumeration\r
-constants.\r
-\r
-Use file names of 14 characters or less, to avoid creating gratuitous\r
-problems on older System V systems. You can use the program\r
-@code{doschk} to test for this. @code{doschk} also tests for potential\r
-name conflicts if the files were loaded onto an MS-DOS file\r
-system---something you may or may not care about.\r
-\r
-@node System Portability\r
-@section Portability between System Types\r
-\r
-In the Unix world, ``portability'' refers to porting to different Unix\r
-versions. For a GNU program, this kind of portability is desirable, but\r
-not paramount.\r
-\r
-The primary purpose of GNU software is to run on top of the GNU kernel,\r
-compiled with the GNU C compiler, on various types of @sc{cpu}. The\r
-amount and kinds of variation among GNU systems on different @sc{cpu}s\r
-will be comparable to the variation among Linux-based GNU systems or\r
-among BSD systems today. So the kinds of portability that are absolutely\r
-necessary are quite limited.\r
-\r
-But many users do run GNU software on non-GNU Unix or Unix-like systems.\r
-So supporting a variety of Unix-like systems is desirable, although not\r
-paramount.\r
-\r
-The easiest way to achieve portability to most Unix-like systems is to\r
-use Autoconf. It's unlikely that your program needs to know more\r
-information about the host platform than Autoconf can provide, simply\r
-because most of the programs that need such knowledge have already been\r
-written.\r
-\r
-Avoid using the format of semi-internal data bases (e.g., directories)\r
-when there is a higher-level alternative (@code{readdir}).\r
-\r
-As for systems that are not like Unix, such as MSDOS, Windows, the\r
-Macintosh, VMS, and MVS, supporting them is often a lot of work. When\r
-that is the case, it is better to spend your time adding features that\r
-will be useful on GNU and GNU/Linux, rather than on supporting other\r
-incompatible systems.\r
-\r
-It is a good idea to define the ``feature test macro''\r
-@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU\r
-or GNU/Linux, this will enable the declarations of GNU library extension\r
-functions, and that will usually give you a compiler error message if\r
-you define the same function names in some other way in your program.\r
-(You don't have to actually @emph{use} these functions, if you prefer\r
-to make the program more portable to other systems.)\r
-\r
-But whether or not you use these GNU extensions, you should avoid\r
-using their names for any other meanings. Doing so would make it hard\r
-to move your code into other GNU programs.\r
-\r
-@node CPU Portability\r
-@section Portability between @sc{cpu}s\r
-\r
-Even GNU systems will differ because of differences among @sc{cpu}\r
-types---for example, difference in byte ordering and alignment\r
-requirements. It is absolutely essential to handle these differences.\r
-However, don't make any effort to cater to the possibility that an\r
-@code{int} will be less than 32 bits. We don't support 16-bit machines\r
-in GNU.\r
-\r
-Don't assume that the address of an @code{int} object is also the\r
-address of its least-significant byte. This is false on big-endian\r
-machines. Thus, don't make the following mistake:\r
-\r
-@example\r
-int c;\r
-@dots{}\r
-while ((c = getchar()) != EOF)\r
- write(file_descriptor, &c, 1);\r
-@end example\r
-\r
-When calling functions, you need not worry about the difference between\r
-pointers of various types, or between pointers and integers. On most\r
-machines, there's no difference anyway. As for the few machines where\r
-there is a difference, all of them support 1989 Standard C, so you can\r
-use prototypes (perhaps conditionalized to be active only in Standard C)\r
-to make the code work on those systems.\r
-\r
-In certain cases, it is ok to pass integer and pointer arguments\r
-indiscriminately to the same function, and use no prototype on any\r
-system. For example, many GNU programs have error-reporting functions\r
-that pass their arguments along to @code{printf} and friends:\r
-\r
-@example\r
-error (s, a1, a2, a3)\r
- char *s;\r
- char *a1, *a2, *a3;\r
-@{\r
- fprintf (stderr, "error: ");\r
- fprintf (stderr, s, a1, a2, a3);\r
-@}\r
-@end example\r
-\r
-@noindent\r
-In practice, this works on all machines, since a pointer is generally\r
-the widest possible kind of argument; it is much simpler than any\r
-``correct'' alternative. Be sure @emph{not} to use a prototype for such\r
-functions.\r
-\r
-If you have decided to use 1989 Standard C, then you can instead define\r
-@code{error} using @file{stdarg.h}, and pass the arguments along to\r
-@code{vfprintf}.\r
-\r
-Avoid casting pointers to integers if you can. Such casts greatly\r
-reduce portability, and in most programs they are easy to avoid. In the\r
-cases where casting pointers to integers is essential---such as, a Lisp\r
-interpreter which stores type information as well as an address in one\r
-word---you'll have to make explicit provisions to handle different word\r
-sizes. You will also need to make provision for systems in which the\r
-normal range of addresses you can get from @code{malloc} starts far away\r
-from zero.\r
-\r
-@node System Functions\r
-@section Calling System Functions\r
-\r
-C implementations differ substantially. 1989 Standard C reduces but does\r
-not eliminate the incompatibilities; meanwhile, many GNU packages still\r
-support pre-standard compilers because this is not hard to do. This\r
-chapter gives recommendations for how to use the more-or-less standard C\r
-library functions to avoid unnecessary loss of portability.\r
-\r
-@itemize @bullet\r
-@item\r
-Don't use the return value of @code{sprintf}. It returns the number of\r
-characters written on some systems, but not on all systems.\r
-\r
-@item\r
-Be aware that @code{vfprintf} is not always available.\r
-\r
-@item\r
-@code{main} should be declared to return type @code{int}. It should\r
-terminate either by calling @code{exit} or by returning the integer\r
-status code; make sure it cannot ever return an undefined value.\r
-\r
-@item\r
-Don't declare system functions explicitly.\r
-\r
-Almost any declaration for a system function is wrong on some system.\r
-To minimize conflicts, leave it to the system header files to declare\r
-system functions. If the headers don't declare a function, let it\r
-remain undeclared.\r
-\r
-While it may seem unclean to use a function without declaring it, in\r
-practice this works fine for most system library functions on the\r
-systems where this really happens; thus, the disadvantage is only\r
-theoretical. By contrast, actual declarations have frequently caused\r
-actual conflicts.\r
-\r
-@item\r
-If you must declare a system function, don't specify the argument types.\r
-Use an old-style declaration, not a Standard C prototype. The more you\r
-specify about the function, the more likely a conflict.\r
-\r
-@item\r
-In particular, don't unconditionally declare @code{malloc} or\r
-@code{realloc}.\r
-\r
-Most GNU programs use those functions just once, in functions\r
-conventionally named @code{xmalloc} and @code{xrealloc}. These\r
-functions call @code{malloc} and @code{realloc}, respectively, and\r
-check the results.\r
-\r
-Because @code{xmalloc} and @code{xrealloc} are defined in your program,\r
-you can declare them in other files without any risk of type conflict.\r
-\r
-On most systems, @code{int} is the same length as a pointer; thus, the\r
-calls to @code{malloc} and @code{realloc} work fine. For the few\r
-exceptional systems (mostly 64-bit machines), you can use\r
-@strong{conditionalized} declarations of @code{malloc} and\r
-@code{realloc}---or put these declarations in configuration files\r
-specific to those systems.\r
-\r
-@item\r
-The string functions require special treatment. Some Unix systems have\r
-a header file @file{string.h}; others have @file{strings.h}. Neither\r
-file name is portable. There are two things you can do: use Autoconf to\r
-figure out which file to include, or don't include either file.\r
-\r
-@item\r
-If you don't include either strings file, you can't get declarations for\r
-the string functions from the header file in the usual way.\r
-\r
-That causes less of a problem than you might think. The newer standard\r
-string functions should be avoided anyway because many systems still\r
-don't support them. The string functions you can use are these:\r
-\r
-@example\r
-strcpy strncpy strcat strncat\r
-strlen strcmp strncmp\r
-strchr strrchr\r
-@end example\r
-\r
-The copy and concatenate functions work fine without a declaration as\r
-long as you don't use their values. Using their values without a\r
-declaration fails on systems where the width of a pointer differs from\r
-the width of @code{int}, and perhaps in other cases. It is trivial to\r
-avoid using their values, so do that.\r
-\r
-The compare functions and @code{strlen} work fine without a declaration\r
-on most systems, possibly all the ones that GNU software runs on.\r
-You may find it necessary to declare them @strong{conditionally} on a\r
-few systems.\r
-\r
-The search functions must be declared to return @code{char *}. Luckily,\r
-there is no variation in the data type they return. But there is\r
-variation in their names. Some systems give these functions the names\r
-@code{index} and @code{rindex}; other systems use the names\r
-@code{strchr} and @code{strrchr}. Some systems support both pairs of\r
-names, but neither pair works on all systems.\r
-\r
-You should pick a single pair of names and use it throughout your\r
-program. (Nowadays, it is better to choose @code{strchr} and\r
-@code{strrchr} for new programs, since those are the standard\r
-names.) Declare both of those names as functions returning @code{char\r
-*}. On systems which don't support those names, define them as macros\r
-in terms of the other pair. For example, here is what to put at the\r
-beginning of your file (or in a header) if you want to use the names\r
-@code{strchr} and @code{strrchr} throughout:\r
-\r
-@example\r
-#ifndef HAVE_STRCHR\r
-#define strchr index\r
-#endif\r
-#ifndef HAVE_STRRCHR\r
-#define strrchr rindex\r
-#endif\r
-\r
-char *strchr ();\r
-char *strrchr ();\r
-@end example\r
-@end itemize\r
-\r
-Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are\r
-macros defined in systems where the corresponding functions exist.\r
-One way to get them properly defined is to use Autoconf.\r
-\r
-@node Internationalization\r
-@section Internationalization\r
-\r
-GNU has a library called GNU gettext that makes it easy to translate the\r
-messages in a program into various languages. You should use this\r
-library in every program. Use English for the messages as they appear\r
-in the program, and let gettext provide the way to translate them into\r
-other languages.\r
-\r
-Using GNU gettext involves putting a call to the @code{gettext} macro\r
-around each string that might need translation---like this:\r
-\r
-@example\r
-printf (gettext ("Processing file `%s'..."));\r
-@end example\r
-\r
-@noindent\r
-This permits GNU gettext to replace the string @code{"Processing file\r
-`%s'..."} with a translated version.\r
-\r
-Once a program uses gettext, please make a point of writing calls to\r
-@code{gettext} when you add new strings that call for translation.\r
-\r
-Using GNU gettext in a package involves specifying a @dfn{text domain\r
-name} for the package. The text domain name is used to separate the\r
-translations for this package from the translations for other packages.\r
-Normally, the text domain name should be the same as the name of the\r
-package---for example, @samp{fileutils} for the GNU file utilities.\r
-\r
-To enable gettext to work well, avoid writing code that makes\r
-assumptions about the structure of words or sentences. When you want\r
-the precise text of a sentence to vary depending on the data, use two or\r
-more alternative string constants each containing a complete sentences,\r
-rather than inserting conditionalized words or phrases into a single\r
-sentence framework.\r
-\r
-Here is an example of what not to do:\r
-\r
-@example\r
-printf ("%d file%s processed", nfiles,\r
- nfiles != 1 ? "s" : "");\r
-@end example\r
-\r
-@noindent\r
-The problem with that example is that it assumes that plurals are made\r
-by adding `s'. If you apply gettext to the format string, like this,\r
-\r
-@example\r
-printf (gettext ("%d file%s processed"), nfiles,\r
- nfiles != 1 ? "s" : "");\r
-@end example\r
-\r
-@noindent\r
-the message can use different words, but it will still be forced to use\r
-`s' for the plural. Here is a better way:\r
-\r
-@example\r
-printf ((nfiles != 1 ? "%d files processed"\r
- : "%d file processed"),\r
- nfiles);\r
-@end example\r
-\r
-@noindent\r
-This way, you can apply gettext to each of the two strings\r
-independently:\r
-\r
-@example\r
-printf ((nfiles != 1 ? gettext ("%d files processed")\r
- : gettext ("%d file processed")),\r
- nfiles);\r
-@end example\r
-\r
-@noindent\r
-This can be any method of forming the plural of the word for ``file'', and\r
-also handles languages that require agreement in the word for\r
-``processed''.\r
-\r
-A similar problem appears at the level of sentence structure with this\r
-code:\r
-\r
-@example\r
-printf ("# Implicit rule search has%s been done.\n",\r
- f->tried_implicit ? "" : " not");\r
-@end example\r
-\r
-@noindent\r
-Adding @code{gettext} calls to this code cannot give correct results for\r
-all languages, because negation in some languages requires adding words\r
-at more than one place in the sentence. By contrast, adding\r
-@code{gettext} calls does the job straightfowardly if the code starts\r
-out like this:\r
-\r
-@example\r
-printf (f->tried_implicit\r
- ? "# Implicit rule search has been done.\n",\r
- : "# Implicit rule search has not been done.\n");\r
-@end example\r
-\r
-@node Mmap\r
-@section Mmap\r
-\r
-Don't assume that @code{mmap} either works on all files or fails\r
-for all files. It may work on some files and fail on others.\r
-\r
-The proper way to use @code{mmap} is to try it on the specific file for\r
-which you want to use it---and if @code{mmap} doesn't work, fall back on\r
-doing the job in another way using @code{read} and @code{write}.\r
-\r
-The reason this precaution is needed is that the GNU kernel (the HURD)\r
-provides a user-extensible file system, in which there can be many\r
-different kinds of ``ordinary files.'' Many of them support\r
-@code{mmap}, but some do not. It is important to make programs handle\r
-all these kinds of files.\r
-\r
-@node Documentation\r
-@chapter Documenting Programs\r
-\r
-A GNU program should ideally come with full free documentation, adequate\r
-for both reference and tutorial purposes. If the package can be\r
-programmed or extended, the documentation should cover programming or\r
-extending it, as well as just using it.\r
-\r
-@menu\r
-* GNU Manuals:: Writing proper manuals.\r
-* Manual Structure Details:: Specific structure conventions.\r
-* License for Manuals:: Writing the distribution terms for a manual.\r
-* NEWS File:: NEWS files supplement manuals.\r
-* Change Logs:: Recording Changes\r
-* Man Pages:: Man pages are secondary.\r
-* Reading other Manuals:: How far you can go in learning\r
- from other manuals.\r
-@end menu\r
-\r
-@node GNU Manuals\r
-@section GNU Manuals\r
-\r
-The preferred way to document part of the GNU system is to write a\r
-manual in the Texinfo formatting language. This makes it possible to\r
-produce a good quality formatted book, using @TeX{}, and to generate an\r
-Info file. It is also possible to generate HTML output from Texinfo\r
-source. See the Texinfo manual, either the hardcopy, or the on-line\r
-version available through @code{info} or the Emacs Info subsystem\r
-(@kbd{C-h i}).\r
-\r
-Programmers often find it most natural to structure the documentation\r
-following the structure of the implementation, which they know. But\r
-this structure is not necessarily good for explaining how to use the\r
-program; it may be irrelevant and confusing for a user.\r
-\r
-At every level, from the sentences in a paragraph to the grouping of\r
-topics into separate manuals, the right way to structure documentation\r
-is according to the concepts and questions that a user will have in mind\r
-when reading it. Sometimes this structure of ideas matches the\r
-structure of the implementation of the software being documented---but\r
-often they are different. Often the most important part of learning to\r
-write good documentation is learning to notice when you are structuring\r
-the documentation like the implementation, and think about better\r
-alternatives.\r
-\r
-For example, each program in the GNU system probably ought to be\r
-documented in one manual; but this does not mean each program should\r
-have its own manual. That would be following the structure of the\r
-implementation, rather than the structure that helps the user\r
-understand.\r
-\r
-Instead, each manual should cover a coherent @emph{topic}. For example,\r
-instead of a manual for @code{diff} and a manual for @code{diff3}, we\r
-have one manual for ``comparison of files'' which covers both of those\r
-programs, as well as @code{cmp}. By documenting these programs\r
-together, we can make the whole subject clearer.\r
-\r
-The manual which discusses a program should document all of the\r
-program's command-line options and all of its commands. It should give\r
-examples of their use. But don't organize the manual as a list of\r
-features. Instead, organize it logically, by subtopics. Address the\r
-questions that a user will ask when thinking about the job that the\r
-program does.\r
-\r
-In general, a GNU manual should serve both as tutorial and reference.\r
-It should be set up for convenient access to each topic through Info,\r
-and for reading straight through (appendixes aside). A GNU manual\r
-should give a good introduction to a beginner reading through from the\r
-start, and should also provide all the details that hackers want.\r
-The Bison manual is a good example of this---please take a look at it\r
-to see what we mean.\r
-\r
-That is not as hard as it first sounds. Arrange each chapter as a\r
-logical breakdown of its topic, but order the sections, and write their\r
-text, so that reading the chapter straight through makes sense. Do\r
-likewise when structuring the book into chapters, and when structuring a\r
-section into paragraphs. The watchword is, @emph{at each point, address\r
-the most fundamental and important issue raised by the preceding text.}\r
-\r
-If necessary, add extra chapters at the beginning of the manual which\r
-are purely tutorial and cover the basics of the subject. These provide\r
-the framework for a beginner to understand the rest of the manual. The\r
-Bison manual provides a good example of how to do this.\r
-\r
-Don't use Unix man pages as a model for how to write GNU documentation;\r
-most of them are terse, badly structured, and give inadequate\r
-explanation of the underlying concepts. (There are, of course\r
-exceptions.) Also Unix man pages use a particular format which is\r
-different from what we use in GNU manuals.\r
-\r
-Please include an email address in the manual for where to report\r
-bugs @emph{in the manual}.\r
-\r
-Please do not use the term ``pathname'' that is used in Unix\r
-documentation; use ``file name'' (two words) instead. We use the term\r
-``path'' only for search paths, which are lists of directory names.\r
-\r
-Please do not use the term ``illegal'' to refer to erroneous input to a\r
-computer program. Please use ``invalid'' for this, and reserve the term\r
-``illegal'' for violations of law.\r
-\r
-@node Manual Structure Details\r
-@section Manual Structure Details\r
-\r
-The title page of the manual should state the version of the programs or\r
-packages documented in the manual. The Top node of the manual should\r
-also contain this information. If the manual is changing more\r
-frequently than or independent of the program, also state a version\r
-number for the manual in both of these places.\r
-\r
-Each program documented in the manual should have a node named\r
-@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This\r
-node (together with its subnodes, if any) should describe the program's\r
-command line arguments and how to run it (the sort of information people\r
-would look in a man page for). Start with an @samp{@@example}\r
-containing a template for all the options and arguments that the program\r
-uses.\r
-\r
-Alternatively, put a menu item in some menu whose item name fits one of\r
-the above patterns. This identifies the node which that item points to\r
-as the node for this purpose, regardless of the node's actual name.\r
-\r
-There will be automatic features for specifying a program name and\r
-quickly reading just this part of its manual.\r
-\r
-If one manual describes several programs, it should have such a node for\r
-each program described.\r
-\r
-@node License for Manuals\r
-@section License for Manuals\r
-\r
-Please use the GNU Free Documentation License for all GNU manuals that\r
-are more than a few pages long. Likewise for a collection of short\r
-documents---you only need one copy of the GNU FDL for the whole\r
-collection. For a single short document, you can use a very permissive\r
-non-copyleft license, to avoid taking up space with a long license.\r
-\r
-@node NEWS File\r
-@section The NEWS File\r
-\r
-In addition to its manual, the package should have a file named\r
-@file{NEWS} which contains a list of user-visible changes worth\r
-mentioning. In each new release, add items to the front of the file and\r
-identify the version they pertain to. Don't discard old items; leave\r
-them in the file after the newer items. This way, a user upgrading from\r
-any previous version can see what is new.\r
-\r
-If the @file{NEWS} file gets very long, move some of the older items\r
-into a file named @file{ONEWS} and put a note at the end referring the\r
-user to that file.\r
-\r
-@node Change Logs\r
-@section Change Logs\r
-\r
-Keep a change log to describe all the changes made to program source\r
-files. The purpose of this is so that people investigating bugs in the\r
-future will know about the changes that might have introduced the bug.\r
-Often a new bug can be found by looking at what was recently changed.\r
-More importantly, change logs can help you eliminate conceptual\r
-inconsistencies between different parts of a program, by giving you a\r
-history of how the conflicting concepts arose and who they came from.\r
-\r
-@menu\r
-* Change Log Concepts:: \r
-* Style of Change Logs:: \r
-* Simple Changes:: \r
-* Conditional Changes:: \r
-* Indicating the Part Changed::\r
-@end menu\r
-\r
-@node Change Log Concepts\r
-@subsection Change Log Concepts\r
-\r
-You can think of the change log as a conceptual ``undo list'' which\r
-explains how earlier versions were different from the current version.\r
-People can see the current version; they don't need the change log\r
-to tell them what is in it. What they want from a change log is a\r
-clear explanation of how the earlier version differed.\r
-\r
-The change log file is normally called @file{ChangeLog} and covers an\r
-entire directory. Each directory can have its own change log, or a\r
-directory can use the change log of its parent directory--it's up to\r
-you.\r
-\r
-Another alternative is to record change log information with a version\r
-control system such as RCS or CVS. This can be converted automatically\r
-to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command\r
-@kbd{C-x v a} (@code{vc-update-change-log}) does the job.\r
-\r
-There's no need to describe the full purpose of the changes or how they\r
-work together. If you think that a change calls for explanation, you're\r
-probably right. Please do explain it---but please put the explanation\r
-in comments in the code, where people will see it whenever they see the\r
-code. For example, ``New function'' is enough for the change log when\r
-you add a function, because there should be a comment before the\r
-function definition to explain what it does.\r
-\r
-However, sometimes it is useful to write one line to describe the\r
-overall purpose of a batch of changes.\r
-\r
-The easiest way to add an entry to @file{ChangeLog} is with the Emacs\r
-command @kbd{M-x add-change-log-entry}. An entry should have an\r
-asterisk, the name of the changed file, and then in parentheses the name\r
-of the changed functions, variables or whatever, followed by a colon.\r
-Then describe the changes you made to that function or variable.\r
-\r
-@node Style of Change Logs\r
-@subsection Style of Change Logs\r
-\r
-Here are some examples of change log entries:\r
-\r
-@example\r
-* register.el (insert-register): Return nil.\r
-(jump-to-register): Likewise.\r
-\r
-* sort.el (sort-subr): Return nil.\r
-\r
-* tex-mode.el (tex-bibtex-file, tex-file, tex-region):\r
-Restart the tex shell if process is gone or stopped.\r
-(tex-shell-running): New function.\r
-\r
-* expr.c (store_one_arg): Round size up for move_block_to_reg.\r
-(expand_call): Round up when emitting USE insns.\r
-* stmt.c (assign_parms): Round size up for move_block_from_reg.\r
-\r
-* keyboard.c (menu_bar_items, tool_bar_items)\r
-(Fexecute_extended_command): Deal with `keymap' property.\r
-@end example\r
-\r
-It's important to name the changed function or variable in full. Don't\r
-abbreviate function or variable names, and don't combine them.\r
-Subsequent maintainers will often search for a function name to find all\r
-the change log entries that pertain to it; if you abbreviate the name,\r
-they won't find it when they search.\r
-\r
-For example, some people are tempted to abbreviate groups of function\r
-names by writing @samp{* register.el (@{insert,jump-to@}-register)};\r
-this is not a good idea, since searching for @code{jump-to-register} or\r
-@code{insert-register} would not find that entry.\r
-\r
-Separate unrelated change log entries with blank lines. When two\r
-entries represent parts of the same change, so that they work together,\r
-then don't put blank lines between them. Then you can omit the file\r
-name and the asterisk when successive entries are in the same file.\r
-\r
-Break long lists of function names by closing continued lines with\r
-@samp{)}, rather than @samp{,}, and opening the continuation with\r
-@samp{(} as in the example above.\r
-\r
-@node Simple Changes\r
-@subsection Simple Changes\r
-\r
-Certain simple kinds of changes don't need much detail in the change\r
-log.\r
-\r
-When you change the calling sequence of a function in a simple fashion,\r
-and you change all the callers of the function, there is no need to make\r
-individual entries for all the callers that you changed. Just write in\r
-the entry for the function being called, ``All callers changed.''\r
-\r
-@example\r
-* keyboard.c (Fcommand_execute): New arg SPECIAL.\r
-All callers changed.\r
-@end example\r
-\r
-When you change just comments or doc strings, it is enough to write an\r
-entry for the file, without mentioning the functions. Just ``Doc\r
-fixes'' is enough for the change log.\r
-\r
-There's no need to make change log entries for documentation files.\r
-This is because documentation is not susceptible to bugs that are hard\r
-to fix. Documentation does not consist of parts that must interact in a\r
-precisely engineered fashion. To correct an error, you need not know\r
-the history of the erroneous passage; it is enough to compare what the\r
-documentation says with the way the program actually works.\r
-\r
-@node Conditional Changes\r
-@subsection Conditional Changes\r
-\r
-C programs often contain compile-time @code{#if} conditionals. Many\r
-changes are conditional; sometimes you add a new definition which is\r
-entirely contained in a conditional. It is very useful to indicate in\r
-the change log the conditions for which the change applies.\r
-\r
-Our convention for indicating conditional changes is to use square\r
-brackets around the name of the condition.\r
-\r
-Here is a simple example, describing a change which is conditional but\r
-does not have a function or entity name associated with it:\r
-\r
-@example\r
-* xterm.c [SOLARIS2]: Include string.h.\r
-@end example\r
-\r
-Here is an entry describing a new definition which is entirely\r
-conditional. This new definition for the macro @code{FRAME_WINDOW_P} is\r
-used only when @code{HAVE_X_WINDOWS} is defined:\r
-\r
-@example\r
-* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.\r
-@end example\r
-\r
-Here is an entry for a change within the function @code{init_display},\r
-whose definition as a whole is unconditional, but the changes themselves\r
-are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:\r
-\r
-@example\r
-* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.\r
-@end example\r
-\r
-Here is an entry for a change that takes affect only when\r
-a certain macro is @emph{not} defined:\r
-\r
-@example\r
-(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.\r
-@end example\r
-\r
-@node Indicating the Part Changed\r
-@subsection Indicating the Part Changed\r
-\r
-Indicate the part of a function which changed by using angle brackets\r
-enclosing an indication of what the changed part does. Here is an entry\r
-for a change in the part of the function that deals with @code{sh}\r
-commands.\r
-\r
-@example\r
-* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that\r
-user-specified option string is empty.\r
-@end example\r
-\r
-\r
-@node Man Pages\r
-@section Man Pages\r
-\r
-In the GNU project, man pages are secondary. It is not necessary or\r
-expected for every GNU program to have a man page, but some of them do.\r
-It's your choice whether to include a man page in your program.\r
-\r
-When you make this decision, consider that supporting a man page\r
-requires continual effort each time the program is changed. The time\r
-you spend on the man page is time taken away from more useful work.\r
-\r
-For a simple program which changes little, updating the man page may be\r
-a small job. Then there is little reason not to include a man page, if\r
-you have one.\r
-\r
-For a large program that changes a great deal, updating a man page may\r
-be a substantial burden. If a user offers to donate a man page, you may\r
-find this gift costly to accept. It may be better to refuse the man\r
-page unless the same person agrees to take full responsibility for\r
-maintaining it---so that you can wash your hands of it entirely. If\r
-this volunteer later ceases to do the job, then don't feel obliged to\r
-pick it up yourself; it may be better to withdraw the man page from the\r
-distribution until someone else agrees to update it.\r
-\r
-When a program changes only a little, you may feel that the\r
-discrepancies are small enough that the man page remains useful without\r
-updating. If so, put a prominent note near the beginning of the man\r
-page explaining that you don't maintain it and that the Texinfo manual\r
-is more authoritative. The note should say how to access the Texinfo\r
-documentation.\r
-\r
-@node Reading other Manuals\r
-@section Reading other Manuals\r
-\r
-There may be non-free books or documentation files that describe the\r
-program you are documenting.\r
-\r
-It is ok to use these documents for reference, just as the author of a\r
-new algebra textbook can read other books on algebra. A large portion\r
-of any non-fiction book consists of facts, in this case facts about how\r
-a certain program works, and these facts are necessarily the same for\r
-everyone who writes about the subject. But be careful not to copy your\r
-outline structure, wording, tables or examples from preexisting non-free\r
-documentation. Copying from free documentation may be ok; please check\r
-with the FSF about the individual case.\r
-\r
-@node Managing Releases\r
-@chapter The Release Process\r
-\r
-Making a release is more than just bundling up your source files in a\r
-tar file and putting it up for FTP. You should set up your software so\r
-that it can be configured to run on a variety of systems. Your Makefile\r
-should conform to the GNU standards described below, and your directory\r
-layout should also conform to the standards discussed below. Doing so\r
-makes it easy to include your package into the larger framework of\r
-all GNU software.\r
-\r
-@menu\r
-* Configuration:: How Configuration Should Work\r
-* Makefile Conventions:: Makefile Conventions\r
-* Releases:: Making Releases\r
-@end menu\r
-\r
-@node Configuration\r
-@section How Configuration Should Work\r
-\r
-Each GNU distribution should come with a shell script named\r
-@code{configure}. This script is given arguments which describe the\r
-kind of machine and system you want to compile the program for.\r
-\r
-The @code{configure} script must record the configuration options so\r
-that they affect compilation.\r
-\r
-One way to do this is to make a link from a standard name such as\r
-@file{config.h} to the proper configuration file for the chosen system.\r
-If you use this technique, the distribution should @emph{not} contain a\r
-file named @file{config.h}. This is so that people won't be able to\r
-build the program without configuring it first.\r
-\r
-Another thing that @code{configure} can do is to edit the Makefile. If\r
-you do this, the distribution should @emph{not} contain a file named\r
-@file{Makefile}. Instead, it should include a file @file{Makefile.in} which\r
-contains the input used for editing. Once again, this is so that people\r
-won't be able to build the program without configuring it first.\r
-\r
-If @code{configure} does write the @file{Makefile}, then @file{Makefile}\r
-should have a target named @file{Makefile} which causes @code{configure}\r
-to be rerun, setting up the same configuration that was set up last\r
-time. The files that @code{configure} reads should be listed as\r
-dependencies of @file{Makefile}.\r
-\r
-All the files which are output from the @code{configure} script should\r
-have comments at the beginning explaining that they were generated\r
-automatically using @code{configure}. This is so that users won't think\r
-of trying to edit them by hand.\r
-\r
-The @code{configure} script should write a file named @file{config.status}\r
-which describes which configuration options were specified when the\r
-program was last configured. This file should be a shell script which,\r
-if run, will recreate the same configuration.\r
-\r
-The @code{configure} script should accept an option of the form\r
-@samp{--srcdir=@var{dirname}} to specify the directory where sources are found\r
-(if it is not the current directory). This makes it possible to build\r
-the program in a separate directory, so that the actual source directory\r
-is not modified.\r
-\r
-If the user does not specify @samp{--srcdir}, then @code{configure} should\r
-check both @file{.} and @file{..} to see if it can find the sources. If\r
-it finds the sources in one of these places, it should use them from\r
-there. Otherwise, it should report that it cannot find the sources, and\r
-should exit with nonzero status.\r
-\r
-Usually the easy way to support @samp{--srcdir} is by editing a\r
-definition of @code{VPATH} into the Makefile. Some rules may need to\r
-refer explicitly to the specified source directory. To make this\r
-possible, @code{configure} can add to the Makefile a variable named\r
-@code{srcdir} whose value is precisely the specified directory.\r
-\r
-The @code{configure} script should also take an argument which specifies the\r
-type of system to build the program for. This argument should look like\r
-this:\r
-\r
-@example\r
-@var{cpu}-@var{company}-@var{system}\r
-@end example\r
-\r
-For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.\r
-\r
-The @code{configure} script needs to be able to decode all plausible\r
-alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}\r
-would be a valid alias. For many programs, @samp{vax-dec-ultrix} would\r
-be an alias for @samp{vax-dec-bsd}, simply because the differences\r
-between Ultrix and @sc{bsd} are rarely noticeable, but a few programs\r
-might need to distinguish them.\r
-@c Real 4.4BSD now runs on some Suns.\r
-\r
-There is a shell script called @file{config.sub} that you can use\r
-as a subroutine to validate system types and canonicalize aliases.\r
-\r
-Other options are permitted to specify in more detail the software\r
-or hardware present on the machine, and include or exclude optional\r
-parts of the package:\r
-\r
-@table @samp\r
-@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}\r
-Configure the package to build and install an optional user-level\r
-facility called @var{feature}. This allows users to choose which\r
-optional features to include. Giving an optional @var{parameter} of\r
-@samp{no} should omit @var{feature}, if it is built by default.\r
-\r
-No @samp{--enable} option should @strong{ever} cause one feature to\r
-replace another. No @samp{--enable} option should ever substitute one\r
-useful behavior for another useful behavior. The only proper use for\r
-@samp{--enable} is for questions of whether to build part of the program\r
-or exclude it.\r
-\r
-@item --with-@var{package}\r
-@c @r{[}=@var{parameter}@r{]}\r
-The package @var{package} will be installed, so configure this package\r
-to work with @var{package}.\r
-\r
-@c Giving an optional @var{parameter} of\r
-@c @samp{no} should omit @var{package}, if it is used by default.\r
-\r
-Possible values of @var{package} include \r
-@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},\r
-@samp{gdb},\r
-@samp{x}, \r
-and\r
-@samp{x-toolkit}.\r
-\r
-Do not use a @samp{--with} option to specify the file name to use to\r
-find certain files. That is outside the scope of what @samp{--with}\r
-options are for.\r
-\r
-@item --nfp\r
-The target machine has no floating point processor.\r
-\r
-@item --gas\r
-The target machine assembler is GAS, the GNU assembler.\r
-This is obsolete; users should use @samp{--with-gnu-as} instead.\r
-\r
-@item --x\r
-The target machine has the X Window System installed.\r
-This is obsolete; users should use @samp{--with-x} instead.\r
-@end table\r
-\r
-All @code{configure} scripts should accept all of these ``detail''\r
-options, whether or not they make any difference to the particular\r
-package at hand. In particular, they should accept any option that\r
-starts with @samp{--with-} or @samp{--enable-}. This is so users will\r
-be able to configure an entire GNU source tree at once with a single set\r
-of options.\r
-\r
-You will note that the categories @samp{--with-} and @samp{--enable-}\r
-are narrow: they @strong{do not} provide a place for any sort of option\r
-you might think of. That is deliberate. We want to limit the possible\r
-configuration options in GNU software. We do not want GNU programs to\r
-have idiosyncratic configuration options.\r
-\r
-Packages that perform part of the compilation process may support cross-compilation.\r
-In such a case, the host and target machines for the program may be\r
-different. The @code{configure} script should normally treat the\r
-specified type of system as both the host and the target, thus producing\r
-a program which works for the same type of machine that it runs on.\r
-\r
-The way to build a cross-compiler, cross-assembler, or what have you, is\r
-to specify the option @samp{--host=@var{hosttype}} when running\r
-@code{configure}. This specifies the host system without changing the\r
-type of target system. The syntax for @var{hosttype} is the same as\r
-described above.\r
-\r
-Bootstrapping a cross-compiler requires compiling it on a machine other\r
-than the host it will run on. Compilation packages accept a\r
-configuration option @samp{--build=@var{hosttype}} for specifying the\r
-configuration on which you will compile them, in case that is different\r
-from the host.\r
-\r
-Programs for which cross-operation is not meaningful need not accept the\r
-@samp{--host} option, because configuring an entire operating system for\r
-cross-operation is not a meaningful thing.\r
-\r
-Some programs have ways of configuring themselves automatically. If\r
-your program is set up to do this, your @code{configure} script can simply\r
-ignore most of its arguments.\r
-\r
-@comment The makefile standards are in a separate file that is also\r
-@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.\r
-@comment For this document, turn chapters into sections, etc.\r
-@lowersections\r
-@include make-stds.texi\r
-@raisesections\r
-\r
-@node Releases\r
-@section Making Releases\r
-\r
-Package the distribution of @code{Foo version 69.96} up in a gzipped tar\r
-file with the name @file{foo-69.96.tar.gz}. It should unpack into a\r
-subdirectory named @file{foo-69.96}.\r
-\r
-Building and installing the program should never modify any of the files\r
-contained in the distribution. This means that all the files that form\r
-part of the program in any way must be classified into @dfn{source\r
-files} and @dfn{non-source files}. Source files are written by humans\r
-and never changed automatically; non-source files are produced from\r
-source files by programs under the control of the Makefile.\r
-\r
-The distribution should contain a file named @file{README} which gives\r
-the name of the package, and a general description of what it does. It\r
-is also good to explain the purpose of each of the first-level\r
-subdirectories in the package, if there are any. The @file{README} file\r
-should either state the version number of the package, or refer to where\r
-in the package it can be found.\r
-\r
-The @file{README} file should refer to the file @file{INSTALL}, which\r
-should contain an explanation of the installation procedure.\r
-\r
-The @file{README} file should also refer to the file which contains the\r
-copying conditions. The GNU GPL, if used, should be in a file called\r
-@file{COPYING}. If the GNU LGPL is used, it should be in a file called\r
-@file{COPYING.LIB}.\r
-\r
-Naturally, all the source files must be in the distribution. It is okay\r
-to include non-source files in the distribution, provided they are\r
-up-to-date and machine-independent, so that building the distribution\r
-normally will never modify them. We commonly include non-source files\r
-produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid\r
-unnecessary dependencies between our distributions, so that users can\r
-install whichever packages they want to install.\r
-\r
-Non-source files that might actually be modified by building and\r
-installing the program should @strong{never} be included in the\r
-distribution. So if you do distribute non-source files, always make\r
-sure they are up to date when you make a new distribution.\r
-\r
-Make sure that the directory into which the distribution unpacks (as\r
-well as any subdirectories) are all world-writable (octal mode 777).\r
-This is so that old versions of @code{tar} which preserve the\r
-ownership and permissions of the files from the tar archive will be\r
-able to extract all the files even if the user is unprivileged.\r
-\r
-Make sure that all the files in the distribution are world-readable.\r
-\r
-Make sure that no file name in the distribution is more than 14\r
-characters long. Likewise, no file created by building the program\r
-should have a name longer than 14 characters. The reason for this is\r
-that some systems adhere to a foolish interpretation of the @sc{posix}\r
-standard, and refuse to open a longer name, rather than truncating as\r
-they did in the past.\r
-\r
-Don't include any symbolic links in the distribution itself. If the tar\r
-file contains symbolic links, then people cannot even unpack it on\r
-systems that don't support symbolic links. Also, don't use multiple\r
-names for one file in different directories, because certain file\r
-systems cannot handle this and that prevents unpacking the\r
-distribution.\r
-\r
-Try to make sure that all the file names will be unique on MS-DOS. A\r
-name on MS-DOS consists of up to 8 characters, optionally followed by a\r
-period and up to three characters. MS-DOS will truncate extra\r
-characters both before and after the period. Thus,\r
-@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they\r
-are truncated to @file{foobarha.c} and @file{foobarha.o}, which are\r
-distinct.\r
-\r
-Include in your distribution a copy of the @file{texinfo.tex} you used\r
-to test print any @file{*.texinfo} or @file{*.texi} files.\r
-\r
-Likewise, if your program uses small GNU software packages like regex,\r
-getopt, obstack, or termcap, include them in the distribution file.\r
-Leaving them out would make the distribution file a little smaller at\r
-the expense of possible inconvenience to a user who doesn't know what\r
-other files to get.\r
-\r
-@node References\r
-@chapter References to Non-Free Software and Documentation\r
-\r
-A GNU program should not recommend use of any non-free program. We\r
-can't stop some people from writing proprietary programs, or stop other\r
-people from using them. But we can and should avoid helping to\r
-advertise them to new customers.\r
-\r
-Sometimes it is important to mention how to build your package on top of\r
-some non-free operating system or other non-free base package. In such\r
-cases, please mention the name of the non-free package or system in the\r
-briefest possible way. Don't include any references for where to find\r
-more information about the proprietary program. The goal should be that\r
-people already using the proprietary program will get the advice they\r
-need about how to use your free program, while people who don't already\r
-use the proprietary program will not see anything to encourage them to\r
-take an interest in it.\r
-\r
-Likewise, a GNU package should not refer the user to any non-free\r
-documentation for free software. The need for free documentation to go\r
-with free software is now a major focus of the GNU project; to show that\r
-we are serious about the need for free documentation, we must not\r
-undermine our position by recommending use of documentation that isn't\r
-free.\r
-\r
-@node Index\r
-@unnumbered Index\r
-@printindex cp\r
-\r
-@contents\r
-\r
-@bye\r
-Local variables:\r
-update-date-leading-regexp: "@c This date is automagically updated when you save this file:\n@set lastupdate "\r
-update-date-trailing-regexp: ""\r
-eval: (load "/gd/gnuorg/update-date.el")\r
-eval: (add-hook 'write-file-hooks 'update-date)\r
-End:\r
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename standards.info
+@settitle GNU Coding Standards
+@c This date is automagically updated when you save this file:
+@set lastupdate June 27, 2000
+@c %**end of header
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@c @setchapternewpage odd
+@setchapternewpage off
+
+@c This is used by a cross ref in make-stds.texi
+@set CODESTD 1
+@iftex
+@set CHAPTER chapter
+@end iftex
+@ifinfo
+@set CHAPTER node
+@end ifinfo
+
+@ifinfo
+GNU Coding Standards
+Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 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.
+
+@ignore
+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).
+@end ignore
+
+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 Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998 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 Free Software Foundation.
+@end titlepage
+
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top Version
+
+Last updated @value{lastupdate}.
+@end ifinfo
+
+@menu
+* Preface:: About the GNU Coding Standards
+* Legal Issues:: Keeping Free Software Free
+* Design Advice:: General Program Design
+* Program Behavior:: Program Behavior for All Programs
+* Writing C:: Making The Best Use of C
+* Documentation:: Documenting Programs
+* Managing Releases:: The Release Process
+* References:: References to Non-Free Software or Documentation
+* Index::
+@end menu
+
+@node Preface
+@chapter About the GNU Coding Standards
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to writing portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+Corrections or suggestions for this document should be sent to
+@email{gnu@@gnu.org}. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
+If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version. You can ftp the GNU Coding
+Standards from any GNU FTP host in the directory
+@file{/pub/gnu/standards/}. The GNU Coding Standards are available
+there in several different formats: @file{standards.text},
+@file{standards.texi}, @file{standards.info}, and @file{standards.dvi}.
+The GNU Coding Standards are also available on the GNU World Wide Web
+server: @uref{http://www.gnu.org/prep/standards_toc.html}.
+
+@node Legal Issues
+@chapter Keeping Free Software Free
+
+This @value{CHAPTER} discusses how you can make sure that GNU software
+avoids legal difficulties, and other related issues.
+
+@menu
+* Reading Non-Free Code:: Referring to Proprietary Programs
+* Contributions:: Accepting Contributions
+* Trademarks:: How We Deal with Trademark Issues
+@end menu
+
+@node Reading Non-Free Code
+@section Referring to Proprietary Programs
+
+Don't in any circumstances refer to Unix source code for or during
+your work on GNU! (Or to any other proprietary programs.)
+
+If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different. You could keep the entire input file in core and scan it
+there instead of using stdio. Use a smarter algorithm discovered more
+recently than the Unix program. Eliminate use of temporary files. Do
+it in one pass instead of two (we did this in the assembler).
+
+Or, on the contrary, emphasize simplicity instead of speed. For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+Or go for generality. For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead. Make sure your program handles NULs and
+other funny characters in the input files. Add a programming language
+for extensibility and write part of the program in that language.
+
+Or turn some parts of the program into independently usable libraries.
+Or use a simple garbage collector instead of tracking precisely when
+to free memory, or use a new GNU facility such as obstacks.
+
+@node Contributions
+@section Accepting Contributions
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it---just as we asked you to
+sign papers initially. @emph{Each} person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers. Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+This applies both before you release the program and afterward. If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+This also applies to comments and documentation files. For copyright
+law, comments and code are just text. Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+We know it is frustrating to ask for legal papers; it's frustrating for
+us as well. But if you don't wait, you are going out on a limb---for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes. Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use. For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+The very worst thing is if you forget to tell us about the other
+contributor. We could be very embarrassed in court some day as a
+result.
+
+We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
+@node Trademarks
+@section Trademarks
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them. There is no legal requirement for them.
+
+What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities. For example, since ``Objective C'' is
+(or at least was) a trademark, we made sure to say that we provide a
+``compiler for the Objective C language'' rather than an ``Objective C
+compiler''. The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using ``Objective C'' as a label for the compiler rather than for the
+language.
+
+@node Design Advice
+@chapter General Program Design
+
+This @value{CHAPTER} discusses some of the issues you should take into
+account when designing your program.
+
+@c Standard or ANSI C
+@c
+@c In 1989 the American National Standards Institute (ANSI) standardized
+@c C as standard X3.159-1989. In December of that year the
+@c International Standards Organization ISO adopted the ANSI C standard
+@c making minor changes. In 1990 ANSI then re-adopted ISO standard
+@c C. This version of C is known as either ANSI C or Standard C.
+
+@menu
+* Source Language:: Which languges to use.
+* Compatibility:: Compatibility with other implementations
+* Using Extensions:: Using non-standard features
+* Standard C:: Using Standard (ANSI 1989) C features
+@end menu
+
+@node Source Language
+@section Which Languages to Use
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language is like
+using a non-standard feature: it will cause trouble for users. Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program. For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+So in general it is much better to use use C, rather than the
+comparable alternatives.
+
+But there are two exceptions to that conclusion:
+
+@itemize @bullet
+@item
+It is no problem to use another language to write a tool specifically
+intended for use with that language. That is because the only people
+who want to build the tool will be those who have installed the other
+language anyway.
+
+@item
+If an application is of interest only to a narrow part of the community,
+then the question of which language it is written in has less effect on
+other people, so you may as well please yourself.
+@end itemize
+
+Many programs are designed to be extensible: they include an interpreter
+for a language that is higher level than C. Often much of the program
+is written in that language, too. The Emacs editor pioneered this
+technique.
+
+The standard extensibility interpreter for GNU software is GUILE, which
+implements the language Scheme (an especially clean and simple dialect
+of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject
+programs written in other ``scripting languages'' such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+@node Compatibility
+@section Compatibility with Other Implementations
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with 1989 Standard C if 1989 Standard C specifies their
+behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
+their behavior.
+
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+1989 Standard C and @sc{posix} prohibit many kinds of extensions. Feel
+free to make the extensions anyway, and include a @samp{--ansi},
+@samp{--posix}, or @samp{--compatible} option to turn them off.
+However, if the extension has a significant chance of breaking any real
+programs or scripts, then it is not really upward compatible. So you
+should try to redesign its interface to make it upward compatible.
+
+Many GNU programs suppress extensions that conflict with @sc{posix} if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better. (For example,
+@code{vi} is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free @code{vi} clone, so we offer it.)
+
+Additional useful features are welcome regardless of whether
+there is any precedent for them.
+
+@node Using Extensions
+@section Using Non-standard Features
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities. Whether to use these
+extensions in implementing your program is a difficult question.
+
+On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program
+unless the other GNU tools are available. This might cause the
+program to work on fewer kinds of machines.
+
+With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a ``keyword'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems. Using GNU extensions in
+such programs would make many users unhappy, so we don't do that.
+
+Another exception is for programs that are used as part of compilation:
+anything that must be compiled with other compilers in order to
+bootstrap the GNU compilation facilities. If these require the GNU
+compiler, then no one can compile them without having them installed
+already. That would be extremely troublesome in certain cases.
+
+@node Standard C
+@section 1989 Standard C and Pre-Standard C
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs. There is one exception: do not ever use the
+``trigraph'' feature of 1989 Standard C.
+
+However, it is easy to support pre-standard compilers in most programs,
+so if you know how to do that, feel free. If a program you are
+maintaining has such support, you should try to keep it working.
+
+To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+@example
+int
+foo (int x, int y)
+@dots{}
+@end example
+
+@noindent
+write the definition in pre-standard style like this,
+
+@example
+int
+foo (x, y)
+ int x, y;
+@dots{}
+@end example
+
+@noindent
+and use a separate declaration to specify the argument prototype:
+
+@example
+int foo (int, int);
+@end example
+
+You need such a declaration anyway, in a header file, to get the benefit
+of prototypes in all the files where the function is called. And once
+you have the declaration, you normally lose nothing by writing the
+function definition in the pre-standard style.
+
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+
+There are a few special cases where this technique is hard to use. For
+example, if a function argument needs to hold the system type
+@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+@code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines. There
+is no type you can safely use on all machines in a non-standard
+definition. The only way to support non-standard C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly. This may not be worth the trouble.
+
+In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+@example
+/* Declare the prototype for a general external function. */
+#if defined (__STDC__) || defined (WINDOWSNT)
+#define P_(proto) proto
+#else
+#define P_(proto) ()
+#endif
+@end example
+
+@node Program Behavior
+@chapter Program Behavior for All Programs
+
+This @value{CHAPTER} describes conventions for writing robust
+software. It also describes general standards for error messages, the
+command line interface, and how libraries should behave.
+
+@menu
+* Semantics:: Writing robust programs
+* Libraries:: Library behavior
+* Errors:: Formatting error messages
+* User Interfaces:: Standards about interfaces generally
+* Graphical Interfaces:: Standards for graphical interfaces
+* Command-Line Interfaces:: Standards for command line interfaces
+* Option Table:: Table of long options.
+* Memory Usage:: When and how to care about memory needs
+@end menu
+
+@node Semantics
+@section Writing Robust Programs
+
+Avoid arbitrary limits on the length or number of @emph{any} data
+structure, including file names, lines, files, and symbols, by allocating
+all data structures dynamically. In most Unix utilities, ``long lines
+are silently truncated''. This is not acceptable in a GNU utility.
+
+Utilities reading files should not drop NUL characters, or any other
+nonprinting characters @emph{including those with codes above 0177}.
+The only sensible exceptions would be utilities specifically intended
+for interface to certain types of terminals or printers
+that can't handle those characters.
+Whenever possible, try to make programs work properly with
+sequences of bytes that represent multibyte characters, using encodings
+such as UTF-8 and others.
+
+Check every system call for an error return, unless you know you wish to
+ignore errors. Include the system error text (from @code{perror} or
+equivalent) in @emph{every} error message resulting from a failing
+system call, as well as the name of the file if any and the name of the
+utility. Just ``cannot open foo.c'' or ``stat failed'' is not
+sufficient.
+
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero. Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+@code{realloc} may get a different block if you ask for less space.
+
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero. GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged. Feel free to assume the bug is fixed. If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+
+You must expect @code{free} to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop. This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+When static storage is to be written in during program execution, use
+explicit C code to initialize it. Reserve C initialized declarations
+for data that will not be changed.
+@c ADR: why?
+
+Try to avoid low-level interfaces to obscure Unix data structures (such
+as file directories, utmp, or the layout of kernel memory), since these
+are less likely to work compatibly. If you need to find all the files
+in a directory, use @code{readdir} or some other high-level interface.
+These are supported compatibly by GNU.
+
+The preferred signal handling facilities are the BSD variant of
+@code{signal}, and the @sc{posix} @code{sigaction} function; the
+alternative USG @code{signal} interface is an inferior design.
+
+Nowadays, using the @sc{posix} signal functions may be the easiest way
+to make a program portable. If you use @code{signal}, then on GNU/Linux
+systems running GNU libc version 1, you should include
+@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
+behavior. It is up to you whether to support systems where
+@code{signal} has only the USG behavior, or give up on them.
+
+In error checks that detect ``impossible'' conditions, just abort.
+There is usually no point in printing any message. These checks
+indicate the existence of bugs. Whoever wants to fix the bugs will have
+to read the source code and run a debugger. So explain the problem with
+comments in the source. The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+Do not use a count of errors as the exit status for a program.
+@emph{That does not work}, because exit status values are limited to 8
+bits (0 through 255). A single run of the program might have 256
+errors; if you try to return 256 as the exit status, the parent process
+will see 0 as the status, and it will appear that the program succeeded.
+
+If you make temporary files, check the @code{TMPDIR} environment
+variable; if that variable is defined, use the specified directory
+instead of @file{/tmp}.
+
+In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories. In C, you can
+avoid this problem by creating temporary files in this manner:
+
+@example
+fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+@end example
+
+@noindent
+or by using the @code{mkstemps} function from libiberty.
+
+In bash, use @code{set -C} to avoid this problem.
+
+@node Libraries
+@section Library Behavior
+
+Try to make library functions reentrant. If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of @code{malloc} itself.
+
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix. In addition, there should only be one of these in any given
+library member. This usually means putting each one in a separate
+source file.
+
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}. They should also contain
+the chosen name prefix for the library, to prevent collisions with
+other libraries. These can go in the same files with user entry
+points if you like.
+
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+@node Errors
+@section Formatting Error Messages
+
+Error messages from compilers should look like this:
+
+@example
+@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+If you want to mention the column number, use this format:
+
+@example
+@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+
+@noindent
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line. (Both
+of these conventions are chosen for compatibility.) Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
+Error messages from other noninteractive programs should look like this:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+when there is an appropriate source file, or like this:
+
+@example
+@var{program}: @var{message}
+@end example
+
+@noindent
+when there is no relevant source file.
+
+If you want to mention the column number, use this format:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message. The place to indicate which program is running is in the
+prompt or with the screen layout. (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or file name. Also, it should not end
+with a period.
+
+Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter. But they should not
+end with a period.
+
+@node User Interfaces
+@section Standards for Interfaces Generally
+
+Please don't make the behavior of a utility depend on the name used
+to invoke it. It is useful sometimes to make a link to a utility
+with a different name, and that should not change what it does.
+
+Instead, use a run time option or a compilation switch or both
+to select among the alternate behaviors.
+
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then. (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device. It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
+@node Graphical Interfaces
+@section Standards for Graphical Interfaces
+
+When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+``displaying jpeg images while in console mode'').
+
+In addition, please provide a command-line interface to control the
+functionality. (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.) This is
+so that the same jobs can be done from scripts.
+
+Please also consider providing a CORBA interface (for use from GNOME), a
+library interface (for use from C), and perhaps a keyboard-driven
+console interface (for use by users from console mode). Once you are
+doing the work to provide the functionality and the graphical interface,
+these won't be much extra work.
+
+@node Command-Line Interfaces
+@section Standards for Command Line Interfaces
+
+It is a good idea to follow the @sc{posix} guidelines for the
+command-line options of a program. The easiest way to do this is to use
+@code{getopt} to parse them. Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used. This is not what @sc{posix}
+specifies; it is a GNU extension.
+
+Please define long-named options that are equivalent to the
+single-letter Unix-style options. We hope to make GNU more user
+friendly this way. This is easy to do with the GNU function
+@code{getopt_long}.
+
+One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}. To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program (@pxref{Option Table}).
+
+It is usually a good idea for file names given as ordinary arguments to
+be input files only; any output files would be specified using options
+(preferably @samp{-o} or @samp{--output}). Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it. This will lead to more consistency
+among GNU utilities, and fewer idiosyncracies for users to remember.
+
+All programs should support two standard options: @samp{--version}
+and @samp{--help}.
+
+@table @code
+@item --version
+This option should direct the program to print information about its name,
+version, origin and legal status, all on standard output, and then exit
+successfully. Other options and arguments should be ignored once this
+is seen, and the program should not perform its normal function.
+
+The first line is meant to be easy for a program to parse; the version
+number proper starts after the last space. In addition, it contains
+the canonical name for this program, in this format:
+
+@example
+GNU Emacs 19.30
+@end example
+
+@noindent
+The program's name should be a constant string; @emph{don't} compute it
+from @code{argv[0]}. The idea is to state the standard or canonical
+name for the program, not its file name. There are other ways to find
+out the precise file name where a command is found in @code{PATH}.
+
+If the program is a subsidiary part of a larger package, mention the
+package name in parentheses, like this:
+
+@example
+emacsserver (GNU Emacs) 19.30
+@end example
+
+@noindent
+If the package has a version number which is different from this
+program's version number, you can mention the package version number
+just before the close-parenthesis.
+
+If you @strong{need} to mention the version numbers of libraries which
+are distributed separately from the package which contains this program,
+you can do so by printing an additional line of version info for each
+library you want to mention. Use the same format for these lines as for
+the first line.
+
+Please do not mention all of the libraries that the program uses ``just
+for completeness''---that would produce a lot of unhelpful clutter.
+Please mention library version numbers only if you find in practice that
+they are very important to you in debugging.
+
+The following line, after the version number line or lines, should be a
+copyright notice. If more than one copyright notice is called for, put
+each on a separate line.
+
+Next should follow a brief statement that the program is free software,
+and that users are free to copy and change it on certain conditions. If
+the program is covered by the GNU GPL, say so here. Also mention that
+there is no warranty, to the extent permitted by law.
+
+It is ok to finish the output with a list of the major authors of the
+program, as a way of giving credit.
+
+Here's an example of output that follows these rules:
+
+@smallexample
+GNU Emacs 19.34.5
+Copyright (C) 1996 Free Software Foundation, Inc.
+GNU Emacs comes with NO WARRANTY,
+to the extent permitted by law.
+You may redistribute copies of GNU Emacs
+under the terms of the GNU General Public License.
+For more information about these matters,
+see the files named COPYING.
+@end smallexample
+
+You should adapt this to your program, of course, filling in the proper
+year, copyright holder, name of program, and the references to
+distribution terms, and changing the rest of the wording as necessary.
+
+This copyright notice only needs to mention the most recent year in
+which changes were made---there's no need to list the years for previous
+versions' changes. You don't have to mention the name of the program in
+these notices, if that is inconvenient, since it appeared in the first
+line.
+
+@item --help
+This option should output brief documentation for how to invoke the
+program, on standard output, then exit successfully. Other options and
+arguments should be ignored once this is seen, and the program should
+not perform its normal function.
+
+Near the end of the @samp{--help} option's output there should be a line
+that says where to mail bug reports. It should have this format:
+
+@example
+Report bugs to @var{mailing-address}.
+@end example
+@end table
+
+@node Option Table
+@section Table of Long Options
+
+Here is a table of long options used by GNU programs. It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with. If you use names not already in the table,
+please send @email{gnu@@gnu.org} a list of them, with their
+meanings, so we can update the table.
+
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period. --friedman
+
+@table @samp
+@item after-date
+@samp{-N} in @code{tar}.
+
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+@item all-text
+@samp{-a} in @code{diff}.
+
+@item almost-all
+@samp{-A} in @code{ls}.
+
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+
+@item archive
+@samp{-a} in @code{cp}.
+
+@item archive-name
+@samp{-n} in @code{shar}.
+
+@item arglength
+@samp{-l} in @code{m4}.
+
+@item ascii
+@samp{-a} in @code{diff}.
+
+@item assign
+@samp{-v} in @code{gawk}.
+
+@item assume-new
+@samp{-W} in Make.
+
+@item assume-old
+@samp{-o} in Make.
+
+@item auto-check
+@samp{-a} in @code{recode}.
+
+@item auto-pager
+@samp{-a} in @code{wdiff}.
+
+@item auto-reference
+@samp{-A} in @code{ptx}.
+
+@item avoid-wraps
+@samp{-n} in @code{wdiff}.
+
+@item background
+For server programs, run in the background.
+
+@item backward-search
+@samp{-B} in @code{ctags}.
+
+@item basename
+@samp{-f} in @code{shar}.
+
+@item batch
+Used in GDB.
+
+@item baud
+Used in GDB.
+
+@item before
+@samp{-b} in @code{tac}.
+
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+
+@item bits-per-code
+@samp{-b} in @code{shar}.
+
+@item block-size
+Used in @code{cpio} and @code{tar}.
+
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+
+@item break-file
+@samp{-b} in @code{ptx}.
+
+@item brief
+Used in various programs to make output shorter.
+
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+@item c@t{++}
+@samp{-C} in @code{etags}.
+
+@item catenate
+@samp{-A} in @code{tar}.
+
+@item cd
+Used in various programs to specify the directory to use.
+
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+
+@item classify
+@samp{-F} in @code{ls}.
+
+@item colons
+@samp{-c} in @code{recode}.
+
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+
+@item compare
+@samp{-d} in @code{tar}.
+
+@item compat
+Used in @code{gawk}.
+
+@item compress
+@samp{-Z} in @code{tar} and @code{shar}.
+
+@item concatenate
+@samp{-A} in @code{tar}.
+
+@item confirmation
+@samp{-w} in @code{tar}.
+
+@item context
+Used in @code{diff}.
+
+@item copyleft
+@samp{-W copyleft} in @code{gawk}.
+
+@item copyright
+@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
+@samp{-W copyright} in @code{gawk}.
+
+@item core
+Used in GDB.
+
+@item count
+@samp{-q} in @code{who}.
+
+@item count-links
+@samp{-l} in @code{du}.
+
+@item create
+Used in @code{tar} and @code{cpio}.
+
+@item cut-mark
+@samp{-c} in @code{shar}.
+
+@item cxref
+@samp{-x} in @code{ctags}.
+
+@item date
+@samp{-d} in @code{touch}.
+
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+
+@item define
+@samp{-D} in @code{m4}.
+
+@item defines
+@samp{-d} in Bison and @code{ctags}.
+
+@item delete
+@samp{-D} in @code{tar}.
+
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+
+@item dereference-args
+@samp{-D} in @code{du}.
+
+@item device
+Specify an I/O device (special file name).
+
+@item diacritics
+@samp{-d} in @code{recode}.
+
+@item dictionary-order
+@samp{-d} in @code{look}.
+
+@item diff
+@samp{-d} in @code{tar}.
+
+@item digits
+@samp{-n} in @code{csplit}.
+
+@item directory
+Specify the directory to use, in various programs. In @code{ls}, it
+means to show directories themselves rather than their contents. In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+@item discard-all
+@samp{-x} in @code{strip}.
+
+@item discard-locals
+@samp{-X} in @code{strip}.
+
+@item dry-run
+@samp{-n} in Make.
+
+@item ed
+@samp{-e} in @code{diff}.
+
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+
+@item end-delete
+@samp{-x} in @code{wdiff}.
+
+@item end-insert
+@samp{-z} in @code{wdiff}.
+
+@item entire-new-file
+@samp{-N} in @code{diff}.
+
+@item environment-overrides
+@samp{-e} in Make.
+
+@item eof
+@samp{-e} in @code{xargs}.
+
+@item epoch
+Used in GDB.
+
+@item error-limit
+Used in @code{makeinfo}.
+
+@item error-output
+@samp{-o} in @code{m4}.
+
+@item escape
+@samp{-b} in @code{ls}.
+
+@item exclude-from
+@samp{-X} in @code{tar}.
+
+@item exec
+Used in GDB.
+
+@item exit
+@samp{-x} in @code{xargs}.
+
+@item exit-0
+@samp{-e} in @code{unshar}.
+
+@item expand-tabs
+@samp{-t} in @code{diff}.
+
+@item expression
+@samp{-e} in @code{sed}.
+
+@item extern-only
+@samp{-g} in @code{nm}.
+
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+
+@item faces
+@samp{-f} in @code{finger}.
+
+@item fast
+@samp{-f} in @code{su}.
+
+@item fatal-warnings
+@samp{-E} in @code{m4}.
+
+@item file
+@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+
+@item field-separator
+@samp{-F} in @code{gawk}.
+
+@item file-prefix
+@samp{-b} in Bison.
+
+@item file-type
+@samp{-F} in @code{ls}.
+
+@item files-from
+@samp{-T} in @code{tar}.
+
+@item fill-column
+Used in @code{makeinfo}.
+
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+
+@item fixed-output-files
+@samp{-y} in Bison.
+
+@item follow
+@samp{-f} in @code{tail}.
+
+@item footnote-style
+Used in @code{makeinfo}.
+
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+@item force-prefix
+@samp{-F} in @code{shar}.
+
+@item foreground
+For server programs, run in the foreground;
+in other words, don't do anything special to run the server
+in the background.
+
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+@item freeze-state
+@samp{-F} in @code{m4}.
+
+@item fullname
+Used in GDB.
+
+@item gap-size
+@samp{-g} in @code{ptx}.
+
+@item get
+@samp{-x} in @code{tar}.
+
+@item graphic
+@samp{-i} in @code{ul}.
+
+@item graphics
+@samp{-g} in @code{recode}.
+
+@item group
+@samp{-g} in @code{install}.
+
+@item gzip
+@samp{-z} in @code{tar} and @code{shar}.
+
+@item hashsize
+@samp{-H} in @code{m4}.
+
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+
+@item heading
+@samp{-H} in @code{who}.
+
+@item help
+Used to ask for brief usage information.
+
+@item here-delimiter
+@samp{-d} in @code{shar}.
+
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+
+@item html
+In @code{makeinfo}, output HTML.
+
+@item idle
+@samp{-u} in @code{who}.
+
+@item ifdef
+@samp{-D} in @code{diff}.
+
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+
+@item ignore-backups
+@samp{-B} in @code{ls}.
+
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff} and @code{wdiff}.
+
+@item ignore-errors
+@samp{-i} in Make.
+
+@item ignore-file
+@samp{-i} in @code{ptx}.
+
+@item ignore-indentation
+@samp{-I} in @code{etags}.
+
+@item ignore-init-file
+@samp{-f} in Oleo.
+
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+
+@item include-dir
+@samp{-I} in Make.
+
+@item incremental
+@samp{-G} in @code{tar}.
+
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+@item init-file
+In some programs, specify the name of the file to read as the user's
+init file.
+
+@item initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item intermix-type
+@samp{-p} in @code{shar}.
+
+@item iso-8601
+Used in @code{date}
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item language
+@samp{-l} in @code{etags}.
+
+@item less-mode
+@samp{-l} in @code{wdiff}.
+
+@item level-for-gzip
+@samp{-g} in @code{shar}.
+
+@item line-bytes
+@samp{-C} in @code{split}.
+
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+@item link
+@samp{-l} in @code{cpio}.
+
+@item lint
+@itemx lint-old
+Used in @code{gawk}.
+
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+
+@item list
+@samp{-t} in @code{tar}.
+
+@item literal
+@samp{-N} in @code{ls}.
+
+@item load-average
+@samp{-l} in Make.
+
+@item login
+Used in @code{su}.
+
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do, and tell @email{gnu@@gnu.org}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item nesting-limit
+@samp{-L} in @code{m4}.
+
+@item net-headers
+@samp{-a} in @code{shar}.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-character-count
+@samp{-w} in @code{shar}.
+
+@item no-check-existing
+@samp{-x} in @code{shar}.
+
+@item no-common
+@samp{-3} in @code{wdiff}.
+
+@item no-create
+@samp{-c} in @code{touch}.
+
+@item no-defines
+@samp{-D} in @code{etags}.
+
+@item no-deleted
+@samp{-1} in @code{wdiff}.
+
+@item no-dereference
+@samp{-d} in @code{cp}.
+
+@item no-inserted
+@samp{-2} in @code{wdiff}.
+
+@item no-keep-going
+@samp{-S} in Make.
+
+@item no-lines
+@samp{-l} in Bison.
+
+@item no-piping
+@samp{-P} in @code{shar}.
+
+@item no-prof
+@samp{-e} in @code{gprof}.
+
+@item no-regex
+@samp{-R} in @code{etags}.
+
+@item no-sort
+@samp{-p} in @code{nm}.
+
+@item no-split
+Used in @code{makeinfo}.
+
+@item no-static
+@samp{-a} in @code{gprof}.
+
+@item no-time
+@samp{-E} in @code{gprof}.
+
+@item no-timestamp
+@samp{-m} in @code{shar}.
+
+@item no-validate
+Used in @code{makeinfo}.
+
+@item no-wait
+Used in @code{emacsclient}.
+
+@item no-warn
+Used in various programs to inhibit warnings.
+
+@item node
+@samp{-n} in @code{info}.
+
+@item nodename
+@samp{-n} in @code{uname}.
+
+@item nonmatching
+@samp{-f} in @code{cpio}.
+
+@item nstuff
+@samp{-n} in @code{objdump}.
+
+@item null
+@samp{-0} in @code{xargs}.
+
+@item number
+@samp{-n} in @code{cat}.
+
+@item number-nonblank
+@samp{-b} in @code{cat}.
+
+@item numeric-sort
+@samp{-n} in @code{nm}.
+
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+
+@item nx
+Used in GDB.
+
+@item old-archive
+@samp{-o} in @code{tar}.
+
+@item old-file
+@samp{-o} in Make.
+
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+@item only-file
+@samp{-o} in @code{ptx}.
+
+@item only-prof
+@samp{-f} in @code{gprof}.
+
+@item only-time
+@samp{-F} in @code{gprof}.
+
+@item options
+@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
+@code{fdmountd}, and @code{fdumount}.
+
+@item output
+In various programs, specify the output file name.
+
+@item output-prefix
+@samp{-o} in @code{shar}.
+
+@item override
+@samp{-o} in @code{rm}.
+
+@item overwrite
+@samp{-c} in @code{unshar}.
+
+@item owner
+@samp{-o} in @code{install}.
+
+@item paginate
+@samp{-l} in @code{diff}.
+
+@item paragraph-indent
+Used in @code{makeinfo}.
+
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+
+@item pass-all
+@samp{-p} in @code{ul}.
+
+@item pass-through
+@samp{-p} in @code{cpio}.
+
+@item port
+@samp{-P} in @code{finger}.
+
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+
+@item posix
+Used in @code{gawk}.
+
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+
+@item prefix
+@samp{-f} in @code{csplit}.
+
+@item preserve
+Used in @code{tar} and @code{cp}.
+
+@item preserve-environment
+@samp{-p} in @code{su}.
+
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+
+@item preserve-order
+@samp{-s} in @code{tar}.
+
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+
+@item print
+@samp{-l} in @code{diff}.
+
+@item print-chars
+@samp{-L} in @code{cmp}.
+
+@item print-data-base
+@samp{-p} in Make.
+
+@item print-directory
+@samp{-w} in Make.
+
+@item print-file-name
+@samp{-o} in @code{nm}.
+
+@item print-symdefs
+@samp{-s} in @code{nm}.
+
+@item printer
+@samp{-p} in @code{wdiff}.
+
+@item prompt
+@samp{-p} in @code{ed}.
+
+@item proxy
+Specify an HTTP proxy.
+
+@item query-user
+@samp{-X} in @code{shar}.
+
+@item question
+@samp{-q} in Make.
+
+@item quiet
+Used in many programs to inhibit the usual output. @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+@item quiet-unshar
+@samp{-Q} in @code{shar}
+
+@item quote-name
+@samp{-Q} in @code{ls}.
+
+@item rcs
+@samp{-n} in @code{diff}.
+
+@item re-interval
+Used in @code{gawk}.
+
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+
+@item readnow
+Used in GDB.
+
+@item recon
+@samp{-n} in Make.
+
+@item record-number
+@samp{-R} in @code{tar}.
+
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+@item reference-limit
+Used in @code{makeinfo}.
+
+@item references
+@samp{-r} in @code{ptx}.
+
+@item regex
+@samp{-r} in @code{tac} and @code{etags}.
+
+@item release
+@samp{-r} in @code{uname}.
+
+@item reload-state
+@samp{-R} in @code{m4}.
+
+@item relocation
+@samp{-r} in @code{objdump}.
+
+@item rename
+@samp{-r} in @code{cpio}.
+
+@item replace
+@samp{-i} in @code{xargs}.
+
+@item report-identical-files
+@samp{-s} in @code{diff}.
+
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+
+@item reversed-ed
+@samp{-f} in @code{diff}.
+
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+
+@item same-order
+@samp{-s} in @code{tar}.
+
+@item same-permissions
+@samp{-p} in @code{tar}.
+
+@item save
+@samp{-g} in @code{stty}.
+
+@item se
+Used in GDB.
+
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+
+@item separate-dirs
+@samp{-S} in @code{du}.
+
+@item separator
+@samp{-s} in @code{tac}.
+
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+@item shell
+@samp{-s} in @code{su}.
+
+@item show-all
+@samp{-A} in @code{cat}.
+
+@item show-c-function
+@samp{-p} in @code{diff}.
+
+@item show-ends
+@samp{-E} in @code{cat}.
+
+@item show-function-line
+@samp{-F} in @code{diff}.
+
+@item show-tabs
+@samp{-T} in @code{cat}.
+
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+
+@item size
+@samp{-s} in @code{ls}.
+
+@item socket
+Specify a file descriptor for a network server to use for its socket,
+instead of opening and binding a new socket. This provides a way to
+run, in a nonpriveledged process, a server that normally needs a
+reserved port number.
+
+@item sort
+Used in @code{ls}.
+
+@item source
+@samp{-W source} in @code{gawk}.
+
+@item sparse
+@samp{-S} in @code{tar}.
+
+@item speed-large-files
+@samp{-H} in @code{diff}.
+
+@item split-at
+@samp{-E} in @code{unshar}.
+
+@item split-size-limit
+@samp{-L} in @code{shar}.
+
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+
+@item start-delete
+@samp{-w} in @code{wdiff}.
+
+@item start-insert
+@samp{-y} in @code{wdiff}.
+
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+@item statistics
+@samp{-s} in @code{wdiff}.
+
+@item stdin-file-list
+@samp{-S} in @code{shar}.
+
+@item stop
+@samp{-S} in Make.
+
+@item strict
+@samp{-s} in @code{recode}.
+
+@item strip
+@samp{-s} in @code{install}.
+
+@item strip-all
+@samp{-s} in @code{strip}.
+
+@item strip-debug
+@samp{-S} in @code{strip}.
+
+@item submitter
+@samp{-s} in @code{shar}.
+
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+@item suffix-format
+@samp{-b} in @code{csplit}.
+
+@item sum
+@samp{-s} in @code{gprof}.
+
+@item summarize
+@samp{-s} in @code{du}.
+
+@item symbolic
+@samp{-s} in @code{ln}.
+
+@item symbols
+Used in GDB and @code{objdump}.
+
+@item synclines
+@samp{-s} in @code{m4}.
+
+@item sysname
+@samp{-s} in @code{uname}.
+
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+
+@item tabsize
+@samp{-T} in @code{ls}.
+
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+@samp{-t} in @code{wdiff}.
+
+@item text
+@samp{-a} in @code{diff}.
+
+@item text-files
+@samp{-T} in @code{shar}.
+
+@item time
+Used in @code{ls} and @code{touch}.
+
+@item timeout
+Specify how long to wait before giving up on some operation.
+
+@item to-stdout
+@samp{-O} in @code{tar}.
+
+@item total
+@samp{-c} in @code{du}.
+
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+
+@item trace
+@samp{-t} in @code{m4}.
+
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-W traditional} in @code{gawk};
+@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
+
+@item tty
+Used in GDB.
+
+@item typedefs
+@samp{-t} in @code{ctags}.
+
+@item typedefs-and-c++
+@samp{-T} in @code{ctags}.
+
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+
+@item uncompress
+@samp{-z} in @code{tar}.
+
+@item unconditional
+@samp{-u} in @code{cpio}.
+
+@item undefine
+@samp{-U} in @code{m4}.
+
+@item undefined-only
+@samp{-u} in @code{nm}.
+
+@item update
+@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
+
+@item usage
+Used in @code{gawk}; same as @samp{--help}.
+
+@item uuencode
+@samp{-B} in @code{shar}.
+
+@item vanilla-operation
+@samp{-V} in @code{shar}.
+
+@item verbose
+Print more information about progress. Many programs support this.
+
+@item verify
+@samp{-W} in @code{tar}.
+
+@item version
+Print the version number.
+
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+@item vgrind
+@samp{-v} in @code{ctags}.
+
+@item volume
+@samp{-V} in @code{tar}.
+
+@item what-if
+@samp{-W} in Make.
+
+@item whole-size-limit
+@samp{-l} in @code{shar}.
+
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+
+@item word-regexp
+@samp{-W} in @code{ptx}.
+
+@item writable
+@samp{-T} in @code{who}.
+
+@item zeros
+@samp{-z} in @code{gprof}.
+@end table
+
+@node Memory Usage
+@section Memory Usage
+
+If it typically uses just a few meg of memory, don't bother making any
+effort to reduce memory usage. For example, if it is impractical for
+other reasons to operate on files more than a few meg long, it is
+reasonable to read entire input files into core to operate on them.
+
+However, for programs such as @code{cat} or @code{tail}, that can
+usefully operate on very large files, it is important to avoid using a
+technique that would artificially limit the size of files it can handle.
+If a program works by lines and could be applied to arbitrary
+user-supplied input files, it should keep only a line in memory, because
+this is not very hard and users will want to be able to operate on input
+files that are bigger than will fit in core all at once.
+
+If your program creates complicated data structures, just make them in
+core and give a fatal error if @code{malloc} returns zero.
+
+@node Writing C
+@chapter Making The Best Use of C
+
+This @value{CHAPTER} provides advice on how best to use the C language
+when writing GNU software.
+
+@menu
+* Formatting:: Formatting Your Source Code
+* Comments:: Commenting Your Work
+* Syntactic Conventions:: Clean Use of C Constructs
+* Names:: Naming Variables and Functions
+* System Portability:: Portability between different operating systems
+* CPU Portability:: Supporting the range of CPU types
+* System Functions:: Portability and ``standard'' library functions
+* Internationalization:: Techniques for internationalization
+* Mmap:: How you can safely use @code{mmap}.
+@end menu
+
+@node Formatting
+@section Formatting Your Source Code
+@cindex formatting source code
+
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero. Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+It is also important for function definitions to start the name of the
+function in column zero. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus,
+the proper format is this:
+
+@example
+static char *
+concat (s1, s2) /* Name starts in column zero here */
+ char *s1, *s2;
+@{ /* Open brace in column zero here */
+ @dots{}
+@}
+@end example
+
+@noindent
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+@example
+static char *
+concat (char *s1, char *s2)
+@{
+ @dots{}
+@}
+@end example
+
+In Standard C, if the arguments don't fit nicely on one line,
+split it like this:
+
+@example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+@dots{}
+@end example
+
+The rest of this section gives our recommendations for other aspects of
+C formatting style. We don't think of them as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+But whatever style you use, please use it consistently, since a mixture
+of styles within one program tends to look ugly. If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+For the body of the function, our recommended style looks like this:
+
+@example
+if (x < foo (y, z))
+ haha = bar[4] + 5;
+else
+ @{
+ while (z)
+ @{
+ haha += foo (z, z);
+ z--;
+ @}
+ return ++x + bar ();
+ @}
+@end example
+
+@cindex spaces before open-paren
+We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+When you split an expression into multiple lines, split it
+before an operator, not after one. Here is the right way:
+
+@cindex expressions, splitting
+@example
+if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+@end example
+
+Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+@example
+mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+@end example
+
+Instead, use extra parentheses so that the indentation shows the nesting:
+
+@example
+mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+@end example
+
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+@example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+@end example
+
+@noindent
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+@example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+@end example
+
+Format do-while statements like this:
+
+@example
+do
+ @{
+ a = foo (a);
+ @}
+while (a > 0);
+@end example
+
+@cindex formfeed
+@cindex control-L
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+@node Comments
+@section Commenting Your Work
+@cindex commenting
+
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}.
+
+Please write the comments in a GNU program in English, because English
+is the one language that nearly all programmers in all countries can
+read. If you do not write English well, please write comments in
+English as well as you can, then ask other people to help rewrite them.
+If you can't write comments in English, please find someone to work with
+you and translate your comments into English.
+
+Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion. If there is anything nonstandard about
+its use (such as an argument of type @code{char *} which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+Also explain the significance of the return value, if there is one.
+
+Please put two spaces after the end of a sentence in your comments, so
+that the Emacs sentence commands will work. Also, please write
+complete sentences and capitalize the first word. If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier. If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., ``The identifier lower-case is @dots{}'').
+
+The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, ``the inode
+number NODE_NUM'' rather than ``an inode''.
+
+There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the function
+itself would be off the bottom of the screen.
+
+There should be a comment on each static variable as well, like this:
+
+@example
+/* Nonzero means truncate lines in the display;
+ zero means continue them. */
+int truncate_lines;
+@end example
+
+Every @samp{#endif} should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, @emph{including
+its sense}. @samp{#else} should have a comment describing the condition
+@emph{and sense} of the code that follows. For example:
+
+@example
+@group
+#ifdef foo
+ @dots{}
+#else /* not foo */
+ @dots{}
+#endif /* not foo */
+@end group
+@group
+#ifdef foo
+ @dots{}
+#endif /* foo */
+@end group
+@end example
+
+@noindent
+but, by contrast, write the comments this way for a @samp{#ifndef}:
+
+@example
+@group
+#ifndef foo
+ @dots{}
+#else /* foo */
+ @dots{}
+#endif /* foo */
+@end group
+@group
+#ifndef foo
+ @dots{}
+#endif /* not foo */
+@end group
+@end example
+
+@node Syntactic Conventions
+@section Clean Use of C Constructs
+
+@cindex function argument, declaring
+Please explicitly declare all arguments to functions.
+Don't omit them just because they are @code{int}s.
+
+@cindex compiler warnings
+Some programmers like to use the GCC @samp{-Wall} option, and change the
+code whenever it issues a warning. If you want to do this, then do.
+Other programmers prefer not to use @samp{-Wall}, because it gives
+warnings for valid and legitimate code which they do not want to change.
+If you want to do this, then do. The compiler should be your servant,
+not your master.
+
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file. Don't put @code{extern} declarations inside
+functions.
+
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
+
+@cindex multiple variables in a line
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead
+of this:
+
+@example
+@group
+int foo,
+ bar;
+@end group
+@end example
+
+@noindent
+write either this:
+
+@example
+int foo, bar;
+@end example
+
+@noindent
+or this:
+
+@example
+int foo;
+int bar;
+@end example
+
+@noindent
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
+
+@example
+if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+@end example
+
+@noindent
+always like this:
+
+@example
+if (foo)
+ @{
+ if (bar)
+ win ();
+ else
+ lose ();
+ @}
+@end example
+
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
+
+@example
+if (foo)
+ @dots{}
+else if (bar)
+ @dots{}
+@end example
+
+@noindent
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
+
+@example
+if (foo)
+ @dots{}
+else
+ @{
+ if (bar)
+ @dots{}
+ @}
+@end example
+
+Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately
+and then use it to declare the variables or typedefs.
+
+Try to avoid assignments inside @code{if}-conditions. For example,
+don't write this:
+
+@example
+if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+@end example
+
+@noindent
+instead, write this:
+
+@example
+foo = (char *) malloc (sizeof *foo);
+if (foo == 0)
+ fatal ("virtual memory exhausted");
+@end example
+
+Don't make the program ugly to placate @code{lint}. Please don't insert any
+casts to @code{void}. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+@node Names
+@section Naming Variables and Functions
+
+@cindex names of variables and functions
+The names of global variables and functions in a program serve as
+comments of a sort. So don't choose terse names---instead, look for
+names that give useful information about the meaning of the variable or
+function. In a GNU program, names should be English, like other
+comments.
+
+Local variable names can be shorter, because they are used only within
+one context, where (presumably) comments explain their purpose.
+
+Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them. Stick to lower case; reserve
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
+
+For example, you should use names like @code{ignore_space_change_flag};
+don't use names like @code{iCantReadThis}.
+
+Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+@example
+@group
+/* Ignore changes in horizontal whitespace (-b). */
+int ignore_space_change_flag;
+@end group
+@end example
+
+When you want to define names with constant integer values, use
+@code{enum} rather than @samp{#define}. GDB knows about enumeration
+constants.
+
+Use file names of 14 characters or less, to avoid creating gratuitous
+problems on older System V systems. You can use the program
+@code{doschk} to test for this. @code{doschk} also tests for potential
+name conflicts if the files were loaded onto an MS-DOS file
+system---something you may or may not care about.
+
+@node System Portability
+@section Portability between System Types
+
+In the Unix world, ``portability'' refers to porting to different Unix
+versions. For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+The primary purpose of GNU software is to run on top of the GNU kernel,
+compiled with the GNU C compiler, on various types of @sc{cpu}. The
+amount and kinds of variation among GNU systems on different @sc{cpu}s
+will be comparable to the variation among Linux-based GNU systems or
+among BSD systems today. So the kinds of portability that are absolutely
+necessary are quite limited.
+
+But many users do run GNU software on non-GNU Unix or Unix-like systems.
+So supporting a variety of Unix-like systems is desirable, although not
+paramount.
+
+The easiest way to achieve portability to most Unix-like systems is to
+use Autoconf. It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+Avoid using the format of semi-internal data bases (e.g., directories)
+when there is a higher-level alternative (@code{readdir}).
+
+As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work. When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+It is a good idea to define the ``feature test macro''
+@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
+or GNU/Linux, this will enable the declarations of GNU library extension
+functions, and that will usually give you a compiler error message if
+you define the same function names in some other way in your program.
+(You don't have to actually @emph{use} these functions, if you prefer
+to make the program more portable to other systems.)
+
+But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings. Doing so would make it hard
+to move your code into other GNU programs.
+
+@node CPU Portability
+@section Portability between @sc{cpu}s
+
+Even GNU systems will differ because of differences among @sc{cpu}
+types---for example, difference in byte ordering and alignment
+requirements. It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+@code{int} will be less than 32 bits. We don't support 16-bit machines
+in GNU.
+
+Don't assume that the address of an @code{int} object is also the
+address of its least-significant byte. This is false on big-endian
+machines. Thus, don't make the following mistake:
+
+@example
+int c;
+@dots{}
+while ((c = getchar()) != EOF)
+ write(file_descriptor, &c, 1);
+@end example
+
+When calling functions, you need not worry about the difference between
+pointers of various types, or between pointers and integers. On most
+machines, there's no difference anyway. As for the few machines where
+there is a difference, all of them support 1989 Standard C, so you can
+use prototypes (perhaps conditionalized to be active only in Standard C)
+to make the code work on those systems.
+
+In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system. For example, many GNU programs have error-reporting functions
+that pass their arguments along to @code{printf} and friends:
+
+@example
+error (s, a1, a2, a3)
+ char *s;
+ char *a1, *a2, *a3;
+@{
+ fprintf (stderr, "error: ");
+ fprintf (stderr, s, a1, a2, a3);
+@}
+@end example
+
+@noindent
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument; it is much simpler than any
+``correct'' alternative. Be sure @emph{not} to use a prototype for such
+functions.
+
+If you have decided to use 1989 Standard C, then you can instead define
+@code{error} using @file{stdarg.h}, and pass the arguments along to
+@code{vfprintf}.
+
+Avoid casting pointers to integers if you can. Such casts greatly
+reduce portability, and in most programs they are easy to avoid. In the
+cases where casting pointers to integers is essential---such as, a Lisp
+interpreter which stores type information as well as an address in one
+word---you'll have to make explicit provisions to handle different word
+sizes. You will also need to make provision for systems in which the
+normal range of addresses you can get from @code{malloc} starts far away
+from zero.
+
+@node System Functions
+@section Calling System Functions
+
+C implementations differ substantially. 1989 Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do. This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the return value of @code{sprintf}. It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+Be aware that @code{vfprintf} is not always available.
+
+@item
+@code{main} should be declared to return type @code{int}. It should
+terminate either by calling @code{exit} or by returning the integer
+status code; make sure it cannot ever return an undefined value.
+
+@item
+Don't declare system functions explicitly.
+
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions. If the headers don't declare a function, let it
+remain undeclared.
+
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens; thus, the disadvantage is only
+theoretical. By contrast, actual declarations have frequently caused
+actual conflicts.
+
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not a Standard C prototype. The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}. These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine. For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@item
+The string functions require special treatment. Some Unix systems have
+a header file @file{string.h}; others have @file{strings.h}. Neither
+file name is portable. There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+
+That causes less of a problem than you might think. The newer standard
+string functions should be avoided anyway because many systems still
+don't support them. The string functions you can use are these:
+
+@example
+strcpy strncpy strcat strncat
+strlen strcmp strncmp
+strchr strrchr
+@end example
+
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values. Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases. It is trivial to
+avoid using their values, so do that.
+
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+
+The search functions must be declared to return @code{char *}. Luckily,
+there is no variation in the data type they return. But there is
+variation in their names. Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}. Some systems support both pairs of
+names, but neither pair works on all systems.
+
+You should pick a single pair of names and use it throughout your
+program. (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr} for new programs, since those are the standard
+names.) Declare both of those names as functions returning @code{char
+*}. On systems which don't support those names, define them as macros
+in terms of the other pair. For example, here is what to put at the
+beginning of your file (or in a header) if you want to use the names
+@code{strchr} and @code{strrchr} throughout:
+
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+
+@node Internationalization
+@section Internationalization
+
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages. You should use this
+library in every program. Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+Using GNU gettext involves putting a call to the @code{gettext} macro
+around each string that might need translation---like this:
+
+@example
+printf (gettext ("Processing file `%s'..."));
+@end example
+
+@noindent
+This permits GNU gettext to replace the string @code{"Processing file
+`%s'..."} with a translated version.
+
+Once a program uses gettext, please make a point of writing calls to
+@code{gettext} when you add new strings that call for translation.
+
+Using GNU gettext in a package involves specifying a @dfn{text domain
+name} for the package. The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package---for example, @samp{fileutils} for the GNU file utilities.
+
+To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences. When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+Here is an example of what not to do:
+
+@example
+printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
+@end example
+
+@noindent
+The problem with that example is that it assumes that plurals are made
+by adding `s'. If you apply gettext to the format string, like this,
+
+@example
+printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
+@end example
+
+@noindent
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way:
+
+@example
+printf ((nfiles != 1 ? "%d files processed"
+ : "%d file processed"),
+ nfiles);
+@end example
+
+@noindent
+This way, you can apply gettext to each of the two strings
+independently:
+
+@example
+printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+@end example
+
+@noindent
+This can be any method of forming the plural of the word for ``file'', and
+also handles languages that require agreement in the word for
+``processed''.
+
+A similar problem appears at the level of sentence structure with this
+code:
+
+@example
+printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+@end example
+
+@noindent
+Adding @code{gettext} calls to this code cannot give correct results for
+all languages, because negation in some languages requires adding words
+at more than one place in the sentence. By contrast, adding
+@code{gettext} calls does the job straightfowardly if the code starts
+out like this:
+
+@example
+printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
+@end example
+
+@node Mmap
+@section Mmap
+
+Don't assume that @code{mmap} either works on all files or fails
+for all files. It may work on some files and fail on others.
+
+The proper way to use @code{mmap} is to try it on the specific file for
+which you want to use it---and if @code{mmap} doesn't work, fall back on
+doing the job in another way using @code{read} and @code{write}.
+
+The reason this precaution is needed is that the GNU kernel (the HURD)
+provides a user-extensible file system, in which there can be many
+different kinds of ``ordinary files.'' Many of them support
+@code{mmap}, but some do not. It is important to make programs handle
+all these kinds of files.
+
+@node Documentation
+@chapter Documenting Programs
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes. If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+@menu
+* GNU Manuals:: Writing proper manuals.
+* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
+* NEWS File:: NEWS files supplement manuals.
+* Change Logs:: Recording Changes
+* Man Pages:: Man pages are secondary.
+* Reading other Manuals:: How far you can go in learning
+ from other manuals.
+@end menu
+
+@node GNU Manuals
+@section GNU Manuals
+
+The preferred way to document part of the GNU system is to write a
+manual in the Texinfo formatting language. This makes it possible to
+produce a good quality formatted book, using @TeX{}, and to generate an
+Info file. It is also possible to generate HTML output from Texinfo
+source. See the Texinfo manual, either the hardcopy, or the on-line
+version available through @code{info} or the Emacs Info subsystem
+(@kbd{C-h i}).
+
+Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know. But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it. Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented---but
+often they are different. Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual. That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+Instead, each manual should cover a coherent @emph{topic}. For example,
+instead of a manual for @code{diff} and a manual for @code{diff3}, we
+have one manual for ``comparison of files'' which covers both of those
+programs, as well as @code{cmp}. By documenting these programs
+together, we can make the whole subject clearer.
+
+The manual which discusses a program should document all of the
+program's command-line options and all of its commands. It should give
+examples of their use. But don't organize the manual as a list of
+features. Instead, organize it logically, by subtopics. Address the
+questions that a user will ask when thinking about the job that the
+program does.
+
+In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside). A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
+
+That is not as hard as it first sounds. Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense. Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs. The watchword is, @emph{at each point, address
+the most fundamental and important issue raised by the preceding text.}
+
+If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject. These provide
+the framework for a beginner to understand the rest of the manual. The
+Bison manual provides a good example of how to do this.
+
+Don't use Unix man pages as a model for how to write GNU documentation;
+most of them are terse, badly structured, and give inadequate
+explanation of the underlying concepts. (There are, of course
+exceptions.) Also Unix man pages use a particular format which is
+different from what we use in GNU manuals.
+
+Please include an email address in the manual for where to report
+bugs @emph{in the manual}.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead. We use the term
+``path'' only for search paths, which are lists of directory names.
+
+Please do not use the term ``illegal'' to refer to erroneous input to a
+computer program. Please use ``invalid'' for this, and reserve the term
+``illegal'' for violations of law.
+
+@node Manual Structure Details
+@section Manual Structure Details
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual. The Top node of the manual should
+also contain this information. If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+Each program documented in the manual should have a node named
+@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
+node (together with its subnodes, if any) should describe the program's
+command line arguments and how to run it (the sort of information people
+would look in a man page for). Start with an @samp{@@example}
+containing a template for all the options and arguments that the program
+uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns. This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+If one manual describes several programs, it should have such a node for
+each program described.
+
+@node License for Manuals
+@section License for Manuals
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long. Likewise for a collection of short
+documents---you only need one copy of the GNU FDL for the whole
+collection. For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+@node NEWS File
+@section The NEWS File
+
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning. In each new release, add items to the front of the file and
+identify the version they pertain to. Don't discard old items; leave
+them in the file after the newer items. This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+@node Change Logs
+@section Change Logs
+
+Keep a change log to describe all the changes made to program source
+files. The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+@menu
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+* Indicating the Part Changed::
+@end menu
+
+@node Change Log Concepts
+@subsection Change Log Concepts
+
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it. What they want from a change log is a
+clear explanation of how the earlier version differed.
+
+The change log file is normally called @file{ChangeLog} and covers an
+entire directory. Each directory can have its own change log, or a
+directory can use the change log of its parent directory--it's up to
+you.
+
+Another alternative is to record change log information with a version
+control system such as RCS or CVS. This can be converted automatically
+to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
+@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
+
+There's no need to describe the full purpose of the changes or how they
+work together. If you think that a change calls for explanation, you're
+probably right. Please do explain it---but please put the explanation
+in comments in the code, where people will see it whenever they see the
+code. For example, ``New function'' is enough for the change log when
+you add a function, because there should be a comment before the
+function definition to explain what it does.
+
+However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+The easiest way to add an entry to @file{ChangeLog} is with the Emacs
+command @kbd{M-x add-change-log-entry}. An entry should have an
+asterisk, the name of the changed file, and then in parentheses the name
+of the changed functions, variables or whatever, followed by a colon.
+Then describe the changes you made to that function or variable.
+
+@node Style of Change Logs
+@subsection Style of Change Logs
+
+Here are some examples of change log entries:
+
+@example
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+
+* sort.el (sort-subr): Return nil.
+
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+
+* keyboard.c (menu_bar_items, tool_bar_items)
+(Fexecute_extended_command): Deal with `keymap' property.
+@end example
+
+It's important to name the changed function or variable in full. Don't
+abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+For example, some people are tempted to abbreviate groups of function
+names by writing @samp{* register.el (@{insert,jump-to@}-register)};
+this is not a good idea, since searching for @code{jump-to-register} or
+@code{insert-register} would not find that entry.
+
+Separate unrelated change log entries with blank lines. When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them. Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+Break long lists of function names by closing continued lines with
+@samp{)}, rather than @samp{,}, and opening the continuation with
+@samp{(} as in the example above.
+
+@node Simple Changes
+@subsection Simple Changes
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+When you change the calling sequence of a function in a simple fashion,
+and you change all the callers of the function, there is no need to make
+individual entries for all the callers that you changed. Just write in
+the entry for the function being called, ``All callers changed.''
+
+@example
+* keyboard.c (Fcommand_execute): New arg SPECIAL.
+All callers changed.
+@end example
+
+When you change just comments or doc strings, it is enough to write an
+entry for the file, without mentioning the functions. Just ``Doc
+fixes'' is enough for the change log.
+
+There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix. Documentation does not consist of parts that must interact in a
+precisely engineered fashion. To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+@node Conditional Changes
+@subsection Conditional Changes
+
+C programs often contain compile-time @code{#if} conditionals. Many
+changes are conditional; sometimes you add a new definition which is
+entirely contained in a conditional. It is very useful to indicate in
+the change log the conditions for which the change applies.
+
+Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+Here is a simple example, describing a change which is conditional but
+does not have a function or entity name associated with it:
+
+@example
+* xterm.c [SOLARIS2]: Include string.h.
+@end example
+
+Here is an entry describing a new definition which is entirely
+conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
+used only when @code{HAVE_X_WINDOWS} is defined:
+
+@example
+* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+@end example
+
+Here is an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+
+@example
+* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+@end example
+
+Here is an entry for a change that takes affect only when
+a certain macro is @emph{not} defined:
+
+@example
+(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+@end example
+
+@node Indicating the Part Changed
+@subsection Indicating the Part Changed
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does. Here is an entry
+for a change in the part of the function that deals with @code{sh}
+commands.
+
+@example
+* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+user-specified option string is empty.
+@end example
+
+
+@node Man Pages
+@section Man Pages
+
+In the GNU project, man pages are secondary. It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed. The time
+you spend on the man page is time taken away from more useful work.
+
+For a simple program which changes little, updating the man page may be
+a small job. Then there is little reason not to include a man page, if
+you have one.
+
+For a large program that changes a great deal, updating a man page may
+be a substantial burden. If a user offers to donate a man page, you may
+find this gift costly to accept. It may be better to refuse the man
+page unless the same person agrees to take full responsibility for
+maintaining it---so that you can wash your hands of it entirely. If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating. If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative. The note should say how to access the Texinfo
+documentation.
+
+@node Reading other Manuals
+@section Reading other Manuals
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+It is ok to use these documents for reference, just as the author of a
+new algebra textbook can read other books on algebra. A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject. But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation. Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+@node Managing Releases
+@chapter The Release Process
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of
+all GNU software.
+
+@menu
+* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
+* Releases:: Making Releases
+@end menu
+
+@node Configuration
+@section How Configuration Should Work
+
+Each GNU distribution should come with a shell script named
+@code{configure}. This script is given arguments which describe the
+kind of machine and system you want to compile the program for.
+
+The @code{configure} script must record the configuration options so
+that they affect compilation.
+
+One way to do this is to make a link from a standard name such as
+@file{config.h} to the proper configuration file for the chosen system.
+If you use this technique, the distribution should @emph{not} contain a
+file named @file{config.h}. This is so that people won't be able to
+build the program without configuring it first.
+
+Another thing that @code{configure} can do is to edit the Makefile. If
+you do this, the distribution should @emph{not} contain a file named
+@file{Makefile}. Instead, it should include a file @file{Makefile.in} which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+If @code{configure} does write the @file{Makefile}, then @file{Makefile}
+should have a target named @file{Makefile} which causes @code{configure}
+to be rerun, setting up the same configuration that was set up last
+time. The files that @code{configure} reads should be listed as
+dependencies of @file{Makefile}.
+
+All the files which are output from the @code{configure} script should
+have comments at the beginning explaining that they were generated
+automatically using @code{configure}. This is so that users won't think
+of trying to edit them by hand.
+
+The @code{configure} script should write a file named @file{config.status}
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+The @code{configure} script should accept an option of the form
+@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
+(if it is not the current directory). This makes it possible to build
+the program in a separate directory, so that the actual source directory
+is not modified.
+
+If the user does not specify @samp{--srcdir}, then @code{configure} should
+check both @file{.} and @file{..} to see if it can find the sources. If
+it finds the sources in one of these places, it should use them from
+there. Otherwise, it should report that it cannot find the sources, and
+should exit with nonzero status.
+
+Usually the easy way to support @samp{--srcdir} is by editing a
+definition of @code{VPATH} into the Makefile. Some rules may need to
+refer explicitly to the specified source directory. To make this
+possible, @code{configure} can add to the Makefile a variable named
+@code{srcdir} whose value is precisely the specified directory.
+
+The @code{configure} script should also take an argument which specifies the
+type of system to build the program for. This argument should look like
+this:
+
+@example
+@var{cpu}-@var{company}-@var{system}
+@end example
+
+For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
+
+The @code{configure} script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}
+would be a valid alias. For many programs, @samp{vax-dec-ultrix} would
+be an alias for @samp{vax-dec-bsd}, simply because the differences
+between Ultrix and @sc{bsd} are rarely noticeable, but a few programs
+might need to distinguish them.
+@c Real 4.4BSD now runs on some Suns.
+
+There is a shell script called @file{config.sub} that you can use
+as a subroutine to validate system types and canonicalize aliases.
+
+Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}. This allows users to choose which
+optional features to include. Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another. No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior. The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
+@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+
+@c Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
+@samp{gdb},
+@samp{x},
+and
+@samp{x-toolkit}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files. That is outside the scope of what @samp{--with}
+options are for.
+
+@item --nfp
+The target machine has no floating point processor.
+
+@item --gas
+The target machine assembler is GAS, the GNU assembler.
+This is obsolete; users should use @samp{--with-gnu-as} instead.
+
+@item --x
+The target machine has the X Window System installed.
+This is obsolete; users should use @samp{--with-x} instead.
+@end table
+
+All @code{configure} scripts should accept all of these ``detail''
+options, whether or not they make any difference to the particular
+package at hand. In particular, they should accept any option that
+starts with @samp{--with-} or @samp{--enable-}. This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+Packages that perform part of the compilation process may support cross-compilation.
+In such a case, the host and target machines for the program may be
+different. The @code{configure} script should normally treat the
+specified type of system as both the host and the target, thus producing
+a program which works for the same type of machine that it runs on.
+
+The way to build a cross-compiler, cross-assembler, or what have you, is
+to specify the option @samp{--host=@var{hosttype}} when running
+@code{configure}. This specifies the host system without changing the
+type of target system. The syntax for @var{hosttype} is the same as
+described above.
+
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on. Compilation packages accept a
+configuration option @samp{--build=@var{hosttype}} for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
+Programs for which cross-operation is not meaningful need not accept the
+@samp{--host} option, because configuring an entire operating system for
+cross-operation is not a meaningful thing.
+
+Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.
+@comment For this document, turn chapters into sections, etc.
+@lowersections
+@include make-stds.texi
+@raisesections
+
+@node Releases
+@section Making Releases
+
+Package the distribution of @code{Foo version 69.96} up in a gzipped tar
+file with the name @file{foo-69.96.tar.gz}. It should unpack into a
+subdirectory named @file{foo-69.96}.
+
+Building and installing the program should never modify any of the files
+contained in the distribution. This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}. Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+
+The distribution should contain a file named @file{README} which gives
+the name of the package, and a general description of what it does. It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any. The @file{README} file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+The @file{README} file should refer to the file @file{INSTALL}, which
+should contain an explanation of the installation procedure.
+
+The @file{README} file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+@file{COPYING}. If the GNU LGPL is used, it should be in a file called
+@file{COPYING.LIB}.
+
+Naturally, all the source files must be in the distribution. It is okay
+to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them. We commonly include non-source files
+produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+Non-source files that might actually be modified by building and
+installing the program should @strong{never} be included in the
+distribution. So if you do distribute non-source files, always make
+sure they are up to date when you make a new distribution.
+
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+
+Make sure that all the files in the distribution are world-readable.
+
+Make sure that no file name in the distribution is more than 14
+characters long. Likewise, no file created by building the program
+should have a name longer than 14 characters. The reason for this is
+that some systems adhere to a foolish interpretation of the @sc{posix}
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+Don't include any symbolic links in the distribution itself. If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
+
+Try to make sure that all the file names will be unique on MS-DOS. A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters. MS-DOS will truncate extra
+characters both before and after the period. Thus,
+@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
+distinct.
+
+Include in your distribution a copy of the @file{texinfo.tex} you used
+to test print any @file{*.texinfo} or @file{*.texi} files.
+
+Likewise, if your program uses small GNU software packages like regex,
+getopt, obstack, or termcap, include them in the distribution file.
+Leaving them out would make the distribution file a little smaller at
+the expense of possible inconvenience to a user who doesn't know what
+other files to get.
+
+@node References
+@chapter References to Non-Free Software and Documentation
+
+A GNU program should not recommend use of any non-free program. We
+can't stop some people from writing proprietary programs, or stop other
+people from using them. But we can and should avoid helping to
+advertise them to new customers.
+
+Sometimes it is important to mention how to build your package on top of
+some non-free operating system or other non-free base package. In such
+cases, please mention the name of the non-free package or system in the
+briefest possible way. Don't include any references for where to find
+more information about the proprietary program. The goal should be that
+people already using the proprietary program will get the advice they
+need about how to use your free program, while people who don't already
+use the proprietary program will not see anything to encourage them to
+take an interest in it.
+
+Likewise, a GNU package should not refer the user to any non-free
+documentation for free software. The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+
+@bye
+Local variables:
+update-date-leading-regexp: "@c This date is automagically updated when you save this file:\n@set lastupdate "
+update-date-trailing-regexp: ""
+eval: (load "/gd/gnuorg/update-date.el")
+eval: (add-hook 'write-file-hooks 'update-date)
+End:
-% texinfo.tex -- TeX macros to handle Texinfo files.\r
-%\r
-% Load plain if necessary, i.e., if running under initex.\r
-\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi\r
-%\r
-\def\texinfoversion{2000-05-28.15}\r
-%\r
-% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99\r
-% Free Software Foundation, Inc.\r
-%\r
-% This texinfo.tex file is free software; you can redistribute it and/or\r
-% modify it under the terms of the GNU General Public License as\r
-% published by the Free Software Foundation; either version 2, or (at\r
-% your option) any later version.\r
-%\r
-% This texinfo.tex file is distributed in the hope that it will be\r
-% useful, but WITHOUT ANY WARRANTY; without even the implied warranty\r
-% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\r
-% General Public License for more details.\r
-%\r
-% You should have received a copy of the GNU General Public License\r
-% along with this texinfo.tex file; see the file COPYING. If not, write\r
-% to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,\r
-% Boston, MA 02111-1307, USA.\r
-%\r
-% In other words, you are welcome to use, share and improve this program.\r
-% You are forbidden to forbid anyone else to use, share and improve\r
-% what you give them. Help stamp out software-hoarding!\r
-%\r
-% Please try the latest version of texinfo.tex before submitting bug\r
-% reports; you can get the latest version from:\r
-% ftp://ftp.gnu.org/gnu/texinfo.tex\r
-% (and all GNU mirrors, see http://www.gnu.org/order/ftp.html)\r
-% ftp://texinfo.org/tex/texinfo.tex\r
-% ftp://us.ctan.org/macros/texinfo/texinfo.tex\r
-% (and all CTAN mirrors, finger ctan@us.ctan.org for a list).\r
-% /home/gd/gnu/doc/texinfo.tex on the GNU machines.\r
-% The texinfo.tex in any given Texinfo distribution could well be out\r
-% of date, so if that's what you're using, please check.\r
-% Texinfo has a small home page at http://texinfo.org/.\r
-%\r
-% Send bug reports to bug-texinfo@gnu.org. Please include including a\r
-% complete document in each bug report with which we can reproduce the\r
-% problem. Patches are, of course, greatly appreciated.\r
-%\r
-% To process a Texinfo manual with TeX, it's most reliable to use the\r
-% texi2dvi shell script that comes with the distribution. For a simple\r
-% manual foo.texi, however, you can get away with this:\r
-% tex foo.texi\r
-% texindex foo.??\r
-% tex foo.texi\r
-% tex foo.texi\r
-% dvips foo.dvi -o # or whatever, to process the dvi file; this makes foo.ps.\r
-% The extra runs of TeX get the cross-reference information correct.\r
-% Sometimes one run after texindex suffices, and sometimes you need more\r
-% than two; texi2dvi does it as many times as necessary.\r
-%\r
-% It is possible to adapt texinfo.tex for other languages. You can get\r
-% the existing language-specific files from ftp://ftp.gnu.org/gnu/texinfo/.\r
-\r
-\message{Loading texinfo [version \texinfoversion]:}\r
-\r
-% If in a .fmt file, print the version number\r
-% and turn on active characters that we couldn't do earlier because\r
-% they might have appeared in the input file name.\r
-\everyjob{\message{[Texinfo version \texinfoversion]}%\r
- \catcode`+=\active \catcode`\_=\active}\r
-\r
-% Save some parts of plain tex whose names we will redefine.\r
-\let\ptexb=\b\r
-\let\ptexbullet=\bullet\r
-\let\ptexc=\c\r
-\let\ptexcomma=\,\r
-\let\ptexdot=\.\r
-\let\ptexdots=\dots\r
-\let\ptexend=\end\r
-\let\ptexequiv=\equiv\r
-\let\ptexexclam=\!\r
-\let\ptexi=\i\r
-\let\ptexlbrace=\{\r
-\let\ptexrbrace=\}\r
-\let\ptexstar=\*\r
-\let\ptext=\t\r
-\r
-% We never want plain's outer \+ definition in Texinfo.\r
-% For @tex, we can use \tabalign.\r
-\let\+ = \relax\r
-\r
-\message{Basics,}\r
-\chardef\other=12\r
-\r
-% If this character appears in an error message or help string, it\r
-% starts a new line in the output.\r
-\newlinechar = `^^J\r
-\r
-% Set up fixed words for English if not already set.\r
-\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi\r
-\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi\r
-\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi\r
-\ifx\putwordin\undefined \gdef\putwordin{in}\fi\r
-\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi\r
-\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi\r
-\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi\r
-\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi\r
-\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi\r
-\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi\r
-\ifx\putwordof\undefined \gdef\putwordof{of}\fi\r
-\ifx\putwordon\undefined \gdef\putwordon{on}\fi\r
-\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi\r
-\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi\r
-\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi\r
-\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi\r
-\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi\r
-\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi\r
-\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi\r
-%\r
-\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi\r
-\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi\r
-\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi\r
-\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi\r
-\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi\r
-\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi\r
-\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi\r
-\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi\r
-\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi\r
-\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi\r
-\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi\r
-\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi\r
-%\r
-\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi\r
-\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi\r
-\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi\r
-\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi\r
-\ifx\putwordDeftypevar\undefined\gdef\putwordDeftypevar{Variable}\fi\r
-\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi\r
-\ifx\putwordDeftypefun\undefined\gdef\putwordDeftypefun{Function}\fi\r
-\r
-% Ignore a token.\r
-%\r
-\def\gobble#1{}\r
-\r
-\hyphenation{ap-pen-dix}\r
-\hyphenation{mini-buf-fer mini-buf-fers}\r
-\hyphenation{eshell}\r
-\hyphenation{white-space}\r
-\r
-% Margin to add to right of even pages, to left of odd pages.\r
-\newdimen \bindingoffset\r
-\newdimen \normaloffset\r
-\newdimen\pagewidth \newdimen\pageheight\r
-\r
-% Sometimes it is convenient to have everything in the transcript file\r
-% and nothing on the terminal. We don't just call \tracingall here,\r
-% since that produces some useless output on the terminal.\r
-%\r
-\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%\r
-\ifx\eTeXversion\undefined\r
-\def\loggingall{\tracingcommands2 \tracingstats2\r
- \tracingpages1 \tracingoutput1 \tracinglostchars1\r
- \tracingmacros2 \tracingparagraphs1 \tracingrestores1\r
- \showboxbreadth\maxdimen\showboxdepth\maxdimen\r
-}%\r
-\else\r
-\def\loggingall{\tracingcommands3 \tracingstats2\r
- \tracingpages1 \tracingoutput1 \tracinglostchars1\r
- \tracingmacros2 \tracingparagraphs1 \tracingrestores1\r
- \tracingscantokens1 \tracingassigns1 \tracingifs1\r
- \tracinggroups1 \tracingnesting2\r
- \showboxbreadth\maxdimen\showboxdepth\maxdimen\r
-}%\r
-\fi\r
-\r
-% For @cropmarks command.\r
-% Do @cropmarks to get crop marks.\r
-%\r
-\newif\ifcropmarks\r
-\let\cropmarks = \cropmarkstrue\r
-%\r
-% Dimensions to add cropmarks at corners.\r
-% Added by P. A. MacKay, 12 Nov. 1986\r
-%\r
-\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines\r
-\newdimen\cornerlong \cornerlong=1pc\r
-\newdimen\cornerthick \cornerthick=.3pt\r
-\newdimen\topandbottommargin \topandbottommargin=.75in\r
-\r
-% Main output routine.\r
-\chardef\PAGE = 255\r
-\output = {\onepageout{\pagecontents\PAGE}}\r
-\r
-\newbox\headlinebox\r
-\newbox\footlinebox\r
-\r
-% \onepageout takes a vbox as an argument. Note that \pagecontents\r
-% does insertions, but you have to call it yourself.\r
-\def\onepageout#1{%\r
- \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi\r
- %\r
- \ifodd\pageno \advance\hoffset by \bindingoffset\r
- \else \advance\hoffset by -\bindingoffset\fi\r
- %\r
- % Do this outside of the \shipout so @code etc. will be expanded in\r
- % the headline as they should be, not taken literally (outputting ''code).\r
- \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}%\r
- \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}%\r
- %\r
- {%\r
- % Have to do this stuff outside the \shipout because we want it to\r
- % take effect in \write's, yet the group defined by the \vbox ends\r
- % before the \shipout runs.\r
- %\r
- \escapechar = `\\ % use backslash in output files.\r
- \indexdummies % don't expand commands in the output.\r
- \normalturnoffactive % \ in index entries must not stay \, e.g., if\r
- % the page break happens to be in the middle of an example.\r
- \shipout\vbox{%\r
- % Do this early so pdf references go to the beginning of the page.\r
- \ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi\r
- %\r
- \ifcropmarks \vbox to \outervsize\bgroup\r
- \hsize = \outerhsize\r
- \vskip-\topandbottommargin\r
- \vtop to0pt{%\r
- \line{\ewtop\hfil\ewtop}%\r
- \nointerlineskip\r
- \line{%\r
- \vbox{\moveleft\cornerthick\nstop}%\r
- \hfill\r
- \vbox{\moveright\cornerthick\nstop}%\r
- }%\r
- \vss}%\r
- \vskip\topandbottommargin\r
- \line\bgroup\r
- \hfil % center the page within the outer (page) hsize.\r
- \ifodd\pageno\hskip\bindingoffset\fi\r
- \vbox\bgroup\r
- \fi\r
- %\r
- \unvbox\headlinebox\r
- \pagebody{#1}%\r
- \ifdim\ht\footlinebox > 0pt\r
- % Only leave this space if the footline is nonempty.\r
- % (We lessened \vsize for it in \oddfootingxxx.)\r
- % The \baselineskip=24pt in plain's \makefootline has no effect.\r
- \vskip 2\baselineskip\r
- \unvbox\footlinebox\r
- \fi\r
- %\r
- \ifcropmarks\r
- \egroup % end of \vbox\bgroup\r
- \hfil\egroup % end of (centering) \line\bgroup\r
- \vskip\topandbottommargin plus1fill minus1fill\r
- \boxmaxdepth = \cornerthick\r
- \vbox to0pt{\vss\r
- \line{%\r
- \vbox{\moveleft\cornerthick\nsbot}%\r
- \hfill\r
- \vbox{\moveright\cornerthick\nsbot}%\r
- }%\r
- \nointerlineskip\r
- \line{\ewbot\hfil\ewbot}%\r
- }%\r
- \egroup % \vbox from first cropmarks clause\r
- \fi\r
- }% end of \shipout\vbox\r
- }% end of group with \turnoffactive\r
- \advancepageno\r
- \ifnum\outputpenalty>-20000 \else\dosupereject\fi\r
-}\r
-\r
-\newinsert\margin \dimen\margin=\maxdimen\r
-\r
-\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}\r
-{\catcode`\@ =11\r
-\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi\r
-% marginal hacks, juha@viisa.uucp (Juha Takala)\r
-\ifvoid\margin\else % marginal info is present\r
- \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi\r
-\dimen@=\dp#1 \unvbox#1\r
-\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi\r
-\ifr@ggedbottom \kern-\dimen@ \vfil \fi}\r
-}\r
-\r
-% Here are the rules for the cropmarks. Note that they are\r
-% offset so that the space between them is truly \outerhsize or \outervsize\r
-% (P. A. MacKay, 12 November, 1986)\r
-%\r
-\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}\r
-\def\nstop{\vbox\r
- {\hrule height\cornerthick depth\cornerlong width\cornerthick}}\r
-\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}\r
-\def\nsbot{\vbox\r
- {\hrule height\cornerlong depth\cornerthick width\cornerthick}}\r
-\r
-% Parse an argument, then pass it to #1. The argument is the rest of\r
-% the input line (except we remove a trailing comment). #1 should be a\r
-% macro which expects an ordinary undelimited TeX argument.\r
-%\r
-\def\parsearg#1{%\r
- \let\next = #1%\r
- \begingroup\r
- \obeylines\r
- \futurelet\temp\parseargx\r
-}\r
-\r
-% If the next token is an obeyed space (from an @example environment or\r
-% the like), remove it and recurse. Otherwise, we're done.\r
-\def\parseargx{%\r
- % \obeyedspace is defined far below, after the definition of \sepspaces.\r
- \ifx\obeyedspace\temp\r
- \expandafter\parseargdiscardspace\r
- \else\r
- \expandafter\parseargline\r
- \fi\r
-}\r
-\r
-% Remove a single space (as the delimiter token to the macro call).\r
-{\obeyspaces %\r
- \gdef\parseargdiscardspace {\futurelet\temp\parseargx}}\r
-\r
-{\obeylines %\r
- \gdef\parseargline#1^^M{%\r
- \endgroup % End of the group started in \parsearg.\r
- %\r
- % First remove any @c comment, then any @comment.\r
- % Result of each macro is put in \toks0.\r
- \argremovec #1\c\relax %\r
- \expandafter\argremovecomment \the\toks0 \comment\relax %\r
- %\r
- % Call the caller's macro, saved as \next in \parsearg.\r
- \expandafter\next\expandafter{\the\toks0}%\r
- }%\r
-}\r
-\r
-% Since all \c{,omment} does is throw away the argument, we can let TeX\r
-% do that for us. The \relax here is matched by the \relax in the call\r
-% in \parseargline; it could be more or less anything, its purpose is\r
-% just to delimit the argument to the \c.\r
-\def\argremovec#1\c#2\relax{\toks0 = {#1}}\r
-\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}}\r
-\r
-% \argremovec{,omment} might leave us with trailing spaces, though; e.g.,\r
-% @end itemize @c foo\r
-% will have two active spaces as part of the argument with the\r
-% `itemize'. Here we remove all active spaces from #1, and assign the\r
-% result to \toks0.\r
-%\r
-% This loses if there are any *other* active characters besides spaces\r
-% in the argument -- _ ^ +, for example -- since they get expanded.\r
-% Fortunately, Texinfo does not define any such commands. (If it ever\r
-% does, the catcode of the characters in questionwill have to be changed\r
-% here.) But this means we cannot call \removeactivespaces as part of\r
-% \argremovec{,omment}, since @c uses \parsearg, and thus the argument\r
-% that \parsearg gets might well have any character at all in it.\r
-%\r
-\def\removeactivespaces#1{%\r
- \begingroup\r
- \ignoreactivespaces\r
- \edef\temp{#1}%\r
- \global\toks0 = \expandafter{\temp}%\r
- \endgroup\r
-}\r
-\r
-% Change the active space to expand to nothing.\r
-%\r
-\begingroup\r
- \obeyspaces\r
- \gdef\ignoreactivespaces{\obeyspaces\let =\empty}\r
-\endgroup\r
-\r
-\r
-\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}\r
-\r
-%% These are used to keep @begin/@end levels from running away\r
-%% Call \inENV within environments (after a \begingroup)\r
-\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi}\r
-\def\ENVcheck{%\r
-\ifENV\errmessage{Still within an environment; press RETURN to continue}\r
-\endgroup\fi} % This is not perfect, but it should reduce lossage\r
-\r
-% @begin foo is the same as @foo, for now.\r
-\newhelp\EMsimple{Press RETURN to continue.}\r
-\r
-\outer\def\begin{\parsearg\beginxxx}\r
-\r
-\def\beginxxx #1{%\r
-\expandafter\ifx\csname #1\endcsname\relax\r
-{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else\r
-\csname #1\endcsname\fi}\r
-\r
-% @end foo executes the definition of \Efoo.\r
-%\r
-\def\end{\parsearg\endxxx}\r
-\def\endxxx #1{%\r
- \removeactivespaces{#1}%\r
- \edef\endthing{\the\toks0}%\r
- %\r
- \expandafter\ifx\csname E\endthing\endcsname\relax\r
- \expandafter\ifx\csname \endthing\endcsname\relax\r
- % There's no \foo, i.e., no ``environment'' foo.\r
- \errhelp = \EMsimple\r
- \errmessage{Undefined command `@end \endthing'}%\r
- \else\r
- \unmatchedenderror\endthing\r
- \fi\r
- \else\r
- % Everything's ok; the right environment has been started.\r
- \csname E\endthing\endcsname\r
- \fi\r
-}\r
-\r
-% There is an environment #1, but it hasn't been started. Give an error.\r
-%\r
-\def\unmatchedenderror#1{%\r
- \errhelp = \EMsimple\r
- \errmessage{This `@end #1' doesn't have a matching `@#1'}%\r
-}\r
-\r
-% Define the control sequence \E#1 to give an unmatched @end error.\r
-%\r
-\def\defineunmatchedend#1{%\r
- \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}%\r
-}\r
-\r
-\r
-% Single-spacing is done by various environments (specifically, in\r
-% \nonfillstart and \quotations).\r
-\newskip\singlespaceskip \singlespaceskip = 12.5pt\r
-\def\singlespace{%\r
- % Why was this kern here? It messes up equalizing space above and below\r
- % environments. --karl, 6may93\r
- %{\advance \baselineskip by -\singlespaceskip\r
- %\kern \baselineskip}%\r
- \setleading \singlespaceskip\r
-}\r
-\r
-%% Simple single-character @ commands\r
-\r
-% @@ prints an @\r
-% Kludge this until the fonts are right (grr).\r
-\def\@{{\tt\char64}}\r
-\r
-% This is turned off because it was never documented\r
-% and you can use @w{...} around a quote to suppress ligatures.\r
-%% Define @` and @' to be the same as ` and '\r
-%% but suppressing ligatures.\r
-%\def\`{{`}}\r
-%\def\'{{'}}\r
-\r
-% Used to generate quoted braces.\r
-\def\mylbrace {{\tt\char123}}\r
-\def\myrbrace {{\tt\char125}}\r
-\let\{=\mylbrace\r
-\let\}=\myrbrace\r
-\begingroup\r
- % Definitions to produce actual \{ & \} command in an index.\r
- \catcode`\{ = 12 \catcode`\} = 12\r
- \catcode`\[ = 1 \catcode`\] = 2\r
- \catcode`\@ = 0 \catcode`\\ = 12\r
- @gdef@lbracecmd[\{]%\r
- @gdef@rbracecmd[\}]%\r
-@endgroup\r
-\r
-% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent\r
-% Others are defined by plain TeX: @` @' @" @^ @~ @= @v @H.\r
-\let\, = \c\r
-\let\dotaccent = \.\r
-\def\ringaccent#1{{\accent23 #1}}\r
-\let\tieaccent = \t\r
-\let\ubaraccent = \b\r
-\let\udotaccent = \d\r
-\r
-% Other special characters: @questiondown @exclamdown\r
-% Plain TeX defines: @AA @AE @O @OE @L (and lowercase versions) @ss.\r
-\def\questiondown{?`}\r
-\def\exclamdown{!`}\r
-\r
-% Dotless i and dotless j, used for accents.\r
-\def\imacro{i}\r
-\def\jmacro{j}\r
-\def\dotless#1{%\r
- \def\temp{#1}%\r
- \ifx\temp\imacro \ptexi\r
- \else\ifx\temp\jmacro \j\r
- \else \errmessage{@dotless can be used only with i or j}%\r
- \fi\fi\r
-}\r
-\r
-% Be sure we're in horizontal mode when doing a tie, since we make space\r
-% equivalent to this in @example-like environments. Otherwise, a space\r
-% at the beginning of a line will start with \penalty -- and\r
-% since \penalty is valid in vertical mode, we'd end up putting the\r
-% penalty on the vertical list instead of in the new paragraph.\r
-{\catcode`@ = 11\r
- % Avoid using \@M directly, because that causes trouble\r
- % if the definition is written into an index file.\r
- \global\let\tiepenalty = \@M\r
- \gdef\tie{\leavevmode\penalty\tiepenalty\ }\r
-}\r
-\r
-% @: forces normal size whitespace following.\r
-\def\:{\spacefactor=1000 }\r
-\r
-% @* forces a line break.\r
-\def\*{\hfil\break\hbox{}\ignorespaces}\r
-\r
-% @. is an end-of-sentence period.\r
-\def\.{.\spacefactor=3000 }\r
-\r
-% @! is an end-of-sentence bang.\r
-\def\!{!\spacefactor=3000 }\r
-\r
-% @? is an end-of-sentence query.\r
-\def\?{?\spacefactor=3000 }\r
-\r
-% @w prevents a word break. Without the \leavevmode, @w at the\r
-% beginning of a paragraph, when TeX is still in vertical mode, would\r
-% produce a whole line of output instead of starting the paragraph.\r
-\def\w#1{\leavevmode\hbox{#1}}\r
-\r
-% @group ... @end group forces ... to be all on one page, by enclosing\r
-% it in a TeX vbox. We use \vtop instead of \vbox to construct the box\r
-% to keep its height that of a normal line. According to the rules for\r
-% \topskip (p.114 of the TeXbook), the glue inserted is\r
-% max (\topskip - \ht (first item), 0). If that height is large,\r
-% therefore, no glue is inserted, and the space between the headline and\r
-% the text is small, which looks bad.\r
-%\r
-\def\group{\begingroup\r
- \ifnum\catcode13=\active \else\r
- \errhelp = \groupinvalidhelp\r
- \errmessage{@group invalid in context where filling is enabled}%\r
- \fi\r
- %\r
- % The \vtop we start below produces a box with normal height and large\r
- % depth; thus, TeX puts \baselineskip glue before it, and (when the\r
- % next line of text is done) \lineskip glue after it. (See p.82 of\r
- % the TeXbook.) Thus, space below is not quite equal to space\r
- % above. But it's pretty close.\r
- \def\Egroup{%\r
- \egroup % End the \vtop.\r
- \endgroup % End the \group.\r
- }%\r
- %\r
- \vtop\bgroup\r
- % We have to put a strut on the last line in case the @group is in\r
- % the midst of an example, rather than completely enclosing it.\r
- % Otherwise, the interline space between the last line of the group\r
- % and the first line afterwards is too small. But we can't put the\r
- % strut in \Egroup, since there it would be on a line by itself.\r
- % Hence this just inserts a strut at the beginning of each line.\r
- \everypar = {\strut}%\r
- %\r
- % Since we have a strut on every line, we don't need any of TeX's\r
- % normal interline spacing.\r
- \offinterlineskip\r
- %\r
- % OK, but now we have to do something about blank\r
- % lines in the input in @example-like environments, which normally\r
- % just turn into \lisppar, which will insert no space now that we've\r
- % turned off the interline space. Simplest is to make them be an\r
- % empty paragraph.\r
- \ifx\par\lisppar\r
- \edef\par{\leavevmode \par}%\r
- %\r
- % Reset ^^M's definition to new definition of \par.\r
- \obeylines\r
- \fi\r
- %\r
- % Do @comment since we are called inside an environment such as\r
- % @example, where each end-of-line in the input causes an\r
- % end-of-line in the output. We don't want the end-of-line after\r
- % the `@group' to put extra space in the output. Since @group\r
- % should appear on a line by itself (according to the Texinfo\r
- % manual), we don't worry about eating any user text.\r
- \comment\r
-}\r
-%\r
-% TeX puts in an \escapechar (i.e., `@') at the beginning of the help\r
-% message, so this ends up printing `@group can only ...'.\r
-%\r
-\newhelp\groupinvalidhelp{%\r
-group can only be used in environments such as @example,^^J%\r
-where each line of input produces a line of output.}\r
-\r
-% @need space-in-mils\r
-% forces a page break if there is not space-in-mils remaining.\r
-\r
-\newdimen\mil \mil=0.001in\r
-\r
-\def\need{\parsearg\needx}\r
-\r
-% Old definition--didn't work.\r
-%\def\needx #1{\par %\r
-%% This method tries to make TeX break the page naturally\r
-%% if the depth of the box does not fit.\r
-%{\baselineskip=0pt%\r
-%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak\r
-%\prevdepth=-1000pt\r
-%}}\r
-\r
-\def\needx#1{%\r
- % Ensure vertical mode, so we don't make a big box in the middle of a\r
- % paragraph.\r
- \par\r
- %\r
- % If the @need value is less than one line space, it's useless.\r
- \dimen0 = #1\mil\r
- \dimen2 = \ht\strutbox\r
- \advance\dimen2 by \dp\strutbox\r
- \ifdim\dimen0 > \dimen2\r
- %\r
- % Do a \strut just to make the height of this box be normal, so the\r
- % normal leading is inserted relative to the preceding line.\r
- % And a page break here is fine.\r
- \vtop to #1\mil{\strut\vfil}%\r
- %\r
- % TeX does not even consider page breaks if a penalty added to the\r
- % main vertical list is 10000 or more. But in order to see if the\r
- % empty box we just added fits on the page, we must make it consider\r
- % page breaks. On the other hand, we don't want to actually break the\r
- % page after the empty box. So we use a penalty of 9999.\r
- %\r
- % There is an extremely small chance that TeX will actually break the\r
- % page at this \penalty, if there are no other feasible breakpoints in\r
- % sight. (If the user is using lots of big @group commands, which\r
- % almost-but-not-quite fill up a page, TeX will have a hard time doing\r
- % good page breaking, for example.) However, I could not construct an\r
- % example where a page broke at this \penalty; if it happens in a real\r
- % document, then we can reconsider our strategy.\r
- \penalty9999\r
- %\r
- % Back up by the size of the box, whether we did a page break or not.\r
- \kern -#1\mil\r
- %\r
- % Do not allow a page break right after this kern.\r
- \nobreak\r
- \fi\r
-}\r
-\r
-% @br forces paragraph break\r
-\r
-\let\br = \par\r
-\r
-% @dots{} output an ellipsis using the current font.\r
-% We do .5em per period so that it has the same spacing in a typewriter\r
-% font as three actual period characters.\r
-%\r
-\def\dots{%\r
- \leavevmode\r
- \hbox to 1.5em{%\r
- \hskip 0pt plus 0.25fil minus 0.25fil\r
- .\hss.\hss.%\r
- \hskip 0pt plus 0.5fil minus 0.5fil\r
- }%\r
-}\r
-\r
-% @enddots{} is an end-of-sentence ellipsis.\r
-%\r
-\def\enddots{%\r
- \leavevmode\r
- \hbox to 2em{%\r
- \hskip 0pt plus 0.25fil minus 0.25fil\r
- .\hss.\hss.\hss.%\r
- \hskip 0pt plus 0.5fil minus 0.5fil\r
- }%\r
- \spacefactor=3000\r
-}\r
-\r
-\r
-% @page forces the start of a new page\r
-%\r
-\def\page{\par\vfill\supereject}\r
-\r
-% @exdent text....\r
-% outputs text on separate line in roman font, starting at standard page margin\r
-\r
-% This records the amount of indent in the innermost environment.\r
-% That's how much \exdent should take out.\r
-\newskip\exdentamount\r
-\r
-% This defn is used inside fill environments such as @defun.\r
-\def\exdent{\parsearg\exdentyyy}\r
-\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}}\r
-\r
-% This defn is used inside nofill environments such as @example.\r
-\def\nofillexdent{\parsearg\nofillexdentyyy}\r
-\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount\r
-\leftline{\hskip\leftskip{\rm#1}}}}\r
-\r
-% @inmargin{TEXT} puts TEXT in the margin next to the current paragraph.\r
-\r
-\def\inmargin#1{%\r
-\strut\vadjust{\nobreak\kern-\strutdepth\r
- \vtop to \strutdepth{\baselineskip\strutdepth\vss\r
- \llap{\rightskip=\inmarginspacing \vbox{\noindent #1}}\null}}}\r
-\newskip\inmarginspacing \inmarginspacing=1cm\r
-\def\strutdepth{\dp\strutbox}\r
-\r
-%\hbox{{\rm#1}}\hfil\break}}\r
-\r
-% @include file insert text of that file as input.\r
-% Allow normal characters that we make active in the argument (a file name).\r
-\def\include{\begingroup\r
- \catcode`\\=12\r
- \catcode`~=12\r
- \catcode`^=12\r
- \catcode`_=12\r
- \catcode`|=12\r
- \catcode`<=12\r
- \catcode`>=12\r
- \catcode`+=12\r
- \parsearg\includezzz}\r
-% Restore active chars for included file.\r
-\def\includezzz#1{\endgroup\begingroup\r
- % Read the included file in a group so nested @include's work.\r
- \def\thisfile{#1}%\r
- \input\thisfile\r
-\endgroup}\r
-\r
-\def\thisfile{}\r
-\r
-% @center line outputs that line, centered\r
-\r
-\def\center{\parsearg\centerzzz}\r
-\def\centerzzz #1{{\advance\hsize by -\leftskip\r
-\advance\hsize by -\rightskip\r
-\centerline{#1}}}\r
-\r
-% @sp n outputs n lines of vertical space\r
-\r
-\def\sp{\parsearg\spxxx}\r
-\def\spxxx #1{\vskip #1\baselineskip}\r
-\r
-% @comment ...line which is ignored...\r
-% @c is the same as @comment\r
-% @ignore ... @end ignore is another way to write a comment\r
-\r
-\def\comment{\begingroup \catcode`\^^M=\other%\r
-\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%\r
-\commentxxx}\r
-{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}\r
-\r
-\let\c=\comment\r
-\r
-% @paragraphindent NCHARS\r
-% We'll use ems for NCHARS, close enough.\r
-% We cannot implement @paragraphindent asis, though.\r
-% \r
-\def\asisword{asis} % no translation, these are keywords\r
-\def\noneword{none}\r
-%\r
-\def\paragraphindent{\parsearg\doparagraphindent}\r
-\def\doparagraphindent#1{%\r
- \def\temp{#1}%\r
- \ifx\temp\asisword\r
- \else\r
- \ifx\temp\noneword\r
- \defaultparindent = 0pt\r
- \else\r
- \defaultparindent = #1em\r
- \fi\r
- \fi\r
- \parindent = \defaultparindent\r
-}\r
-\r
-% @exampleindent NCHARS\r
-% We'll use ems for NCHARS like @paragraphindent.\r
-% It seems @exampleindent asis isn't necessary, but\r
-% I preserve it to make it similar to @paragraphindent.\r
-\def\exampleindent{\parsearg\doexampleindent}\r
-\def\doexampleindent#1{%\r
- \def\temp{#1}%\r
- \ifx\temp\asisword\r
- \else\r
- \ifx\temp\noneword\r
- \lispnarrowing = 0pt\r
- \else\r
- \lispnarrowing = #1em\r
- \fi\r
- \fi\r
-}\r
-\r
-% @asis just yields its argument. Used with @table, for example.\r
-%\r
-\def\asis#1{#1}\r
-\r
-% @math means output in math mode.\r
-% We don't use $'s directly in the definition of \math because control\r
-% sequences like \math are expanded when the toc file is written. Then,\r
-% we read the toc file back, the $'s will be normal characters (as they\r
-% should be, according to the definition of Texinfo). So we must use a\r
-% control sequence to switch into and out of math mode.\r
-%\r
-% This isn't quite enough for @math to work properly in indices, but it\r
-% seems unlikely it will ever be needed there.\r
-%\r
-\let\implicitmath = $\r
-\def\math#1{\implicitmath #1\implicitmath}\r
-\r
-% @bullet and @minus need the same treatment as @math, just above.\r
-\def\bullet{\implicitmath\ptexbullet\implicitmath}\r
-\def\minus{\implicitmath-\implicitmath}\r
-\r
-% @refill is a no-op.\r
-\let\refill=\relax\r
-\r
-% If working on a large document in chapters, it is convenient to\r
-% be able to disable indexing, cross-referencing, and contents, for test runs.\r
-% This is done with @novalidate (before @setfilename).\r
-%\r
-\newif\iflinks \linkstrue % by default we want the aux files.\r
-\let\novalidate = \linksfalse\r
-\r
-% @setfilename is done at the beginning of every texinfo file.\r
-% So open here the files we need to have open while reading the input.\r
-% This makes it possible to make a .fmt file for texinfo.\r
-\def\setfilename{%\r
- \iflinks\r
- \readauxfile\r
- \fi % \openindices needs to do some work in any case.\r
- \openindices\r
- \fixbackslash % Turn off hack to swallow `\input texinfo'.\r
- \global\let\setfilename=\comment % Ignore extra @setfilename cmds.\r
- %\r
- % If texinfo.cnf is present on the system, read it.\r
- % Useful for site-wide @afourpaper, etc.\r
- % Just to be on the safe side, close the input stream before the \input.\r
- \openin 1 texinfo.cnf\r
- \ifeof1 \let\temp=\relax \else \def\temp{\input texinfo.cnf }\fi\r
- \closein1\r
- \temp\r
- %\r
- \comment % Ignore the actual filename.\r
-}\r
-\r
-% Called from \setfilename.\r
-%\r
-\def\openindices{%\r
- \newindex{cp}%\r
- \newcodeindex{fn}%\r
- \newcodeindex{vr}%\r
- \newcodeindex{tp}%\r
- \newcodeindex{ky}%\r
- \newcodeindex{pg}%\r
-}\r
-\r
-% @bye.\r
-\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}\r
-\r
-\r
-\message{pdf,}\r
-% adobe `portable' document format\r
-\newcount\tempnum\r
-\newcount\lnkcount\r
-\newtoks\filename\r
-\newcount\filenamelength\r
-\newcount\pgn\r
-\newtoks\toksA\r
-\newtoks\toksB\r
-\newtoks\toksC\r
-\newtoks\toksD\r
-\newbox\boxA\r
-\newcount\countA\r
-\newif\ifpdf\r
-\newif\ifpdfmakepagedest\r
-\r
-\ifx\pdfoutput\undefined\r
- \pdffalse\r
- \let\pdfmkdest = \gobble\r
- \let\pdfurl = \gobble\r
- \let\endlink = \relax\r
- \let\linkcolor = \relax\r
- \let\pdfmakeoutlines = \relax\r
-\else\r
- \pdftrue\r
- \pdfoutput = 1\r
- \input pdfcolor\r
- \def\dopdfimage#1#2#3{%\r
- \def\imagewidth{#2}%\r
- \def\imageheight{#3}%\r
- \ifnum\pdftexversion < 14\r
- \pdfimage\r
- \else\r
- \pdfximage\r
- \fi\r
- \ifx\empty\imagewidth\else width \imagewidth \fi\r
- \ifx\empty\imageheight\else height \imageheight \fi\r
- {#1.pdf}%\r
- \ifnum\pdftexversion < 14 \else\r
- \pdfrefximage \pdflastximage\r
- \fi}\r
- \def\pdfmkdest#1{\pdfdest name{#1@} xyz}\r
- \def\pdfmkpgn#1{#1@}\r
- \let\linkcolor = \Blue % was Cyan, but that seems light?\r
- \def\endlink{\Black\pdfendlink}\r
- % Adding outlines to PDF; macros for calculating structure of outlines\r
- % come from Petr Olsak\r
- \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%\r
- \else \csname#1\endcsname \fi}\r
- \def\advancenumber#1{\tempnum=\expnumber{#1}\relax\r
- \advance\tempnum by1\r
- \expandafter\xdef\csname#1\endcsname{\the\tempnum}}\r
- \def\pdfmakeoutlines{{%\r
- \openin 1 \jobname.toc\r
- \ifeof 1\else\bgroup\r
- \closein 1 \r
- \indexnofonts\r
- \def\tt{}\r
- \let\_ = \normalunderscore\r
- % Thanh's hack / proper braces in bookmarks \r
- \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace\r
- \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace\r
- %\r
- \def\chapentry ##1##2##3{}\r
- \def\unnumbchapentry ##1##2{}\r
- \def\secentry ##1##2##3##4{\advancenumber{chap##2}}\r
- \def\unnumbsecentry ##1##2{}\r
- \def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}}\r
- \def\unnumbsubsecentry ##1##2{}\r
- \def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}}\r
- \def\unnumbsubsubsecentry ##1##2{}\r
- \input \jobname.toc\r
- \def\chapentry ##1##2##3{%\r
- \pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}}\r
- \def\unnumbchapentry ##1##2{%\r
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}\r
- \def\secentry ##1##2##3##4{%\r
- \pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}}\r
- \def\unnumbsecentry ##1##2{%\r
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}\r
- \def\subsecentry ##1##2##3##4##5{%\r
- \pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}}\r
- \def\unnumbsubsecentry ##1##2{%\r
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}\r
- \def\subsubsecentry ##1##2##3##4##5##6{%\r
- \pdfoutline goto name{\pdfmkpgn{##6}}{##1}}\r
- \def\unnumbsubsubsecentry ##1##2{%\r
- \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}\r
- \input \jobname.toc\r
- \egroup\fi\r
- }}\r
- \def\makelinks #1,{%\r
- \def\params{#1}\def\E{END}%\r
- \ifx\params\E\r
- \let\nextmakelinks=\relax\r
- \else\r
- \let\nextmakelinks=\makelinks\r
- \ifnum\lnkcount>0,\fi\r
- \picknum{#1}%\r
- \startlink attr{/Border [0 0 0]} \r
- goto name{\pdfmkpgn{\the\pgn}}%\r
- \linkcolor #1%\r
- \advance\lnkcount by 1%\r
- \endlink\r
- \fi\r
- \nextmakelinks\r
- }\r
- \def\picknum#1{\expandafter\pn#1}\r
- \def\pn#1{%\r
- \def\p{#1}%\r
- \ifx\p\lbrace\r
- \let\nextpn=\ppn\r
- \else\r
- \let\nextpn=\ppnn\r
- \def\first{#1}\r
- \fi\r
- \nextpn\r
- }\r
- \def\ppn#1{\pgn=#1\gobble}\r
- \def\ppnn{\pgn=\first}\r
- \def\pdfmklnk#1{\lnkcount=0\makelinks #1,END,}\r
- \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}\r
- \def\skipspaces#1{\def\PP{#1}\def\D{|}%\r
- \ifx\PP\D\let\nextsp\relax\r
- \else\let\nextsp\skipspaces\r
- \ifx\p\space\else\addtokens{\filename}{\PP}%\r
- \advance\filenamelength by 1\r
- \fi\r
- \fi\r
- \nextsp}\r
- \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax}\r
- \ifnum\pdftexversion < 14\r
- \let \startlink \pdfannotlink\r
- \else\r
- \let \startlink \pdfstartlink\r
- \fi\r
- \def\pdfurl#1{%\r
- \begingroup\r
- \normalturnoffactive\def\@{@}%\r
- \leavevmode\Red\r
- \startlink attr{/Border [0 0 0]}%\r
- user{/Subtype /Link /A << /S /URI /URI (#1) >>}%\r
- % #1\r
- \endgroup}\r
- \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}\r
- \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}\r
- \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}\r
- \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}\r
- \def\maketoks{%\r
- \expandafter\poptoks\the\toksA|ENDTOKS|\r
- \ifx\first0\adn0\r
- \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3\r
- \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6\r
- \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 \r
- \else\r
- \ifnum0=\countA\else\makelink\fi\r
- \ifx\first.\let\next=\done\else\r
- \let\next=\maketoks\r
- \addtokens{\toksB}{\the\toksD}\r
- \ifx\first,\addtokens{\toksB}{\space}\fi\r
- \fi\r
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\r
- \next}\r
- \def\makelink{\addtokens{\toksB}%\r
- {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}\r
- \def\pdflink#1{%\r
- \startlink attr{/Border [0 0 0]} goto name{\mkpgn{#1}}\r
- \linkcolor #1\endlink}\r
- \def\mkpgn#1{#1@} \r
- \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}\r
-\fi % \ifx\pdfoutput\r
-\r
-\r
-\message{fonts,}\r
-% Font-change commands.\r
-\r
-% Texinfo sort of supports the sans serif font style, which plain TeX does not.\r
-% So we set up a \sf analogous to plain's \rm, etc.\r
-\newfam\sffam\r
-\def\sf{\fam=\sffam \tensf}\r
-\let\li = \sf % Sometimes we call it \li, not \sf.\r
-\r
-% We don't need math for this one.\r
-\def\ttsl{\tenttsl}\r
-\r
-% Use Computer Modern fonts at \magstephalf (11pt).\r
-\newcount\mainmagstep\r
-\mainmagstep=\magstephalf\r
-\r
-% Set the font macro #1 to the font named #2, adding on the\r
-% specified font prefix (normally `cm').\r
-% #3 is the font's design size, #4 is a scale factor\r
-\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4}\r
-\r
-% Use cm as the default font prefix.\r
-% To specify the font prefix, you must define \fontprefix\r
-% before you read in texinfo.tex.\r
-\ifx\fontprefix\undefined\r
-\def\fontprefix{cm}\r
-\fi\r
-% Support font families that don't use the same naming scheme as CM.\r
-\def\rmshape{r}\r
-\def\rmbshape{bx} %where the normal face is bold\r
-\def\bfshape{b}\r
-\def\bxshape{bx}\r
-\def\ttshape{tt}\r
-\def\ttbshape{tt}\r
-\def\ttslshape{sltt}\r
-\def\itshape{ti}\r
-\def\itbshape{bxti}\r
-\def\slshape{sl}\r
-\def\slbshape{bxsl}\r
-\def\sfshape{ss}\r
-\def\sfbshape{ss}\r
-\def\scshape{csc}\r
-\def\scbshape{csc}\r
-\r
-\ifx\bigger\relax\r
-\let\mainmagstep=\magstep1\r
-\setfont\textrm\rmshape{12}{1000}\r
-\setfont\texttt\ttshape{12}{1000}\r
-\else\r
-\setfont\textrm\rmshape{10}{\mainmagstep}\r
-\setfont\texttt\ttshape{10}{\mainmagstep}\r
-\fi\r
-% Instead of cmb10, you many want to use cmbx10.\r
-% cmbx10 is a prettier font on its own, but cmb10\r
-% looks better when embedded in a line with cmr10.\r
-\setfont\textbf\bfshape{10}{\mainmagstep}\r
-\setfont\textit\itshape{10}{\mainmagstep}\r
-\setfont\textsl\slshape{10}{\mainmagstep}\r
-\setfont\textsf\sfshape{10}{\mainmagstep}\r
-\setfont\textsc\scshape{10}{\mainmagstep}\r
-\setfont\textttsl\ttslshape{10}{\mainmagstep}\r
-\font\texti=cmmi10 scaled \mainmagstep\r
-\font\textsy=cmsy10 scaled \mainmagstep\r
-\r
-% A few fonts for @defun, etc.\r
-\setfont\defbf\bxshape{10}{\magstep1} %was 1314\r
-\setfont\deftt\ttshape{10}{\magstep1}\r
-\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf}\r
-\r
-% Fonts for indices, footnotes, small examples (9pt).\r
-\setfont\smallrm\rmshape{9}{1000}\r
-\setfont\smalltt\ttshape{9}{1000}\r
-\setfont\smallbf\bfshape{10}{900}\r
-\setfont\smallit\itshape{9}{1000}\r
-\setfont\smallsl\slshape{9}{1000}\r
-\setfont\smallsf\sfshape{9}{1000}\r
-\setfont\smallsc\scshape{10}{900}\r
-\setfont\smallttsl\ttslshape{10}{900}\r
-\font\smalli=cmmi9\r
-\font\smallsy=cmsy9\r
-\r
-% Fonts for title page:\r
-\setfont\titlerm\rmbshape{12}{\magstep3}\r
-\setfont\titleit\itbshape{10}{\magstep4}\r
-\setfont\titlesl\slbshape{10}{\magstep4}\r
-\setfont\titlett\ttbshape{12}{\magstep3}\r
-\setfont\titlettsl\ttslshape{10}{\magstep4}\r
-\setfont\titlesf\sfbshape{17}{\magstep1}\r
-\let\titlebf=\titlerm\r
-\setfont\titlesc\scbshape{10}{\magstep4}\r
-\font\titlei=cmmi12 scaled \magstep3\r
-\font\titlesy=cmsy10 scaled \magstep4\r
-\def\authorrm{\secrm}\r
-\r
-% Chapter (and unnumbered) fonts (17.28pt).\r
-\setfont\chaprm\rmbshape{12}{\magstep2}\r
-\setfont\chapit\itbshape{10}{\magstep3}\r
-\setfont\chapsl\slbshape{10}{\magstep3}\r
-\setfont\chaptt\ttbshape{12}{\magstep2}\r
-\setfont\chapttsl\ttslshape{10}{\magstep3}\r
-\setfont\chapsf\sfbshape{17}{1000}\r
-\let\chapbf=\chaprm\r
-\setfont\chapsc\scbshape{10}{\magstep3}\r
-\font\chapi=cmmi12 scaled \magstep2\r
-\font\chapsy=cmsy10 scaled \magstep3\r
-\r
-% Section fonts (14.4pt).\r
-\setfont\secrm\rmbshape{12}{\magstep1}\r
-\setfont\secit\itbshape{10}{\magstep2}\r
-\setfont\secsl\slbshape{10}{\magstep2}\r
-\setfont\sectt\ttbshape{12}{\magstep1}\r
-\setfont\secttsl\ttslshape{10}{\magstep2}\r
-\setfont\secsf\sfbshape{12}{\magstep1}\r
-\let\secbf\secrm\r
-\setfont\secsc\scbshape{10}{\magstep2}\r
-\font\seci=cmmi12 scaled \magstep1\r
-\font\secsy=cmsy10 scaled \magstep2\r
-\r
-% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad.\r
-% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded.\r
-% \setfont\ssecsl\slshape{10}{\magstep1}\r
-% \setfont\ssectt\ttshape{10}{\magstep1}\r
-% \setfont\ssecsf\sfshape{10}{\magstep1}\r
-\r
-%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx.\r
-%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than\r
-%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1.\r
-%\setfont\ssectt\ttshape{10}{1315}\r
-%\setfont\ssecsf\sfshape{10}{1315}\r
-\r
-%\let\ssecbf=\ssecrm\r
-\r
-% Subsection fonts (13.15pt).\r
-\setfont\ssecrm\rmbshape{12}{\magstephalf}\r
-\setfont\ssecit\itbshape{10}{1315}\r
-\setfont\ssecsl\slbshape{10}{1315}\r
-\setfont\ssectt\ttbshape{12}{\magstephalf}\r
-\setfont\ssecttsl\ttslshape{10}{1315}\r
-\setfont\ssecsf\sfbshape{12}{\magstephalf}\r
-\let\ssecbf\ssecrm\r
-\setfont\ssecsc\scbshape{10}{\magstep1}\r
-\font\sseci=cmmi12 scaled \magstephalf\r
-\font\ssecsy=cmsy10 scaled 1315\r
-% The smallcaps and symbol fonts should actually be scaled \magstep1.5,\r
-% but that is not a standard magnification.\r
-\r
-% In order for the font changes to affect most math symbols and letters,\r
-% we have to define the \textfont of the standard families. Since\r
-% texinfo doesn't allow for producing subscripts and superscripts, we\r
-% don't bother to reset \scriptfont and \scriptscriptfont (which would\r
-% also require loading a lot more fonts).\r
-%\r
-\def\resetmathfonts{%\r
- \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy\r
- \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf\r
- \textfont\ttfam = \tentt \textfont\sffam = \tensf\r
-}\r
-\r
-\r
-% The font-changing commands redefine the meanings of \tenSTYLE, instead\r
-% of just \STYLE. We do this so that font changes will continue to work\r
-% in math mode, where it is the current \fam that is relevant in most\r
-% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam\r
-% \tenbf}, for example. By redefining \tenbf, we obviate the need to\r
-% redefine \bf itself.\r
-\def\textfonts{%\r
- \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl\r
- \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc\r
- \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl\r
- \resetmathfonts}\r
-\def\titlefonts{%\r
- \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl\r
- \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc\r
- \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy\r
- \let\tenttsl=\titlettsl\r
- \resetmathfonts \setleading{25pt}}\r
-\def\titlefont#1{{\titlefonts\rm #1}}\r
-\def\chapfonts{%\r
- \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl\r
- \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc\r
- \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl\r
- \resetmathfonts \setleading{19pt}}\r
-\def\secfonts{%\r
- \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl\r
- \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc\r
- \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl\r
- \resetmathfonts \setleading{16pt}}\r
-\def\subsecfonts{%\r
- \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl\r
- \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc\r
- \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl\r
- \resetmathfonts \setleading{15pt}}\r
-\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf?\r
-\def\smallfonts{%\r
- \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl\r
- \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc\r
- \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy\r
- \let\tenttsl=\smallttsl\r
- \resetmathfonts \setleading{11pt}}\r
-\r
-% Set up the default fonts, so we can use them for creating boxes.\r
-%\r
-\textfonts\r
-\r
-% Define these so they can be easily changed for other fonts.\r
-\def\angleleft{$\langle$}\r
-\def\angleright{$\rangle$}\r
-\r
-% Count depth in font-changes, for error checks\r
-\newcount\fontdepth \fontdepth=0\r
-\r
-% Fonts for short table of contents.\r
-\setfont\shortcontrm\rmshape{12}{1000}\r
-\setfont\shortcontbf\bxshape{12}{1000}\r
-\setfont\shortcontsl\slshape{12}{1000}\r
-\r
-%% Add scribe-like font environments, plus @l for inline lisp (usually sans\r
-%% serif) and @ii for TeX italic\r
-\r
-% \smartitalic{ARG} outputs arg in italics, followed by an italic correction\r
-% unless the following character is such as not to need one.\r
-\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi}\r
-\def\smartslanted#1{{\sl #1}\futurelet\next\smartitalicx}\r
-\def\smartitalic#1{{\it #1}\futurelet\next\smartitalicx}\r
-\r
-\let\i=\smartitalic\r
-\let\var=\smartslanted\r
-\let\dfn=\smartslanted\r
-\let\emph=\smartitalic\r
-\let\cite=\smartslanted\r
-\r
-\def\b#1{{\bf #1}}\r
-\let\strong=\b\r
-\r
-% We can't just use \exhyphenpenalty, because that only has effect at\r
-% the end of a paragraph. Restore normal hyphenation at the end of the\r
-% group within which \nohyphenation is presumably called.\r
-%\r
-\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation}\r
-\def\restorehyphenation{\hyphenchar\font = `- }\r
-\r
-\def\t#1{%\r
- {\tt \rawbackslash \frenchspacing #1}%\r
- \null\r
-}\r
-\let\ttfont=\t\r
-\def\samp#1{`\tclose{#1}'\null}\r
-\setfont\keyrm\rmshape{8}{1000}\r
-\font\keysy=cmsy9\r
-\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%\r
- \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%\r
- \vbox{\hrule\kern-0.4pt\r
- \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%\r
- \kern-0.4pt\hrule}%\r
- \kern-.06em\raise0.4pt\hbox{\angleright}}}}\r
-% The old definition, with no lozenge:\r
-%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null}\r
-\def\ctrl #1{{\tt \rawbackslash \hat}#1}\r
-\r
-% @file, @option are the same as @samp.\r
-\let\file=\samp\r
-\let\option=\samp\r
-\r
-% @code is a modification of @t,\r
-% which makes spaces the same size as normal in the surrounding text.\r
-\def\tclose#1{%\r
- {%\r
- % Change normal interword space to be same as for the current font.\r
- \spaceskip = \fontdimen2\font\r
- %\r
- % Switch to typewriter.\r
- \tt\r
- %\r
- % But `\ ' produces the large typewriter interword space.\r
- \def\ {{\spaceskip = 0pt{} }}%\r
- %\r
- % Turn off hyphenation.\r
- \nohyphenation\r
- %\r
- \rawbackslash\r
- \frenchspacing\r
- #1%\r
- }%\r
- \null\r
-}\r
-\r
-% We *must* turn on hyphenation at `-' and `_' in \code.\r
-% Otherwise, it is too hard to avoid overfull hboxes\r
-% in the Emacs manual, the Library manual, etc.\r
-\r
-% Unfortunately, TeX uses one parameter (\hyphenchar) to control\r
-% both hyphenation at - and hyphenation within words.\r
-% We must therefore turn them both off (\tclose does that)\r
-% and arrange explicitly to hyphenate at a dash.\r
-% -- rms.\r
-{\r
- \catcode`\-=\active\r
- \catcode`\_=\active\r
- %\r
- \global\def\code{\begingroup\r
- \catcode`\-=\active \let-\codedash\r
- \catcode`\_=\active \let_\codeunder\r
- \codex\r
- }\r
- %\r
- % If we end up with any active - characters when handling the index,\r
- % just treat them as a normal -.\r
- \global\def\indexbreaks{\catcode`\-=\active \let-\realdash}\r
-}\r
-\r
-\def\realdash{-}\r
-\def\codedash{-\discretionary{}{}{}}\r
-\def\codeunder{\ifusingtt{\normalunderscore\discretionary{}{}{}}{\_}}\r
-\def\codex #1{\tclose{#1}\endgroup}\r
-\r
-%\let\exp=\tclose %Was temporary\r
-\r
-% @kbd is like @code, except that if the argument is just one @key command,\r
-% then @kbd has no effect.\r
-\r
-% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),\r
-% `example' (@kbd uses ttsl only inside of @example and friends),\r
-% or `code' (@kbd uses normal tty font always).\r
-\def\kbdinputstyle{\parsearg\kbdinputstylexxx}\r
-\def\kbdinputstylexxx#1{%\r
- \def\arg{#1}%\r
- \ifx\arg\worddistinct\r
- \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%\r
- \else\ifx\arg\wordexample\r
- \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%\r
- \else\ifx\arg\wordcode\r
- \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%\r
- \fi\fi\fi\r
-}\r
-\def\worddistinct{distinct}\r
-\def\wordexample{example}\r
-\def\wordcode{code}\r
-\r
-% Default is kbdinputdistinct. (Too much of a hassle to call the macro,\r
-% the catcodes are wrong for parsearg to work.)\r
-\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}\r
-\r
-\def\xkey{\key}\r
-\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%\r
-\ifx\one\xkey\ifx\threex\three \key{#2}%\r
-\else{\tclose{\kbdfont\look}}\fi\r
-\else{\tclose{\kbdfont\look}}\fi}\r
-\r
-% For @url, @env, @command quotes seem unnecessary, so use \code.\r
-\let\url=\code\r
-\let\env=\code\r
-\let\command=\code\r
-\r
-% @uref (abbreviation for `urlref') takes an optional (comma-separated)\r
-% second argument specifying the text to display and an optional third\r
-% arg as text to display instead of (rather than in addition to) the url\r
-% itself. First (mandatory) arg is the url. Perhaps eventually put in\r
-% a hypertex \special here.\r
-%\r
-\def\uref#1{\douref #1,,,\finish}\r
-\def\douref#1,#2,#3,#4\finish{\begingroup\r
- \unsepspaces\r
- \pdfurl{#1}%\r
- \setbox0 = \hbox{\ignorespaces #3}%\r
- \ifdim\wd0 > 0pt\r
- \unhbox0 % third arg given, show only that\r
- \else\r
- \setbox0 = \hbox{\ignorespaces #2}%\r
- \ifdim\wd0 > 0pt\r
- \ifpdf\r
- \unhbox0 % PDF: 2nd arg given, show only it\r
- \else\r
- \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url\r
- \fi\r
- \else\r
- \code{#1}% only url given, so show it\r
- \fi\r
- \fi\r
- \endlink\r
-\endgroup}\r
-\r
-% rms does not like angle brackets --karl, 17may97.\r
-% So now @email is just like @uref, unless we are pdf.\r
-% \r
-%\def\email#1{\angleleft{\tt #1}\angleright}\r
-\ifpdf\r
- \def\email#1{\doemail#1,,\finish}\r
- \def\doemail#1,#2,#3\finish{\begingroup\r
- \unsepspaces\r
- \pdfurl{mailto:#1}%\r
- \setbox0 = \hbox{\ignorespaces #2}%\r
- \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi\r
- \endlink\r
- \endgroup}\r
-\else\r
- \let\email=\uref\r
-\fi\r
-\r
-% Check if we are currently using a typewriter font. Since all the\r
-% Computer Modern typewriter fonts have zero interword stretch (and\r
-% shrink), and it is reasonable to expect all typewriter fonts to have\r
-% this property, we can check that font parameter.\r
-%\r
-\def\ifmonospace{\ifdim\fontdimen3\font=0pt }\r
-\r
-% Typeset a dimension, e.g., `in' or `pt'. The only reason for the\r
-% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.\r
-%\r
-\def\dmn#1{\thinspace #1}\r
-\r
-\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par}\r
-\r
-% @l was never documented to mean ``switch to the Lisp font'',\r
-% and it is not used as such in any manual I can find. We need it for\r
-% Polish suppressed-l. --karl, 22sep96.\r
-%\def\l#1{{\li #1}\null}\r
-\r
-% Explicit font changes: @r, @sc, undocumented @ii.\r
-\def\r#1{{\rm #1}} % roman font\r
-\def\sc#1{{\smallcaps#1}} % smallcaps font\r
-\def\ii#1{{\it #1}} % italic font\r
-\r
-% @acronym downcases the argument and prints in smallcaps.\r
-\def\acronym#1{{\smallcaps \lowercase{#1}}}\r
-\r
-% @pounds{} is a sterling sign.\r
-\def\pounds{{\it\$}}\r
-\r
-\r
-\message{page headings,}\r
-\r
-\newskip\titlepagetopglue \titlepagetopglue = 1.5in\r
-\newskip\titlepagebottomglue \titlepagebottomglue = 2pc\r
-\r
-% First the title page. Must do @settitle before @titlepage.\r
-\newif\ifseenauthor\r
-\newif\iffinishedtitlepage\r
-\r
-% Do an implicit @contents or @shortcontents after @end titlepage if the\r
-% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.\r
-%\r
-\newif\ifsetcontentsaftertitlepage\r
- \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue\r
-\newif\ifsetshortcontentsaftertitlepage\r
- \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue\r
-\r
-\def\shorttitlepage{\parsearg\shorttitlepagezzz}\r
-\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}%\r
- \endgroup\page\hbox{}\page}\r
-\r
-\def\titlepage{\begingroup \parindent=0pt \textfonts\r
- \let\subtitlerm=\tenrm\r
- \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}%\r
- %\r
- \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}%\r
- %\r
- % Leave some space at the very top of the page.\r
- \vglue\titlepagetopglue\r
- %\r
- % Now you can print the title using @title.\r
- \def\title{\parsearg\titlezzz}%\r
- \def\titlezzz##1{\leftline{\titlefonts\rm ##1}\r
- % print a rule at the page bottom also.\r
- \finishedtitlepagefalse\r
- \vskip4pt \hrule height 4pt width \hsize \vskip4pt}%\r
- % No rule at page bottom unless we print one at the top with @title.\r
- \finishedtitlepagetrue\r
- %\r
- % Now you can put text using @subtitle.\r
- \def\subtitle{\parsearg\subtitlezzz}%\r
- \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}%\r
- %\r
- % @author should come last, but may come many times.\r
- \def\author{\parsearg\authorzzz}%\r
- \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi\r
- {\authorfont \leftline{##1}}}%\r
- %\r
- % Most title ``pages'' are actually two pages long, with space\r
- % at the top of the second. We don't want the ragged left on the second.\r
- \let\oldpage = \page\r
- \def\page{%\r
- \iffinishedtitlepage\else\r
- \finishtitlepage\r
- \fi\r
- \oldpage\r
- \let\page = \oldpage\r
- \hbox{}}%\r
-% \def\page{\oldpage \hbox{}}\r
-}\r
-\r
-\def\Etitlepage{%\r
- \iffinishedtitlepage\else\r
- \finishtitlepage\r
- \fi\r
- % It is important to do the page break before ending the group,\r
- % because the headline and footline are only empty inside the group.\r
- % If we use the new definition of \page, we always get a blank page\r
- % after the title page, which we certainly don't want.\r
- \oldpage\r
- \endgroup\r
- %\r
- % If they want short, they certainly want long too.\r
- \ifsetshortcontentsaftertitlepage\r
- \shortcontents\r
- \contents\r
- \global\let\shortcontents = \relax\r
- \global\let\contents = \relax\r
- \fi\r
- %\r
- \ifsetcontentsaftertitlepage\r
- \contents\r
- \global\let\contents = \relax\r
- \global\let\shortcontents = \relax\r
- \fi\r
- %\r
- \ifpdf \pdfmakepagedesttrue \fi\r
- %\r
- \HEADINGSon\r
-}\r
-\r
-\def\finishtitlepage{%\r
- \vskip4pt \hrule height 2pt width \hsize\r
- \vskip\titlepagebottomglue\r
- \finishedtitlepagetrue\r
-}\r
-\r
-%%% Set up page headings and footings.\r
-\r
-\let\thispage=\folio\r
-\r
-\newtoks\evenheadline % headline on even pages\r
-\newtoks\oddheadline % headline on odd pages\r
-\newtoks\evenfootline % footline on even pages\r
-\newtoks\oddfootline % footline on odd pages\r
-\r
-% Now make Tex use those variables\r
-\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline\r
- \else \the\evenheadline \fi}}\r
-\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline\r
- \else \the\evenfootline \fi}\HEADINGShook}\r
-\let\HEADINGShook=\relax\r
-\r
-% Commands to set those variables.\r
-% For example, this is what @headings on does\r
-% @evenheading @thistitle|@thispage|@thischapter\r
-% @oddheading @thischapter|@thispage|@thistitle\r
-% @evenfooting @thisfile||\r
-% @oddfooting ||@thisfile\r
-\r
-\def\evenheading{\parsearg\evenheadingxxx}\r
-\def\oddheading{\parsearg\oddheadingxxx}\r
-\def\everyheading{\parsearg\everyheadingxxx}\r
-\r
-\def\evenfooting{\parsearg\evenfootingxxx}\r
-\def\oddfooting{\parsearg\oddfootingxxx}\r
-\def\everyfooting{\parsearg\everyfootingxxx}\r
-\r
-{\catcode`\@=0 %\r
-\r
-\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish}\r
-\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{%\r
-\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}\r
-\r
-\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish}\r
-\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{%\r
-\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}\r
-\r
-\gdef\everyheadingxxx#1{\oddheadingxxx{#1}\evenheadingxxx{#1}}%\r
-\r
-\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish}\r
-\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{%\r
-\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}\r
-\r
-\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish}\r
-\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{%\r
- \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%\r
- %\r
- % Leave some space for the footline. Hopefully ok to assume\r
- % @evenfooting will not be used by itself.\r
- \global\advance\pageheight by -\baselineskip\r
- \global\advance\vsize by -\baselineskip\r
-}\r
-\r
-\gdef\everyfootingxxx#1{\oddfootingxxx{#1}\evenfootingxxx{#1}}\r
-%\r
-}% unbind the catcode of @.\r
-\r
-% @headings double turns headings on for double-sided printing.\r
-% @headings single turns headings on for single-sided printing.\r
-% @headings off turns them off.\r
-% @headings on same as @headings double, retained for compatibility.\r
-% @headings after turns on double-sided headings after this page.\r
-% @headings doubleafter turns on double-sided headings after this page.\r
-% @headings singleafter turns on single-sided headings after this page.\r
-% By default, they are off at the start of a document,\r
-% and turned `on' after @end titlepage.\r
-\r
-\def\headings #1 {\csname HEADINGS#1\endcsname}\r
-\r
-\def\HEADINGSoff{\r
-\global\evenheadline={\hfil} \global\evenfootline={\hfil}\r
-\global\oddheadline={\hfil} \global\oddfootline={\hfil}}\r
-\HEADINGSoff\r
-% When we turn headings on, set the page number to 1.\r
-% For double-sided printing, put current file name in lower left corner,\r
-% chapter name on inside top of right hand pages, document\r
-% title on inside top of left hand pages, and page numbers on outside top\r
-% edge of all pages.\r
-\def\HEADINGSdouble{\r
-\global\pageno=1\r
-\global\evenfootline={\hfil}\r
-\global\oddfootline={\hfil}\r
-\global\evenheadline={\line{\folio\hfil\thistitle}}\r
-\global\oddheadline={\line{\thischapter\hfil\folio}}\r
-\global\let\contentsalignmacro = \chapoddpage\r
-}\r
-\let\contentsalignmacro = \chappager\r
-\r
-% For single-sided printing, chapter title goes across top left of page,\r
-% page number on top right.\r
-\def\HEADINGSsingle{\r
-\global\pageno=1\r
-\global\evenfootline={\hfil}\r
-\global\oddfootline={\hfil}\r
-\global\evenheadline={\line{\thischapter\hfil\folio}}\r
-\global\oddheadline={\line{\thischapter\hfil\folio}}\r
-\global\let\contentsalignmacro = \chappager\r
-}\r
-\def\HEADINGSon{\HEADINGSdouble}\r
-\r
-\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}\r
-\let\HEADINGSdoubleafter=\HEADINGSafter\r
-\def\HEADINGSdoublex{%\r
-\global\evenfootline={\hfil}\r
-\global\oddfootline={\hfil}\r
-\global\evenheadline={\line{\folio\hfil\thistitle}}\r
-\global\oddheadline={\line{\thischapter\hfil\folio}}\r
-\global\let\contentsalignmacro = \chapoddpage\r
-}\r
-\r
-\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}\r
-\def\HEADINGSsinglex{%\r
-\global\evenfootline={\hfil}\r
-\global\oddfootline={\hfil}\r
-\global\evenheadline={\line{\thischapter\hfil\folio}}\r
-\global\oddheadline={\line{\thischapter\hfil\folio}}\r
-\global\let\contentsalignmacro = \chappager\r
-}\r
-\r
-% Subroutines used in generating headings\r
-% This produces Day Month Year style of output.\r
-% Only define if not already defined, in case a txi-??.tex file has set\r
-% up a different format (e.g., txi-cs.tex does this).\r
-\ifx\today\undefined\r
-\def\today{%\r
- \number\day\space\r
- \ifcase\month\r
- \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr\r
- \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug\r
- \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec\r
- \fi\r
- \space\number\year}\r
-\fi\r
-\r
-% @settitle line... specifies the title of the document, for headings.\r
-% It generates no output of its own.\r
-\def\thistitle{\putwordNoTitle}\r
-\def\settitle{\parsearg\settitlezzz}\r
-\def\settitlezzz #1{\gdef\thistitle{#1}}\r
-\r
-\r
-\message{tables,}\r
-% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x).\r
-\r
-% default indentation of table text\r
-\newdimen\tableindent \tableindent=.8in\r
-% default indentation of @itemize and @enumerate text\r
-\newdimen\itemindent \itemindent=.3in\r
-% margin between end of table item and start of table text.\r
-\newdimen\itemmargin \itemmargin=.1in\r
-\r
-% used internally for \itemindent minus \itemmargin\r
-\newdimen\itemmax\r
-\r
-% Note @table, @vtable, and @vtable define @item, @itemx, etc., with\r
-% these defs.\r
-% They also define \itemindex\r
-% to index the item name in whatever manner is desired (perhaps none).\r
-\r
-\newif\ifitemxneedsnegativevskip\r
-\r
-\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}\r
-\r
-\def\internalBitem{\smallbreak \parsearg\itemzzz}\r
-\def\internalBitemx{\itemxpar \parsearg\itemzzz}\r
-\r
-\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz}\r
-\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz}\r
-\r
-\def\internalBkitem{\smallbreak \parsearg\kitemzzz}\r
-\def\internalBkitemx{\itemxpar \parsearg\kitemzzz}\r
-\r
-\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}%\r
- \itemzzz {#1}}\r
-\r
-\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}%\r
- \itemzzz {#1}}\r
-\r
-\def\itemzzz #1{\begingroup %\r
- \advance\hsize by -\rightskip\r
- \advance\hsize by -\tableindent\r
- \setbox0=\hbox{\itemfont{#1}}%\r
- \itemindex{#1}%\r
- \nobreak % This prevents a break before @itemx.\r
- %\r
- % If the item text does not fit in the space we have, put it on a line\r
- % by itself, and do not allow a page break either before or after that\r
- % line. We do not start a paragraph here because then if the next\r
- % command is, e.g., @kindex, the whatsit would get put into the\r
- % horizontal list on a line by itself, resulting in extra blank space.\r
- \ifdim \wd0>\itemmax\r
- %\r
- % Make this a paragraph so we get the \parskip glue and wrapping,\r
- % but leave it ragged-right.\r
- \begingroup\r
- \advance\leftskip by-\tableindent\r
- \advance\hsize by\tableindent\r
- \advance\rightskip by0pt plus1fil\r
- \leavevmode\unhbox0\par\r
- \endgroup\r
- %\r
- % We're going to be starting a paragraph, but we don't want the\r
- % \parskip glue -- logically it's part of the @item we just started.\r
- \nobreak \vskip-\parskip\r
- %\r
- % Stop a page break at the \parskip glue coming up. Unfortunately\r
- % we can't prevent a possible page break at the following\r
- % \baselineskip glue.\r
- \nobreak\r
- \endgroup\r
- \itemxneedsnegativevskipfalse\r
- \else\r
- % The item text fits into the space. Start a paragraph, so that the\r
- % following text (if any) will end up on the same line.\r
- \noindent\r
- % Do this with kerns and \unhbox so that if there is a footnote in\r
- % the item text, it can migrate to the main vertical list and\r
- % eventually be printed.\r
- \nobreak\kern-\tableindent\r
- \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0\r
- \unhbox0\r
- \nobreak\kern\dimen0\r
- \endgroup\r
- \itemxneedsnegativevskiptrue\r
- \fi\r
-}\r
-\r
-\def\item{\errmessage{@item while not in a table}}\r
-\def\itemx{\errmessage{@itemx while not in a table}}\r
-\def\kitem{\errmessage{@kitem while not in a table}}\r
-\def\kitemx{\errmessage{@kitemx while not in a table}}\r
-\def\xitem{\errmessage{@xitem while not in a table}}\r
-\def\xitemx{\errmessage{@xitemx while not in a table}}\r
-\r
-% Contains a kludge to get @end[description] to work.\r
-\def\description{\tablez{\dontindex}{1}{}{}{}{}}\r
-\r
-% @table, @ftable, @vtable.\r
-\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex}\r
-{\obeylines\obeyspaces%\r
-\gdef\tablex #1^^M{%\r
-\tabley\dontindex#1 \endtabley}}\r
-\r
-\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex}\r
-{\obeylines\obeyspaces%\r
-\gdef\ftablex #1^^M{%\r
-\tabley\fnitemindex#1 \endtabley\r
-\def\Eftable{\endgraf\afterenvbreak\endgroup}%\r
-\let\Etable=\relax}}\r
-\r
-\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex}\r
-{\obeylines\obeyspaces%\r
-\gdef\vtablex #1^^M{%\r
-\tabley\vritemindex#1 \endtabley\r
-\def\Evtable{\endgraf\afterenvbreak\endgroup}%\r
-\let\Etable=\relax}}\r
-\r
-\def\dontindex #1{}\r
-\def\fnitemindex #1{\doind {fn}{\code{#1}}}%\r
-\def\vritemindex #1{\doind {vr}{\code{#1}}}%\r
-\r
-{\obeyspaces %\r
-\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup%\r
-\tablez{#1}{#2}{#3}{#4}{#5}{#6}}}\r
-\r
-\def\tablez #1#2#3#4#5#6{%\r
-\aboveenvbreak %\r
-\begingroup %\r
-\def\Edescription{\Etable}% Necessary kludge.\r
-\let\itemindex=#1%\r
-\ifnum 0#3>0 \advance \leftskip by #3\mil \fi %\r
-\ifnum 0#4>0 \tableindent=#4\mil \fi %\r
-\ifnum 0#5>0 \advance \rightskip by #5\mil \fi %\r
-\def\itemfont{#2}%\r
-\itemmax=\tableindent %\r
-\advance \itemmax by -\itemmargin %\r
-\advance \leftskip by \tableindent %\r
-\exdentamount=\tableindent\r
-\parindent = 0pt\r
-\parskip = \smallskipamount\r
-\ifdim \parskip=0pt \parskip=2pt \fi%\r
-\def\Etable{\endgraf\afterenvbreak\endgroup}%\r
-\let\item = \internalBitem %\r
-\let\itemx = \internalBitemx %\r
-\let\kitem = \internalBkitem %\r
-\let\kitemx = \internalBkitemx %\r
-\let\xitem = \internalBxitem %\r
-\let\xitemx = \internalBxitemx %\r
-}\r
-\r
-% This is the counter used by @enumerate, which is really @itemize\r
-\r
-\newcount \itemno\r
-\r
-\def\itemize{\parsearg\itemizezzz}\r
-\r
-\def\itemizezzz #1{%\r
- \begingroup % ended by the @end itemize\r
- \itemizey {#1}{\Eitemize}\r
-}\r
-\r
-\def\itemizey #1#2{%\r
-\aboveenvbreak %\r
-\itemmax=\itemindent %\r
-\advance \itemmax by -\itemmargin %\r
-\advance \leftskip by \itemindent %\r
-\exdentamount=\itemindent\r
-\parindent = 0pt %\r
-\parskip = \smallskipamount %\r
-\ifdim \parskip=0pt \parskip=2pt \fi%\r
-\def#2{\endgraf\afterenvbreak\endgroup}%\r
-\def\itemcontents{#1}%\r
-\let\item=\itemizeitem}\r
-\r
-% Set sfcode to normal for the chars that usually have another value.\r
-% These are `.?!:;,'\r
-\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000\r
- \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 }\r
-\r
-% \splitoff TOKENS\endmark defines \first to be the first token in\r
-% TOKENS, and \rest to be the remainder.\r
-%\r
-\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%\r
-\r
-% Allow an optional argument of an uppercase letter, lowercase letter,\r
-% or number, to specify the first label in the enumerated list. No\r
-% argument is the same as `1'.\r
-%\r
-\def\enumerate{\parsearg\enumeratezzz}\r
-\def\enumeratezzz #1{\enumeratey #1 \endenumeratey}\r
-\def\enumeratey #1 #2\endenumeratey{%\r
- \begingroup % ended by the @end enumerate\r
- %\r
- % If we were given no argument, pretend we were given `1'.\r
- \def\thearg{#1}%\r
- \ifx\thearg\empty \def\thearg{1}\fi\r
- %\r
- % Detect if the argument is a single token. If so, it might be a\r
- % letter. Otherwise, the only valid thing it can be is a number.\r
- % (We will always have one token, because of the test we just made.\r
- % This is a good thing, since \splitoff doesn't work given nothing at\r
- % all -- the first parameter is undelimited.)\r
- \expandafter\splitoff\thearg\endmark\r
- \ifx\rest\empty\r
- % Only one token in the argument. It could still be anything.\r
- % A ``lowercase letter'' is one whose \lccode is nonzero.\r
- % An ``uppercase letter'' is one whose \lccode is both nonzero, and\r
- % not equal to itself.\r
- % Otherwise, we assume it's a number.\r
- %\r
- % We need the \relax at the end of the \ifnum lines to stop TeX from\r
- % continuing to look for a <number>.\r
- %\r
- \ifnum\lccode\expandafter`\thearg=0\relax\r
- \numericenumerate % a number (we hope)\r
- \else\r
- % It's a letter.\r
- \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax\r
- \lowercaseenumerate % lowercase letter\r
- \else\r
- \uppercaseenumerate % uppercase letter\r
- \fi\r
- \fi\r
- \else\r
- % Multiple tokens in the argument. We hope it's a number.\r
- \numericenumerate\r
- \fi\r
-}\r
-\r
-% An @enumerate whose labels are integers. The starting integer is\r
-% given in \thearg.\r
-%\r
-\def\numericenumerate{%\r
- \itemno = \thearg\r
- \startenumeration{\the\itemno}%\r
-}\r
-\r
-% The starting (lowercase) letter is in \thearg.\r
-\def\lowercaseenumerate{%\r
- \itemno = \expandafter`\thearg\r
- \startenumeration{%\r
- % Be sure we're not beyond the end of the alphabet.\r
- \ifnum\itemno=0\r
- \errmessage{No more lowercase letters in @enumerate; get a bigger\r
- alphabet}%\r
- \fi\r
- \char\lccode\itemno\r
- }%\r
-}\r
-\r
-% The starting (uppercase) letter is in \thearg.\r
-\def\uppercaseenumerate{%\r
- \itemno = \expandafter`\thearg\r
- \startenumeration{%\r
- % Be sure we're not beyond the end of the alphabet.\r
- \ifnum\itemno=0\r
- \errmessage{No more uppercase letters in @enumerate; get a bigger\r
- alphabet}\r
- \fi\r
- \char\uccode\itemno\r
- }%\r
-}\r
-\r
-% Call itemizey, adding a period to the first argument and supplying the\r
-% common last two arguments. Also subtract one from the initial value in\r
-% \itemno, since @item increments \itemno.\r
-%\r
-\def\startenumeration#1{%\r
- \advance\itemno by -1\r
- \itemizey{#1.}\Eenumerate\flushcr\r
-}\r
-\r
-% @alphaenumerate and @capsenumerate are abbreviations for giving an arg\r
-% to @enumerate.\r
-%\r
-\def\alphaenumerate{\enumerate{a}}\r
-\def\capsenumerate{\enumerate{A}}\r
-\def\Ealphaenumerate{\Eenumerate}\r
-\def\Ecapsenumerate{\Eenumerate}\r
-\r
-% Definition of @item while inside @itemize.\r
-\r
-\def\itemizeitem{%\r
-\advance\itemno by 1\r
-{\let\par=\endgraf \smallbreak}%\r
-\ifhmode \errmessage{In hmode at itemizeitem}\fi\r
-{\parskip=0in \hskip 0pt\r
-\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}%\r
-\vadjust{\penalty 1200}}%\r
-\flushcr}\r
-\r
-% @multitable macros\r
-% Amy Hendrickson, 8/18/94, 3/6/96\r
-%\r
-% @multitable ... @end multitable will make as many columns as desired.\r
-% Contents of each column will wrap at width given in preamble. Width\r
-% can be specified either with sample text given in a template line,\r
-% or in percent of \hsize, the current width of text on page.\r
-\r
-% Table can continue over pages but will only break between lines.\r
-\r
-% To make preamble:\r
-%\r
-% Either define widths of columns in terms of percent of \hsize:\r
-% @multitable @columnfractions .25 .3 .45\r
-% @item ...\r
-%\r
-% Numbers following @columnfractions are the percent of the total\r
-% current hsize to be used for each column. You may use as many\r
-% columns as desired.\r
-\r
-\r
-% Or use a template:\r
-% @multitable {Column 1 template} {Column 2 template} {Column 3 template}\r
-% @item ...\r
-% using the widest term desired in each column.\r
-%\r
-% For those who want to use more than one line's worth of words in\r
-% the preamble, break the line within one argument and it\r
-% will parse correctly, i.e.,\r
-%\r
-% @multitable {Column 1 template} {Column 2 template} {Column 3\r
-% template}\r
-% Not:\r
-% @multitable {Column 1 template} {Column 2 template}\r
-% {Column 3 template}\r
-\r
-% Each new table line starts with @item, each subsequent new column\r
-% starts with @tab. Empty columns may be produced by supplying @tab's\r
-% with nothing between them for as many times as empty columns are needed,\r
-% ie, @tab@tab@tab will produce two empty columns.\r
-\r
-% @item, @tab, @multitable or @end multitable do not need to be on their\r
-% own lines, but it will not hurt if they are.\r
-\r
-% Sample multitable:\r
-\r
-% @multitable {Column 1 template} {Column 2 template} {Column 3 template}\r
-% @item first col stuff @tab second col stuff @tab third col\r
-% @item\r
-% first col stuff\r
-% @tab\r
-% second col stuff\r
-% @tab\r
-% third col\r
-% @item first col stuff @tab second col stuff\r
-% @tab Many paragraphs of text may be used in any column.\r
-%\r
-% They will wrap at the width determined by the template.\r
-% @item@tab@tab This will be in third column.\r
-% @end multitable\r
-\r
-% Default dimensions may be reset by user.\r
-% @multitableparskip is vertical space between paragraphs in table.\r
-% @multitableparindent is paragraph indent in table.\r
-% @multitablecolmargin is horizontal space to be left between columns.\r
-% @multitablelinespace is space to leave between table items, baseline\r
-% to baseline.\r
-% 0pt means it depends on current normal line spacing.\r
-%\r
-\newskip\multitableparskip\r
-\newskip\multitableparindent\r
-\newdimen\multitablecolspace\r
-\newskip\multitablelinespace\r
-\multitableparskip=0pt\r
-\multitableparindent=6pt\r
-\multitablecolspace=12pt\r
-\multitablelinespace=0pt\r
-\r
-% Macros used to set up halign preamble:\r
-%\r
-\let\endsetuptable\relax\r
-\def\xendsetuptable{\endsetuptable}\r
-\let\columnfractions\relax\r
-\def\xcolumnfractions{\columnfractions}\r
-\newif\ifsetpercent\r
-\r
-% #1 is the part of the @columnfraction before the decimal point, which\r
-% is presumably either 0 or the empty string (but we don't check, we\r
-% just throw it away). #2 is the decimal part, which we use as the\r
-% percent of \hsize for this column.\r
-\def\pickupwholefraction#1.#2 {%\r
- \global\advance\colcount by 1\r
- \expandafter\xdef\csname col\the\colcount\endcsname{.#2\hsize}%\r
- \setuptable\r
-}\r
-\r
-\newcount\colcount\r
-\def\setuptable#1{%\r
- \def\firstarg{#1}%\r
- \ifx\firstarg\xendsetuptable\r
- \let\go = \relax\r
- \else\r
- \ifx\firstarg\xcolumnfractions\r
- \global\setpercenttrue\r
- \else\r
- \ifsetpercent\r
- \let\go\pickupwholefraction\r
- \else\r
- \global\advance\colcount by 1\r
- \setbox0=\hbox{#1\unskip }% Add a normal word space as a separator;\r
- % typically that is always in the input, anyway.\r
- \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%\r
- \fi\r
- \fi\r
- \ifx\go\pickupwholefraction\r
- % Put the argument back for the \pickupwholefraction call, so\r
- % we'll always have a period there to be parsed.\r
- \def\go{\pickupwholefraction#1}%\r
- \else\r
- \let\go = \setuptable\r
- \fi%\r
- \fi\r
- \go\r
-}\r
-\r
-% This used to have \hskip1sp. But then the space in a template line is\r
-% not enough. That is bad. So let's go back to just & until we\r
-% encounter the problem it was intended to solve again.\r
-% --karl, nathan@acm.org, 20apr99.\r
-\def\tab{&}\r
-\r
-% @multitable ... @end multitable definitions:\r
-%\r
-\def\multitable{\parsearg\dotable}\r
-\def\dotable#1{\bgroup\r
- \vskip\parskip\r
- \let\item\crcr\r
- \tolerance=9500\r
- \hbadness=9500\r
- \setmultitablespacing\r
- \parskip=\multitableparskip\r
- \parindent=\multitableparindent\r
- \overfullrule=0pt\r
- \global\colcount=0\r
- \def\Emultitable{\global\setpercentfalse\cr\egroup\egroup}%\r
- %\r
- % To parse everything between @multitable and @item:\r
- \setuptable#1 \endsetuptable\r
- %\r
- % \everycr will reset column counter, \colcount, at the end of\r
- % each line. Every column entry will cause \colcount to advance by one.\r
- % The table preamble\r
- % looks at the current \colcount to find the correct column width.\r
- \everycr{\noalign{%\r
- %\r
- % \filbreak%% keeps underfull box messages off when table breaks over pages.\r
- % Maybe so, but it also creates really weird page breaks when the table\r
- % breaks over pages. Wouldn't \vfil be better? Wait until the problem\r
- % manifests itself, so it can be fixed for real --karl.\r
- \global\colcount=0\relax}}%\r
- %\r
- % This preamble sets up a generic column definition, which will\r
- % be used as many times as user calls for columns.\r
- % \vtop will set a single line and will also let text wrap and\r
- % continue for many paragraphs if desired.\r
- \halign\bgroup&\global\advance\colcount by 1\relax\r
- \multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname\r
- %\r
- % In order to keep entries from bumping into each other\r
- % we will add a \leftskip of \multitablecolspace to all columns after\r
- % the first one.\r
- %\r
- % If a template has been used, we will add \multitablecolspace\r
- % to the width of each template entry.\r
- %\r
- % If the user has set preamble in terms of percent of \hsize we will\r
- % use that dimension as the width of the column, and the \leftskip\r
- % will keep entries from bumping into each other. Table will start at\r
- % left margin and final column will justify at right margin.\r
- %\r
- % Make sure we don't inherit \rightskip from the outer environment.\r
- \rightskip=0pt\r
- \ifnum\colcount=1\r
- % The first column will be indented with the surrounding text.\r
- \advance\hsize by\leftskip\r
- \else\r
- \ifsetpercent \else\r
- % If user has not set preamble in terms of percent of \hsize\r
- % we will advance \hsize by \multitablecolspace.\r
- \advance\hsize by \multitablecolspace\r
- \fi\r
- % In either case we will make \leftskip=\multitablecolspace:\r
- \leftskip=\multitablecolspace\r
- \fi\r
- % Ignoring space at the beginning and end avoids an occasional spurious\r
- % blank line, when TeX decides to break the line at the space before the\r
- % box from the multistrut, so the strut ends up on a line by itself.\r
- % For example:\r
- % @multitable @columnfractions .11 .89\r
- % @item @code{#}\r
- % @tab Legal holiday which is valid in major parts of the whole country.\r
- % Is automatically provided with highlighting sequences respectively marking\r
- % characters.\r
- \noindent\ignorespaces##\unskip\multistrut}\cr\r
-}\r
-\r
-\def\setmultitablespacing{% test to see if user has set \multitablelinespace.\r
-% If so, do nothing. If not, give it an appropriate dimension based on\r
-% current baselineskip.\r
-\ifdim\multitablelinespace=0pt\r
-\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip\r
-\global\advance\multitablelinespace by-\ht0\r
-%% strut to put in table in case some entry doesn't have descenders,\r
-%% to keep lines equally spaced\r
-\let\multistrut = \strut\r
-\else\r
-%% FIXME: what is \box0 supposed to be?\r
-\gdef\multistrut{\vrule height\multitablelinespace depth\dp0\r
-width0pt\relax} \fi\r
-%% Test to see if parskip is larger than space between lines of\r
-%% table. If not, do nothing.\r
-%% If so, set to same dimension as multitablelinespace.\r
-\ifdim\multitableparskip>\multitablelinespace\r
-\global\multitableparskip=\multitablelinespace\r
-\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller\r
- %% than skip between lines in the table.\r
-\fi%\r
-\ifdim\multitableparskip=0pt\r
-\global\multitableparskip=\multitablelinespace\r
-\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller\r
- %% than skip between lines in the table.\r
-\fi}\r
-\r
-\r
-\message{conditionals,}\r
-% Prevent errors for section commands.\r
-% Used in @ignore and in failing conditionals.\r
-\def\ignoresections{%\r
- \let\chapter=\relax\r
- \let\unnumbered=\relax\r
- \let\top=\relax\r
- \let\unnumberedsec=\relax\r
- \let\unnumberedsection=\relax\r
- \let\unnumberedsubsec=\relax\r
- \let\unnumberedsubsection=\relax\r
- \let\unnumberedsubsubsec=\relax\r
- \let\unnumberedsubsubsection=\relax\r
- \let\section=\relax\r
- \let\subsec=\relax\r
- \let\subsubsec=\relax\r
- \let\subsection=\relax\r
- \let\subsubsection=\relax\r
- \let\appendix=\relax\r
- \let\appendixsec=\relax\r
- \let\appendixsection=\relax\r
- \let\appendixsubsec=\relax\r
- \let\appendixsubsection=\relax\r
- \let\appendixsubsubsec=\relax\r
- \let\appendixsubsubsection=\relax\r
- \let\contents=\relax\r
- \let\smallbook=\relax\r
- \let\titlepage=\relax\r
-}\r
-\r
-% Used in nested conditionals, where we have to parse the Texinfo source\r
-% and so want to turn off most commands, in case they are used\r
-% incorrectly.\r
-%\r
-\def\ignoremorecommands{%\r
- \let\defcodeindex = \relax\r
- \let\defcv = \relax\r
- \let\deffn = \relax\r
- \let\deffnx = \relax\r
- \let\defindex = \relax\r
- \let\defivar = \relax\r
- \let\defmac = \relax\r
- \let\defmethod = \relax\r
- \let\defop = \relax\r
- \let\defopt = \relax\r
- \let\defspec = \relax\r
- \let\deftp = \relax\r
- \let\deftypefn = \relax\r
- \let\deftypefun = \relax\r
- \let\deftypeivar = \relax\r
- \let\deftypeop = \relax\r
- \let\deftypevar = \relax\r
- \let\deftypevr = \relax\r
- \let\defun = \relax\r
- \let\defvar = \relax\r
- \let\defvr = \relax\r
- \let\ref = \relax\r
- \let\xref = \relax\r
- \let\printindex = \relax\r
- \let\pxref = \relax\r
- \let\settitle = \relax\r
- \let\setchapternewpage = \relax\r
- \let\setchapterstyle = \relax\r
- \let\everyheading = \relax\r
- \let\evenheading = \relax\r
- \let\oddheading = \relax\r
- \let\everyfooting = \relax\r
- \let\evenfooting = \relax\r
- \let\oddfooting = \relax\r
- \let\headings = \relax\r
- \let\include = \relax\r
- \let\lowersections = \relax\r
- \let\down = \relax\r
- \let\raisesections = \relax\r
- \let\up = \relax\r
- \let\set = \relax\r
- \let\clear = \relax\r
- \let\item = \relax\r
-}\r
-\r
-% Ignore @ignore ... @end ignore.\r
-%\r
-\def\ignore{\doignore{ignore}}\r
-\r
-% Ignore @ifinfo, @ifhtml, @ifnottex, @html, @menu, and @direntry text.\r
-%\r
-\def\ifinfo{\doignore{ifinfo}}\r
-\def\ifhtml{\doignore{ifhtml}}\r
-\def\ifnottex{\doignore{ifnottex}}\r
-\def\html{\doignore{html}}\r
-\def\menu{\doignore{menu}}\r
-\def\direntry{\doignore{direntry}}\r
-\r
-% @dircategory CATEGORY -- specify a category of the dir file\r
-% which this file should belong to. Ignore this in TeX.\r
-\let\dircategory = \comment\r
-\r
-% Ignore text until a line `@end #1'.\r
-%\r
-\def\doignore#1{\begingroup\r
- % Don't complain about control sequences we have declared \outer.\r
- \ignoresections\r
- %\r
- % Define a command to swallow text until we reach `@end #1'.\r
- % This @ is a catcode 12 token (that is the normal catcode of @ in\r
- % this texinfo.tex file). We change the catcode of @ below to match.\r
- \long\def\doignoretext##1@end #1{\enddoignore}%\r
- %\r
- % Make sure that spaces turn into tokens that match what \doignoretext wants.\r
- \catcode32 = 10\r
- %\r
- % Ignore braces, too, so mismatched braces don't cause trouble.\r
- \catcode`\{ = 9\r
- \catcode`\} = 9\r
- %\r
- % We must not have @c interpreted as a control sequence.\r
- \catcode`\@ = 12\r
- %\r
- % Make the letter c a comment character so that the rest of the line\r
- % will be ignored. This way, the document can have (for example)\r
- % @c @end ifinfo\r
- % and the @end ifinfo will be properly ignored.\r
- % (We've just changed @ to catcode 12.)\r
- \catcode`\c = 14\r
- %\r
- % And now expand that command.\r
- \doignoretext\r
-}\r
-\r
-% What we do to finish off ignored text.\r
-%\r
-\def\enddoignore{\endgroup\ignorespaces}%\r
-\r
-\newif\ifwarnedobs\warnedobsfalse\r
-\def\obstexwarn{%\r
- \ifwarnedobs\relax\else\r
- % We need to warn folks that they may have trouble with TeX 3.0.\r
- % This uses \immediate\write16 rather than \message to get newlines.\r
- \immediate\write16{}\r
- \immediate\write16{WARNING: for users of Unix TeX 3.0!}\r
- \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).}\r
- \immediate\write16{If you are running another version of TeX, relax.}\r
- \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.}\r
- \immediate\write16{ Then upgrade your TeX installation if you can.}\r
- \immediate\write16{ (See ftp://ftp.gnu.org/pub/gnu/TeX.README.)}\r
- \immediate\write16{If you are stuck with version 3.0, run the}\r
- \immediate\write16{ script ``tex3patch'' from the Texinfo distribution}\r
- \immediate\write16{ to use a workaround.}\r
- \immediate\write16{}\r
- \global\warnedobstrue\r
- \fi\r
-}\r
-\r
-% **In TeX 3.0, setting text in \nullfont hangs tex. For a\r
-% workaround (which requires the file ``dummy.tfm'' to be installed),\r
-% uncomment the following line:\r
-%%%%%\font\nullfont=dummy\let\obstexwarn=\relax\r
-\r
-% Ignore text, except that we keep track of conditional commands for\r
-% purposes of nesting, up to an `@end #1' command.\r
-%\r
-\def\nestedignore#1{%\r
- \obstexwarn\r
- % We must actually expand the ignored text to look for the @end\r
- % command, so that nested ignore constructs work. Thus, we put the\r
- % text into a \vbox and then do nothing with the result. To minimize\r
- % the change of memory overflow, we follow the approach outlined on\r
- % page 401 of the TeXbook: make the current font be a dummy font.\r
- %\r
- \setbox0 = \vbox\bgroup\r
- % Don't complain about control sequences we have declared \outer.\r
- \ignoresections\r
- %\r
- % Define `@end #1' to end the box, which will in turn undefine the\r
- % @end command again.\r
- \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}%\r
- %\r
- % We are going to be parsing Texinfo commands. Most cause no\r
- % trouble when they are used incorrectly, but some commands do\r
- % complicated argument parsing or otherwise get confused, so we\r
- % undefine them.\r
- %\r
- % We can't do anything about stray @-signs, unfortunately;\r
- % they'll produce `undefined control sequence' errors.\r
- \ignoremorecommands\r
- %\r
- % Set the current font to be \nullfont, a TeX primitive, and define\r
- % all the font commands to also use \nullfont. We don't use\r
- % dummy.tfm, as suggested in the TeXbook, because not all sites\r
- % might have that installed. Therefore, math mode will still\r
- % produce output, but that should be an extremely small amount of\r
- % stuff compared to the main input.\r
- %\r
- \nullfont\r
- \let\tenrm=\nullfont \let\tenit=\nullfont \let\tensl=\nullfont\r
- \let\tenbf=\nullfont \let\tentt=\nullfont \let\smallcaps=\nullfont\r
- \let\tensf=\nullfont\r
- % Similarly for index fonts (mostly for their use in smallexample).\r
- \let\smallrm=\nullfont \let\smallit=\nullfont \let\smallsl=\nullfont\r
- \let\smallbf=\nullfont \let\smalltt=\nullfont \let\smallsc=\nullfont\r
- \let\smallsf=\nullfont\r
- %\r
- % Don't complain when characters are missing from the fonts.\r
- \tracinglostchars = 0\r
- %\r
- % Don't bother to do space factor calculations.\r
- \frenchspacing\r
- %\r
- % Don't report underfull hboxes.\r
- \hbadness = 10000\r
- %\r
- % Do minimal line-breaking.\r
- \pretolerance = 10000\r
- %\r
- % Do not execute instructions in @tex\r
- \def\tex{\doignore{tex}}%\r
- % Do not execute macro definitions.\r
- % `c' is a comment character, so the word `macro' will get cut off.\r
- \def\macro{\doignore{ma}}%\r
-}\r
-\r
-% @set VAR sets the variable VAR to an empty value.\r
-% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.\r
-%\r
-% Since we want to separate VAR from REST-OF-LINE (which might be\r
-% empty), we can't just use \parsearg; we have to insert a space of our\r
-% own to delimit the rest of the line, and then take it out again if we\r
-% didn't need it. Make sure the catcode of space is correct to avoid\r
-% losing inside @example, for instance.\r
-%\r
-\def\set{\begingroup\catcode` =10\r
- \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR.\r
- \parsearg\setxxx}\r
-\def\setxxx#1{\setyyy#1 \endsetyyy}\r
-\def\setyyy#1 #2\endsetyyy{%\r
- \def\temp{#2}%\r
- \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty\r
- \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted.\r
- \fi\r
- \endgroup\r
-}\r
-% Can't use \xdef to pre-expand #2 and save some time, since \temp or\r
-% \next or other control sequences that we've defined might get us into\r
-% an infinite loop. Consider `@set foo @cite{bar}'.\r
-\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}}\r
-\r
-% @clear VAR clears (i.e., unsets) the variable VAR.\r
-%\r
-\def\clear{\parsearg\clearxxx}\r
-\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax}\r
-\r
-% @value{foo} gets the text saved in variable foo.\r
-{\r
- \catcode`\_ = \active\r
- %\r
- % We might end up with active _ or - characters in the argument if\r
- % we're called from @code, as @code{@value{foo-bar_}}. So \let any\r
- % such active characters to their normal equivalents.\r
- \gdef\value{\begingroup\r
- \catcode`\-=12 \catcode`\_=12\r
- \indexbreaks \let_\normalunderscore\r
- \valuexxx}\r
-}\r
-\def\valuexxx#1{\expandablevalue{#1}\endgroup}\r
-\r
-% We have this subroutine so that we can handle at least some @value's\r
-% properly in indexes (we \let\value to this in \indexdummies). Ones\r
-% whose names contain - or _ still won't work, but we can't do anything\r
-% about that. The command has to be fully expandable, since the result\r
-% winds up in the index file. This means that if the variable's value\r
-% contains other Texinfo commands, it's almost certain it will fail\r
-% (although perhaps we could fix that with sufficient work to do a\r
-% one-level expansion on the result, instead of complete).\r
-%\r
-\def\expandablevalue#1{%\r
- \expandafter\ifx\csname SET#1\endcsname\relax\r
- {[No value for ``#1'']}%\r
- \else\r
- \csname SET#1\endcsname\r
- \fi\r
-}\r
-\r
-% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined\r
-% with @set.\r
-%\r
-\def\ifset{\parsearg\ifsetxxx}\r
-\def\ifsetxxx #1{%\r
- \expandafter\ifx\csname SET#1\endcsname\relax\r
- \expandafter\ifsetfail\r
- \else\r
- \expandafter\ifsetsucceed\r
- \fi\r
-}\r
-\def\ifsetsucceed{\conditionalsucceed{ifset}}\r
-\def\ifsetfail{\nestedignore{ifset}}\r
-\defineunmatchedend{ifset}\r
-\r
-% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been\r
-% defined with @set, or has been undefined with @clear.\r
-%\r
-\def\ifclear{\parsearg\ifclearxxx}\r
-\def\ifclearxxx #1{%\r
- \expandafter\ifx\csname SET#1\endcsname\relax\r
- \expandafter\ifclearsucceed\r
- \else\r
- \expandafter\ifclearfail\r
- \fi\r
-}\r
-\def\ifclearsucceed{\conditionalsucceed{ifclear}}\r
-\def\ifclearfail{\nestedignore{ifclear}}\r
-\defineunmatchedend{ifclear}\r
-\r
-% @iftex, @ifnothtml, @ifnotinfo always succeed; we read the text\r
-% following, through the first @end iftex (etc.). Make `@end iftex'\r
-% (etc.) valid only after an @iftex.\r
-%\r
-\def\iftex{\conditionalsucceed{iftex}}\r
-\def\ifnothtml{\conditionalsucceed{ifnothtml}}\r
-\def\ifnotinfo{\conditionalsucceed{ifnotinfo}}\r
-\defineunmatchedend{iftex}\r
-\defineunmatchedend{ifnothtml}\r
-\defineunmatchedend{ifnotinfo}\r
-\r
-% We can't just want to start a group at @iftex (for example) and end it\r
-% at @end iftex, since then @set commands inside the conditional have no\r
-% effect (they'd get reverted at the end of the group). So we must\r
-% define \Eiftex to redefine itself to be its previous value. (We can't\r
-% just define it to fail again with an ``unmatched end'' error, since\r
-% the @ifset might be nested.)\r
-%\r
-\def\conditionalsucceed#1{%\r
- \edef\temp{%\r
- % Remember the current value of \E#1.\r
- \let\nece{prevE#1} = \nece{E#1}%\r
- %\r
- % At the `@end #1', redefine \E#1 to be its previous value.\r
- \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}%\r
- }%\r
- \temp\r
-}\r
-\r
-% We need to expand lots of \csname's, but we don't want to expand the\r
-% control sequences after we've constructed them.\r
-%\r
-\def\nece#1{\expandafter\noexpand\csname#1\endcsname}\r
-\r
-% @defininfoenclose.\r
-\let\definfoenclose=\comment\r
-\r
-\r
-\message{indexing,}\r
-% Index generation facilities\r
-\r
-% Define \newwrite to be identical to plain tex's \newwrite\r
-% except not \outer, so it can be used within \newindex.\r
-{\catcode`\@=11\r
-\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}}\r
-\r
-% \newindex {foo} defines an index named foo.\r
-% It automatically defines \fooindex such that\r
-% \fooindex ...rest of line... puts an entry in the index foo.\r
-% It also defines \fooindfile to be the number of the output channel for\r
-% the file that accumulates this index. The file's extension is foo.\r
-% The name of an index should be no more than 2 characters long\r
-% for the sake of vms.\r
-%\r
-\def\newindex#1{%\r
- \iflinks\r
- \expandafter\newwrite \csname#1indfile\endcsname\r
- \openout \csname#1indfile\endcsname \jobname.#1 % Open the file\r
- \fi\r
- \expandafter\xdef\csname#1index\endcsname{% % Define @#1index\r
- \noexpand\doindex{#1}}\r
-}\r
-\r
-% @defindex foo == \newindex{foo}\r
-\r
-\def\defindex{\parsearg\newindex}\r
-\r
-% Define @defcodeindex, like @defindex except put all entries in @code.\r
-\r
-\def\newcodeindex#1{%\r
- \iflinks\r
- \expandafter\newwrite \csname#1indfile\endcsname\r
- \openout \csname#1indfile\endcsname \jobname.#1\r
- \fi\r
- \expandafter\xdef\csname#1index\endcsname{%\r
- \noexpand\docodeindex{#1}}\r
-}\r
-\r
-\def\defcodeindex{\parsearg\newcodeindex}\r
-\r
-% @synindex foo bar makes index foo feed into index bar.\r
-% Do this instead of @defindex foo if you don't want it as a separate index.\r
-% The \closeout helps reduce unnecessary open files; the limit on the\r
-% Acorn RISC OS is a mere 16 files.\r
-\def\synindex#1 #2 {%\r
- \expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname\r
- \expandafter\closeout\csname#1indfile\endcsname\r
- \expandafter\let\csname#1indfile\endcsname=\synindexfoo\r
- \expandafter\xdef\csname#1index\endcsname{% define \xxxindex\r
- \noexpand\doindex{#2}}%\r
-}\r
-\r
-% @syncodeindex foo bar similar, but put all entries made for index foo\r
-% inside @code.\r
-\def\syncodeindex#1 #2 {%\r
- \expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname\r
- \expandafter\closeout\csname#1indfile\endcsname\r
- \expandafter\let\csname#1indfile\endcsname=\synindexfoo\r
- \expandafter\xdef\csname#1index\endcsname{% define \xxxindex\r
- \noexpand\docodeindex{#2}}%\r
-}\r
-\r
-% Define \doindex, the driver for all \fooindex macros.\r
-% Argument #1 is generated by the calling \fooindex macro,\r
-% and it is "foo", the name of the index.\r
-\r
-% \doindex just uses \parsearg; it calls \doind for the actual work.\r
-% This is because \doind is more useful to call from other macros.\r
-\r
-% There is also \dosubind {index}{topic}{subtopic}\r
-% which makes an entry in a two-level index such as the operation index.\r
-\r
-\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer}\r
-\def\singleindexer #1{\doind{\indexname}{#1}}\r
-\r
-% like the previous two, but they put @code around the argument.\r
-\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}\r
-\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}\r
-\r
-\def\indexdummies{%\r
-\def\ { }%\r
-% Take care of the plain tex accent commands.\r
-\def\"{\realbackslash "}%\r
-\def\`{\realbackslash `}%\r
-\def\'{\realbackslash '}%\r
-\def\^{\realbackslash ^}%\r
-\def\~{\realbackslash ~}%\r
-\def\={\realbackslash =}%\r
-\def\b{\realbackslash b}%\r
-\def\c{\realbackslash c}%\r
-\def\d{\realbackslash d}%\r
-\def\u{\realbackslash u}%\r
-\def\v{\realbackslash v}%\r
-\def\H{\realbackslash H}%\r
-% Take care of the plain tex special European modified letters.\r
-\def\oe{\realbackslash oe}%\r
-\def\ae{\realbackslash ae}%\r
-\def\aa{\realbackslash aa}%\r
-\def\OE{\realbackslash OE}%\r
-\def\AE{\realbackslash AE}%\r
-\def\AA{\realbackslash AA}%\r
-\def\o{\realbackslash o}%\r
-\def\O{\realbackslash O}%\r
-\def\l{\realbackslash l}%\r
-\def\L{\realbackslash L}%\r
-\def\ss{\realbackslash ss}%\r
-% Take care of texinfo commands likely to appear in an index entry.\r
-% (Must be a way to avoid doing expansion at all, and thus not have to\r
-% laboriously list every single command here.)\r
-\def\@{@}% will be @@ when we switch to @ as escape char.\r
-% Need these in case \tex is in effect and \{ is a \delimiter again.\r
-% But can't use \lbracecmd and \rbracecmd because texindex assumes\r
-% braces and backslashes are used only as delimiters. \r
-\let\{ = \mylbrace\r
-\let\} = \myrbrace\r
-\def\_{{\realbackslash _}}%\r
-\def\w{\realbackslash w }%\r
-\def\bf{\realbackslash bf }%\r
-%\def\rm{\realbackslash rm }%\r
-\def\sl{\realbackslash sl }%\r
-\def\sf{\realbackslash sf}%\r
-\def\tt{\realbackslash tt}%\r
-\def\gtr{\realbackslash gtr}%\r
-\def\less{\realbackslash less}%\r
-\def\hat{\realbackslash hat}%\r
-\def\TeX{\realbackslash TeX}%\r
-\def\dots{\realbackslash dots }%\r
-\def\result{\realbackslash result}%\r
-\def\equiv{\realbackslash equiv}%\r
-\def\expansion{\realbackslash expansion}%\r
-\def\print{\realbackslash print}%\r
-\def\error{\realbackslash error}%\r
-\def\point{\realbackslash point}%\r
-\def\copyright{\realbackslash copyright}%\r
-\def\tclose##1{\realbackslash tclose {##1}}%\r
-\def\code##1{\realbackslash code {##1}}%\r
-\def\uref##1{\realbackslash uref {##1}}%\r
-\def\url##1{\realbackslash url {##1}}%\r
-\def\env##1{\realbackslash env {##1}}%\r
-\def\command##1{\realbackslash command {##1}}%\r
-\def\option##1{\realbackslash option {##1}}%\r
-\def\dotless##1{\realbackslash dotless {##1}}%\r
-\def\samp##1{\realbackslash samp {##1}}%\r
-\def\,##1{\realbackslash ,{##1}}%\r
-\def\t##1{\realbackslash t {##1}}%\r
-\def\r##1{\realbackslash r {##1}}%\r
-\def\i##1{\realbackslash i {##1}}%\r
-\def\b##1{\realbackslash b {##1}}%\r
-\def\sc##1{\realbackslash sc {##1}}%\r
-\def\cite##1{\realbackslash cite {##1}}%\r
-\def\key##1{\realbackslash key {##1}}%\r
-\def\file##1{\realbackslash file {##1}}%\r
-\def\var##1{\realbackslash var {##1}}%\r
-\def\kbd##1{\realbackslash kbd {##1}}%\r
-\def\dfn##1{\realbackslash dfn {##1}}%\r
-\def\emph##1{\realbackslash emph {##1}}%\r
-\def\acronym##1{\realbackslash acronym {##1}}%\r
-%\r
-% Handle some cases of @value -- where the variable name does not\r
-% contain - or _, and the value does not contain any\r
-% (non-fully-expandable) commands.\r
-\let\value = \expandablevalue\r
-%\r
-\unsepspaces\r
-% Turn off macro expansion\r
-\turnoffmacros\r
-}\r
-\r
-% If an index command is used in an @example environment, any spaces\r
-% therein should become regular spaces in the raw index file, not the\r
-% expansion of \tie (\\leavevmode \penalty \@M \ ).\r
-{\obeyspaces\r
- \gdef\unsepspaces{\obeyspaces\let =\space}}\r
-\r
-% \indexnofonts no-ops all font-change commands.\r
-% This is used when outputting the strings to sort the index by.\r
-\def\indexdummyfont#1{#1}\r
-\def\indexdummytex{TeX}\r
-\def\indexdummydots{...}\r
-\r
-\def\indexnofonts{%\r
-% Just ignore accents.\r
-\let\,=\indexdummyfont\r
-\let\"=\indexdummyfont\r
-\let\`=\indexdummyfont\r
-\let\'=\indexdummyfont\r
-\let\^=\indexdummyfont\r
-\let\~=\indexdummyfont\r
-\let\==\indexdummyfont\r
-\let\b=\indexdummyfont\r
-\let\c=\indexdummyfont\r
-\let\d=\indexdummyfont\r
-\let\u=\indexdummyfont\r
-\let\v=\indexdummyfont\r
-\let\H=\indexdummyfont\r
-\let\dotless=\indexdummyfont\r
-% Take care of the plain tex special European modified letters.\r
-\def\oe{oe}%\r
-\def\ae{ae}%\r
-\def\aa{aa}%\r
-\def\OE{OE}%\r
-\def\AE{AE}%\r
-\def\AA{AA}%\r
-\def\o{o}%\r
-\def\O{O}%\r
-\def\l{l}%\r
-\def\L{L}%\r
-\def\ss{ss}%\r
-\let\w=\indexdummyfont\r
-\let\t=\indexdummyfont\r
-\let\r=\indexdummyfont\r
-\let\i=\indexdummyfont\r
-\let\b=\indexdummyfont\r
-\let\emph=\indexdummyfont\r
-\let\strong=\indexdummyfont\r
-\let\cite=\indexdummyfont\r
-\let\sc=\indexdummyfont\r
-%Don't no-op \tt, since it isn't a user-level command\r
-% and is used in the definitions of the active chars like <, >, |...\r
-%\let\tt=\indexdummyfont\r
-\let\tclose=\indexdummyfont\r
-\let\code=\indexdummyfont\r
-\let\url=\indexdummyfont\r
-\let\uref=\indexdummyfont\r
-\let\env=\indexdummyfont\r
-\let\acronym=\indexdummyfont\r
-\let\command=\indexdummyfont\r
-\let\option=\indexdummyfont\r
-\let\file=\indexdummyfont\r
-\let\samp=\indexdummyfont\r
-\let\kbd=\indexdummyfont\r
-\let\key=\indexdummyfont\r
-\let\var=\indexdummyfont\r
-\let\TeX=\indexdummytex\r
-\let\dots=\indexdummydots\r
-\def\@{@}%\r
-}\r
-\r
-% To define \realbackslash, we must make \ not be an escape.\r
-% We must first make another character (@) an escape\r
-% so we do not become unable to do a definition.\r
-\r
-{\catcode`\@=0 \catcode`\\=\other\r
- @gdef@realbackslash{\}}\r
-\r
-\let\indexbackslash=0 %overridden during \printindex.\r
-\let\SETmarginindex=\relax % put index entries in margin (undocumented)?\r
-\r
-% For \ifx comparisons.\r
-\def\emptymacro{\empty}\r
-\r
-% Most index entries go through here, but \dosubind is the general case.\r
-%\r
-\def\doind#1#2{\dosubind{#1}{#2}\empty}\r
-\r
-% Workhorse for all \fooindexes.\r
-% #1 is name of index, #2 is stuff to put there, #3 is subentry --\r
-% \empty if called from \doind, as we usually are. The main exception\r
-% is with defuns, which call us directly.\r
-%\r
-\def\dosubind#1#2#3{%\r
- % Put the index entry in the margin if desired.\r
- \ifx\SETmarginindex\relax\else\r
- \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}%\r
- \fi\r
- {%\r
- \count255=\lastpenalty\r
- {%\r
- \indexdummies % Must do this here, since \bf, etc expand at this stage\r
- \escapechar=`\\\r
- {%\r
- \let\folio = 0% We will expand all macros now EXCEPT \folio.\r
- \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now\r
- % so it will be output as is; and it will print as backslash.\r
- %\r
- \def\thirdarg{#3}%\r
- %\r
- % If third arg is present, precede it with space in sort key.\r
- \ifx\thirdarg\emptymacro\r
- \let\subentry = \empty\r
- \else\r
- \def\subentry{ #3}%\r
- \fi\r
- %\r
- % First process the index entry with all font commands turned\r
- % off to get the string to sort by.\r
- {\indexnofonts \xdef\indexsorttmp{#2\subentry}}%\r
- %\r
- % Now the real index entry with the fonts.\r
- \toks0 = {#2}%\r
- %\r
- % If third (subentry) arg is present, add it to the index\r
- % string. And include a space.\r
- \ifx\thirdarg\emptymacro \else\r
- \toks0 = \expandafter{\the\toks0 \space #3}%\r
- \fi\r
- %\r
- % Set up the complete index entry, with both the sort key\r
- % and the original text, including any font commands. We write\r
- % three arguments to \entry to the .?? file, texindex reduces to\r
- % two when writing the .??s sorted result.\r
- \edef\temp{%\r
- \write\csname#1indfile\endcsname{%\r
- \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}%\r
- }%\r
- %\r
- % If a skip is the last thing on the list now, preserve it\r
- % by backing up by \lastskip, doing the \write, then inserting\r
- % the skip again. Otherwise, the whatsit generated by the\r
- % \write will make \lastskip zero. The result is that sequences\r
- % like this:\r
- % @end defun\r
- % @tindex whatever\r
- % @defun ...\r
- % will have extra space inserted, because the \medbreak in the\r
- % start of the @defun won't see the skip inserted by the @end of\r
- % the previous defun.\r
- %\r
- % But don't do any of this if we're not in vertical mode. We\r
- % don't want to do a \vskip and prematurely end a paragraph.\r
- %\r
- % Avoid page breaks due to these extra skips, too.\r
- %\r
- \iflinks\r
- \ifvmode\r
- \skip0 = \lastskip\r
- \ifdim\lastskip = 0pt \else \nobreak\vskip-\lastskip \fi\r
- \fi\r
- %\r
- \temp % do the write\r
- %\r
- %\r
- \ifvmode \ifdim\skip0 = 0pt \else \nobreak\vskip\skip0 \fi \fi\r
- \fi\r
- }%\r
- }%\r
- \penalty\count255\r
- }%\r
-}\r
-\r
-% The index entry written in the file actually looks like\r
-% \entry {sortstring}{page}{topic}\r
-% or\r
-% \entry {sortstring}{page}{topic}{subtopic}\r
-% The texindex program reads in these files and writes files\r
-% containing these kinds of lines:\r
-% \initial {c}\r
-% before the first topic whose initial is c\r
-% \entry {topic}{pagelist}\r
-% for a topic that is used without subtopics\r
-% \primary {topic}\r
-% for the beginning of a topic that is used with subtopics\r
-% \secondary {subtopic}{pagelist}\r
-% for each subtopic.\r
-\r
-% Define the user-accessible indexing commands\r
-% @findex, @vindex, @kindex, @cindex.\r
-\r
-\def\findex {\fnindex}\r
-\def\kindex {\kyindex}\r
-\def\cindex {\cpindex}\r
-\def\vindex {\vrindex}\r
-\def\tindex {\tpindex}\r
-\def\pindex {\pgindex}\r
-\r
-\def\cindexsub {\begingroup\obeylines\cindexsub}\r
-{\obeylines %\r
-\gdef\cindexsub "#1" #2^^M{\endgroup %\r
-\dosubind{cp}{#2}{#1}}}\r
-\r
-% Define the macros used in formatting output of the sorted index material.\r
-\r
-% @printindex causes a particular index (the ??s file) to get printed.\r
-% It does not print any chapter heading (usually an @unnumbered).\r
-%\r
-\def\printindex{\parsearg\doprintindex}\r
-\def\doprintindex#1{\begingroup\r
- \dobreak \chapheadingskip{10000}%\r
- %\r
- \smallfonts \rm\r
- \tolerance = 9500\r
- \indexbreaks\r
- %\r
- % See if the index file exists and is nonempty.\r
- % Change catcode of @ here so that if the index file contains\r
- % \initial {@}\r
- % as its first line, TeX doesn't complain about mismatched braces\r
- % (because it thinks @} is a control sequence).\r
- \catcode`\@ = 11\r
- \openin 1 \jobname.#1s\r
- \ifeof 1\r
- % \enddoublecolumns gets confused if there is no text in the index,\r
- % and it loses the chapter title and the aux file entries for the\r
- % index. The easiest way to prevent this problem is to make sure\r
- % there is some text.\r
- \putwordIndexNonexistent\r
- \else\r
- %\r
- % If the index file exists but is empty, then \openin leaves \ifeof\r
- % false. We have to make TeX try to read something from the file, so\r
- % it can discover if there is anything in it.\r
- \read 1 to \temp\r
- \ifeof 1\r
- \putwordIndexIsEmpty\r
- \else\r
- % Index files are almost Texinfo source, but we use \ as the escape\r
- % character. It would be better to use @, but that's too big a change\r
- % to make right now.\r
- \def\indexbackslash{\rawbackslashxx}%\r
- \catcode`\\ = 0\r
- \escapechar = `\\\r
- \begindoublecolumns\r
- \input \jobname.#1s\r
- \enddoublecolumns\r
- \fi\r
- \fi\r
- \closein 1\r
-\endgroup}\r
-\r
-% These macros are used by the sorted index file itself.\r
-% Change them to control the appearance of the index.\r
-\r
-\def\initial#1{{%\r
- % Some minor font changes for the special characters.\r
- \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt\r
- %\r
- % Remove any glue we may have, we'll be inserting our own.\r
- \removelastskip\r
- %\r
- % We like breaks before the index initials, so insert a bonus.\r
- \penalty -300\r
- %\r
- % Typeset the initial. Making this add up to a whole number of\r
- % baselineskips increases the chance of the dots lining up from column\r
- % to column. It still won't often be perfect, because of the stretch\r
- % we need before each entry, but it's better.\r
- %\r
- % No shrink because it confuses \balancecolumns.\r
- \vskip 1.67\baselineskip plus .5\baselineskip\r
- \leftline{\secbf #1}%\r
- \vskip .33\baselineskip plus .1\baselineskip\r
- %\r
- % Do our best not to break after the initial.\r
- \nobreak\r
-}}\r
-\r
-% This typesets a paragraph consisting of #1, dot leaders, and then #2\r
-% flush to the right margin. It is used for index and table of contents\r
-% entries. The paragraph is indented by \leftskip.\r
-%\r
-\def\entry#1#2{\begingroup\r
- %\r
- % Start a new paragraph if necessary, so our assignments below can't\r
- % affect previous text.\r
- \par\r
- %\r
- % Do not fill out the last line with white space.\r
- \parfillskip = 0in\r
- %\r
- % No extra space above this paragraph.\r
- \parskip = 0in\r
- %\r
- % Do not prefer a separate line ending with a hyphen to fewer lines.\r
- \finalhyphendemerits = 0\r
- %\r
- % \hangindent is only relevant when the entry text and page number\r
- % don't both fit on one line. In that case, bob suggests starting the\r
- % dots pretty far over on the line. Unfortunately, a large\r
- % indentation looks wrong when the entry text itself is broken across\r
- % lines. So we use a small indentation and put up with long leaders.\r
- %\r
- % \hangafter is reset to 1 (which is the value we want) at the start\r
- % of each paragraph, so we need not do anything with that.\r
- \hangindent = 2em\r
- %\r
- % When the entry text needs to be broken, just fill out the first line\r
- % with blank space.\r
- \rightskip = 0pt plus1fil\r
- %\r
- % A bit of stretch before each entry for the benefit of balancing columns.\r
- \vskip 0pt plus1pt\r
- %\r
- % Start a ``paragraph'' for the index entry so the line breaking\r
- % parameters we've set above will have an effect.\r
- \noindent\r
- %\r
- % Insert the text of the index entry. TeX will do line-breaking on it.\r
- #1%\r
- % The following is kludged to not output a line of dots in the index if\r
- % there are no page numbers. The next person who breaks this will be\r
- % cursed by a Unix daemon.\r
- \def\tempa{{\rm }}%\r
- \def\tempb{#2}%\r
- \edef\tempc{\tempa}%\r
- \edef\tempd{\tempb}%\r
- \ifx\tempc\tempd\ \else%\r
- %\r
- % If we must, put the page number on a line of its own, and fill out\r
- % this line with blank space. (The \hfil is overwhelmed with the\r
- % fill leaders glue in \indexdotfill if the page number does fit.)\r
- \hfil\penalty50\r
- \null\nobreak\indexdotfill % Have leaders before the page number.\r
- %\r
- % The `\ ' here is removed by the implicit \unskip that TeX does as\r
- % part of (the primitive) \par. Without it, a spurious underfull\r
- % \hbox ensues.\r
- \ifpdf\r
- \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.\r
- \else\r
- \ #2% The page number ends the paragraph.\r
- \fi\r
- \fi%\r
- \par\r
-\endgroup}\r
-\r
-% Like \dotfill except takes at least 1 em.\r
-\def\indexdotfill{\cleaders\r
- \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill}\r
-\r
-\def\primary #1{\line{#1\hfil}}\r
-\r
-\newskip\secondaryindent \secondaryindent=0.5cm\r
-\r
-\def\secondary #1#2{\r
-{\parfillskip=0in \parskip=0in\r
-\hangindent =1in \hangafter=1\r
-\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par\r
-}}\r
-\r
-% Define two-column mode, which we use to typeset indexes.\r
-% Adapted from the TeXbook, page 416, which is to say,\r
-% the manmac.tex format used to print the TeXbook itself.\r
-\catcode`\@=11\r
-\r
-\newbox\partialpage\r
-\newdimen\doublecolumnhsize\r
-\r
-\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns\r
- % Grab any single-column material above us.\r
- \output = {%\r
- %\r
- % Here is a possibility not foreseen in manmac: if we accumulate a\r
- % whole lot of material, we might end up calling this \output\r
- % routine twice in a row (see the doublecol-lose test, which is\r
- % essentially a couple of indexes with @setchapternewpage off). In\r
- % that case we just ship out what is in \partialpage with the normal\r
- % output routine. Generally, \partialpage will be empty when this\r
- % runs and this will be a no-op. See the indexspread.tex test case.\r
- \ifvoid\partialpage \else\r
- \onepageout{\pagecontents\partialpage}%\r
- \fi\r
- %\r
- \global\setbox\partialpage = \vbox{%\r
- % Unvbox the main output page.\r
- \unvbox\PAGE\r
- \kern-\topskip \kern\baselineskip\r
- }%\r
- }%\r
- \eject % run that output routine to set \partialpage\r
- %\r
- % Use the double-column output routine for subsequent pages.\r
- \output = {\doublecolumnout}%\r
- %\r
- % Change the page size parameters. We could do this once outside this\r
- % routine, in each of @smallbook, @afourpaper, and the default 8.5x11\r
- % format, but then we repeat the same computation. Repeating a couple\r
- % of assignments once per index is clearly meaningless for the\r
- % execution time, so we may as well do it in one place.\r
- %\r
- % First we halve the line length, less a little for the gutter between\r
- % the columns. We compute the gutter based on the line length, so it\r
- % changes automatically with the paper format. The magic constant\r
- % below is chosen so that the gutter has the same value (well, +-<1pt)\r
- % as it did when we hard-coded it.\r
- %\r
- % We put the result in a separate register, \doublecolumhsize, so we\r
- % can restore it in \pagesofar, after \hsize itself has (potentially)\r
- % been clobbered.\r
- %\r
- \doublecolumnhsize = \hsize\r
- \advance\doublecolumnhsize by -.04154\hsize\r
- \divide\doublecolumnhsize by 2\r
- \hsize = \doublecolumnhsize\r
- %\r
- % Double the \vsize as well. (We don't need a separate register here,\r
- % since nobody clobbers \vsize.)\r
- \advance\vsize by -\ht\partialpage\r
- \vsize = 2\vsize\r
-}\r
-\r
-% The double-column output routine for all double-column pages except\r
-% the last.\r
-%\r
-\def\doublecolumnout{%\r
- \splittopskip=\topskip \splitmaxdepth=\maxdepth\r
- % Get the available space for the double columns -- the normal\r
- % (undoubled) page height minus any material left over from the\r
- % previous page.\r
- \dimen@ = \vsize\r
- \divide\dimen@ by 2\r
- %\r
- % box0 will be the left-hand column, box2 the right.\r
- \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@\r
- \onepageout\pagesofar\r
- \unvbox255\r
- \penalty\outputpenalty\r
-}\r
-\def\pagesofar{%\r
- % Re-output the contents of the output page -- any previous material,\r
- % followed by the two boxes we just split, in box0 and box2.\r
- \unvbox\partialpage\r
- %\r
- \hsize = \doublecolumnhsize\r
- \wd0=\hsize \wd2=\hsize\r
- \hbox to\pagewidth{\box0\hfil\box2}%\r
-}\r
-\def\enddoublecolumns{%\r
- \output = {%\r
- % Split the last of the double-column material. Leave it on the\r
- % current page, no automatic page break.\r
- \balancecolumns\r
- %\r
- % If we end up splitting too much material for the current page,\r
- % though, there will be another page break right after this \output\r
- % invocation ends. Having called \balancecolumns once, we do not\r
- % want to call it again. Therefore, reset \output to its normal\r
- % definition right away. (We hope \balancecolumns will never be\r
- % called on to balance too much material, but if it is, this makes\r
- % the output somewhat more palatable.)\r
- \global\output = {\onepageout{\pagecontents\PAGE}}%\r
- }%\r
- \eject\r
- \endgroup % started in \begindoublecolumns\r
- %\r
- % \pagegoal was set to the doubled \vsize above, since we restarted\r
- % the current page. We're now back to normal single-column\r
- % typesetting, so reset \pagegoal to the normal \vsize (after the\r
- % \endgroup where \vsize got restored).\r
- \pagegoal = \vsize\r
-}\r
-\def\balancecolumns{%\r
- % Called at the end of the double column material.\r
- \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.\r
- \dimen@ = \ht0\r
- \advance\dimen@ by \topskip\r
- \advance\dimen@ by-\baselineskip\r
- \divide\dimen@ by 2 % target to split to\r
- %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}%\r
- \splittopskip = \topskip\r
- % Loop until we get a decent breakpoint.\r
- {%\r
- \vbadness = 10000\r
- \loop\r
- \global\setbox3 = \copy0\r
- \global\setbox1 = \vsplit3 to \dimen@\r
- \ifdim\ht3>\dimen@\r
- \global\advance\dimen@ by 1pt\r
- \repeat\r
- }%\r
- %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}%\r
- \setbox0=\vbox to\dimen@{\unvbox1}%\r
- \setbox2=\vbox to\dimen@{\unvbox3}%\r
- %\r
- \pagesofar\r
-}\r
-\catcode`\@ = \other\r
-\r
-\r
-\message{sectioning,}\r
-% Chapters, sections, etc.\r
-\r
-\newcount\chapno\r
-\newcount\secno \secno=0\r
-\newcount\subsecno \subsecno=0\r
-\newcount\subsubsecno \subsubsecno=0\r
-\r
-% This counter is funny since it counts through charcodes of letters A, B, ...\r
-\newcount\appendixno \appendixno = `\@\r
-% \def\appendixletter{\char\the\appendixno}\r
-% We do the following for the sake of pdftex, which needs the actual\r
-% letter in the expansion, not just typeset.\r
-\def\appendixletter{%\r
- \ifnum\appendixno=`A A%\r
- \else\ifnum\appendixno=`B B%\r
- \else\ifnum\appendixno=`C C%\r
- \else\ifnum\appendixno=`D D%\r
- \else\ifnum\appendixno=`E E%\r
- \else\ifnum\appendixno=`F F%\r
- \else\ifnum\appendixno=`G G%\r
- \else\ifnum\appendixno=`H H%\r
- \else\ifnum\appendixno=`I I%\r
- \else\ifnum\appendixno=`J J%\r
- \else\ifnum\appendixno=`K K%\r
- \else\ifnum\appendixno=`L L%\r
- \else\ifnum\appendixno=`M M%\r
- \else\ifnum\appendixno=`N N%\r
- \else\ifnum\appendixno=`O O%\r
- \else\ifnum\appendixno=`P P%\r
- \else\ifnum\appendixno=`Q Q%\r
- \else\ifnum\appendixno=`R R%\r
- \else\ifnum\appendixno=`S S%\r
- \else\ifnum\appendixno=`T T%\r
- \else\ifnum\appendixno=`U U%\r
- \else\ifnum\appendixno=`V V%\r
- \else\ifnum\appendixno=`W W%\r
- \else\ifnum\appendixno=`X X%\r
- \else\ifnum\appendixno=`Y Y%\r
- \else\ifnum\appendixno=`Z Z%\r
- % The \the is necessary, despite appearances, because \appendixletter is\r
- % expanded while writing the .toc file. \char\appendixno is not\r
- % expandable, thus it is written literally, thus all appendixes come out\r
- % with the same letter (or @) in the toc without it.\r
- \else\char\the\appendixno\r
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\r
- \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}\r
-\r
-% Each @chapter defines this as the name of the chapter.\r
-% page headings and footings can use it. @section does likewise.\r
-\def\thischapter{}\r
-\def\thissection{}\r
-\r
-\newcount\absseclevel % used to calculate proper heading level\r
-\newcount\secbase\secbase=0 % @raise/lowersections modify this count\r
-\r
-% @raisesections: treat @section as chapter, @subsection as section, etc.\r
-\def\raisesections{\global\advance\secbase by -1}\r
-\let\up=\raisesections % original BFox name\r
-\r
-% @lowersections: treat @chapter as section, @section as subsection, etc.\r
-\def\lowersections{\global\advance\secbase by 1}\r
-\let\down=\lowersections % original BFox name\r
-\r
-% Choose a numbered-heading macro\r
-% #1 is heading level if unmodified by @raisesections or @lowersections\r
-% #2 is text for heading\r
-\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1\r
-\ifcase\absseclevel\r
- \chapterzzz{#2}\r
-\or\r
- \seczzz{#2}\r
-\or\r
- \numberedsubseczzz{#2}\r
-\or\r
- \numberedsubsubseczzz{#2}\r
-\else\r
- \ifnum \absseclevel<0\r
- \chapterzzz{#2}\r
- \else\r
- \numberedsubsubseczzz{#2}\r
- \fi\r
-\fi\r
-}\r
-\r
-% like \numhead, but chooses appendix heading levels\r
-\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1\r
-\ifcase\absseclevel\r
- \appendixzzz{#2}\r
-\or\r
- \appendixsectionzzz{#2}\r
-\or\r
- \appendixsubseczzz{#2}\r
-\or\r
- \appendixsubsubseczzz{#2}\r
-\else\r
- \ifnum \absseclevel<0\r
- \appendixzzz{#2}\r
- \else\r
- \appendixsubsubseczzz{#2}\r
- \fi\r
-\fi\r
-}\r
-\r
-% like \numhead, but chooses numberless heading levels\r
-\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1\r
-\ifcase\absseclevel\r
- \unnumberedzzz{#2}\r
-\or\r
- \unnumberedseczzz{#2}\r
-\or\r
- \unnumberedsubseczzz{#2}\r
-\or\r
- \unnumberedsubsubseczzz{#2}\r
-\else\r
- \ifnum \absseclevel<0\r
- \unnumberedzzz{#2}\r
- \else\r
- \unnumberedsubsubseczzz{#2}\r
- \fi\r
-\fi\r
-}\r
-\r
-% @chapter, @appendix, @unnumbered.\r
-\def\thischaptername{No Chapter Title}\r
-\outer\def\chapter{\parsearg\chapteryyy}\r
-\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz\r
-\def\chapterzzz #1{%\r
-\secno=0 \subsecno=0 \subsubsecno=0\r
-\global\advance \chapno by 1 \message{\putwordChapter\space \the\chapno}%\r
-\chapmacro {#1}{\the\chapno}%\r
-\gdef\thissection{#1}%\r
-\gdef\thischaptername{#1}%\r
-% We don't substitute the actual chapter name into \thischapter\r
-% because we don't want its macros evaluated now.\r
-\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash chapentry{\the\toks0}%\r
- {\the\chapno}}}%\r
-\temp\r
-\donoderef\r
-\global\let\section = \numberedsec\r
-\global\let\subsection = \numberedsubsec\r
-\global\let\subsubsection = \numberedsubsubsec\r
-}\r
-\r
-\outer\def\appendix{\parsearg\appendixyyy}\r
-\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz\r
-\def\appendixzzz #1{%\r
-\secno=0 \subsecno=0 \subsubsecno=0\r
-\global\advance \appendixno by 1\r
-\message{\putwordAppendix\space \appendixletter}%\r
-\chapmacro {#1}{\putwordAppendix{} \appendixletter}%\r
-\gdef\thissection{#1}%\r
-\gdef\thischaptername{#1}%\r
-\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash chapentry{\the\toks0}%\r
- {\putwordAppendix{} \appendixletter}}}%\r
-\temp\r
-\appendixnoderef\r
-\global\let\section = \appendixsec\r
-\global\let\subsection = \appendixsubsec\r
-\global\let\subsubsection = \appendixsubsubsec\r
-}\r
-\r
-% @centerchap is like @unnumbered, but the heading is centered.\r
-\outer\def\centerchap{\parsearg\centerchapyyy}\r
-\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}}\r
-\r
-% @top is like @unnumbered.\r
-\outer\def\top{\parsearg\unnumberedyyy}\r
-\r
-\outer\def\unnumbered{\parsearg\unnumberedyyy}\r
-\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz\r
-\def\unnumberedzzz #1{%\r
-\secno=0 \subsecno=0 \subsubsecno=0\r
-%\r
-% This used to be simply \message{#1}, but TeX fully expands the\r
-% argument to \message. Therefore, if #1 contained @-commands, TeX\r
-% expanded them. For example, in `@unnumbered The @cite{Book}', TeX\r
-% expanded @cite (which turns out to cause errors because \cite is meant\r
-% to be executed, not expanded).\r
-%\r
-% Anyway, we don't want the fully-expanded definition of @cite to appear\r
-% as a result of the \message, we just want `@cite' itself. We use\r
-% \the<toks register> to achieve this: TeX expands \the<toks> only once,\r
-% simply yielding the contents of <toks register>. (We also do this for\r
-% the toc entries.)\r
-\toks0 = {#1}\message{(\the\toks0)}%\r
-%\r
-\unnumbchapmacro {#1}%\r
-\gdef\thischapter{#1}\gdef\thissection{#1}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash unnumbchapentry{\the\toks0}}}%\r
-\temp\r
-\unnumbnoderef\r
-\global\let\section = \unnumberedsec\r
-\global\let\subsection = \unnumberedsubsec\r
-\global\let\subsubsection = \unnumberedsubsubsec\r
-}\r
-\r
-% Sections.\r
-\outer\def\numberedsec{\parsearg\secyyy}\r
-\def\secyyy #1{\numhead1{#1}} % normally calls seczzz\r
-\def\seczzz #1{%\r
-\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 %\r
-\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash secentry{\the\toks0}%\r
- {\the\chapno}{\the\secno}}}%\r
-\temp\r
-\donoderef\r
-\nobreak\r
-}\r
-\r
-\outer\def\appendixsection{\parsearg\appendixsecyyy}\r
-\outer\def\appendixsec{\parsearg\appendixsecyyy}\r
-\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz\r
-\def\appendixsectionzzz #1{%\r
-\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 %\r
-\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash secentry{\the\toks0}%\r
- {\appendixletter}{\the\secno}}}%\r
-\temp\r
-\appendixnoderef\r
-\nobreak\r
-}\r
-\r
-\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy}\r
-\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz\r
-\def\unnumberedseczzz #1{%\r
-\plainsecheading {#1}\gdef\thissection{#1}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry{\the\toks0}}}%\r
-\temp\r
-\unnumbnoderef\r
-\nobreak\r
-}\r
-\r
-% Subsections.\r
-\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy}\r
-\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz\r
-\def\numberedsubseczzz #1{%\r
-\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 %\r
-\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash subsecentry{\the\toks0}%\r
- {\the\chapno}{\the\secno}{\the\subsecno}}}%\r
-\temp\r
-\donoderef\r
-\nobreak\r
-}\r
-\r
-\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy}\r
-\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz\r
-\def\appendixsubseczzz #1{%\r
-\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 %\r
-\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash subsecentry{\the\toks0}%\r
- {\appendixletter}{\the\secno}{\the\subsecno}}}%\r
-\temp\r
-\appendixnoderef\r
-\nobreak\r
-}\r
-\r
-\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy}\r
-\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz\r
-\def\unnumberedsubseczzz #1{%\r
-\plainsubsecheading {#1}\gdef\thissection{#1}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsecentry%\r
- {\the\toks0}}}%\r
-\temp\r
-\unnumbnoderef\r
-\nobreak\r
-}\r
-\r
-% Subsubsections.\r
-\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy}\r
-\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz\r
-\def\numberedsubsubseczzz #1{%\r
-\gdef\thissection{#1}\global\advance \subsubsecno by 1 %\r
-\subsubsecheading {#1}\r
- {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash subsubsecentry{\the\toks0}%\r
- {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}%\r
-\temp\r
-\donoderef\r
-\nobreak\r
-}\r
-\r
-\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy}\r
-\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz\r
-\def\appendixsubsubseczzz #1{%\r
-\gdef\thissection{#1}\global\advance \subsubsecno by 1 %\r
-\subsubsecheading {#1}\r
- {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash subsubsecentry{\the\toks0}%\r
- {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}%\r
-\temp\r
-\appendixnoderef\r
-\nobreak\r
-}\r
-\r
-\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy}\r
-\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz\r
-\def\unnumberedsubsubseczzz #1{%\r
-\plainsubsubsecheading {#1}\gdef\thissection{#1}%\r
-\toks0 = {#1}%\r
-\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsubsecentry%\r
- {\the\toks0}}}%\r
-\temp\r
-\unnumbnoderef\r
-\nobreak\r
-}\r
-\r
-% These are variants which are not "outer", so they can appear in @ifinfo.\r
-% Actually, they should now be obsolete; ordinary section commands should work.\r
-\def\infotop{\parsearg\unnumberedzzz}\r
-\def\infounnumbered{\parsearg\unnumberedzzz}\r
-\def\infounnumberedsec{\parsearg\unnumberedseczzz}\r
-\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz}\r
-\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz}\r
-\r
-\def\infoappendix{\parsearg\appendixzzz}\r
-\def\infoappendixsec{\parsearg\appendixseczzz}\r
-\def\infoappendixsubsec{\parsearg\appendixsubseczzz}\r
-\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz}\r
-\r
-\def\infochapter{\parsearg\chapterzzz}\r
-\def\infosection{\parsearg\sectionzzz}\r
-\def\infosubsection{\parsearg\subsectionzzz}\r
-\def\infosubsubsection{\parsearg\subsubsectionzzz}\r
-\r
-% These macros control what the section commands do, according\r
-% to what kind of chapter we are in (ordinary, appendix, or unnumbered).\r
-% Define them by default for a numbered chapter.\r
-\global\let\section = \numberedsec\r
-\global\let\subsection = \numberedsubsec\r
-\global\let\subsubsection = \numberedsubsubsec\r
-\r
-% Define @majorheading, @heading and @subheading\r
-\r
-% NOTE on use of \vbox for chapter headings, section headings, and such:\r
-% 1) We use \vbox rather than the earlier \line to permit\r
-% overlong headings to fold.\r
-% 2) \hyphenpenalty is set to 10000 because hyphenation in a\r
-% heading is obnoxious; this forbids it.\r
-% 3) Likewise, headings look best if no \parindent is used, and\r
-% if justification is not attempted. Hence \raggedright.\r
-\r
-\r
-\def\majorheading{\parsearg\majorheadingzzz}\r
-\def\majorheadingzzz #1{%\r
-{\advance\chapheadingskip by 10pt \chapbreak }%\r
-{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000\r
- \parindent=0pt\raggedright\r
- \rm #1\hfill}}\bigskip \par\penalty 200}\r
-\r
-\def\chapheading{\parsearg\chapheadingzzz}\r
-\def\chapheadingzzz #1{\chapbreak %\r
-{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000\r
- \parindent=0pt\raggedright\r
- \rm #1\hfill}}\bigskip \par\penalty 200}\r
-\r
-% @heading, @subheading, @subsubheading.\r
-\def\heading{\parsearg\plainsecheading}\r
-\def\subheading{\parsearg\plainsubsecheading}\r
-\def\subsubheading{\parsearg\plainsubsubsecheading}\r
-\r
-% These macros generate a chapter, section, etc. heading only\r
-% (including whitespace, linebreaking, etc. around it),\r
-% given all the information in convenient, parsed form.\r
-\r
-%%% Args are the skip and penalty (usually negative)\r
-\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}\r
-\r
-\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}\r
-\r
-%%% Define plain chapter starts, and page on/off switching for it\r
-% Parameter controlling skip before chapter headings (if needed)\r
-\r
-\newskip\chapheadingskip\r
-\r
-\def\chapbreak{\dobreak \chapheadingskip {-4000}}\r
-\def\chappager{\par\vfill\supereject}\r
-\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi}\r
-\r
-\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}\r
-\r
-\def\CHAPPAGoff{%\r
-\global\let\contentsalignmacro = \chappager\r
-\global\let\pchapsepmacro=\chapbreak\r
-\global\let\pagealignmacro=\chappager}\r
-\r
-\def\CHAPPAGon{%\r
-\global\let\contentsalignmacro = \chappager\r
-\global\let\pchapsepmacro=\chappager\r
-\global\let\pagealignmacro=\chappager\r
-\global\def\HEADINGSon{\HEADINGSsingle}}\r
-\r
-\def\CHAPPAGodd{\r
-\global\let\contentsalignmacro = \chapoddpage\r
-\global\let\pchapsepmacro=\chapoddpage\r
-\global\let\pagealignmacro=\chapoddpage\r
-\global\def\HEADINGSon{\HEADINGSdouble}}\r
-\r
-\CHAPPAGon\r
-\r
-\def\CHAPFplain{\r
-\global\let\chapmacro=\chfplain\r
-\global\let\unnumbchapmacro=\unnchfplain\r
-\global\let\centerchapmacro=\centerchfplain}\r
-\r
-% Plain chapter opening.\r
-% #1 is the text, #2 the chapter number or empty if unnumbered.\r
-\def\chfplain#1#2{%\r
- \pchapsepmacro\r
- {%\r
- \chapfonts \rm\r
- \def\chapnum{#2}%\r
- \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}%\r
- \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright\r
- \hangindent = \wd0 \centerparametersmaybe\r
- \unhbox0 #1\par}%\r
- }%\r
- \nobreak\bigskip % no page break after a chapter title\r
- \nobreak\r
-}\r
-\r
-% Plain opening for unnumbered.\r
-\def\unnchfplain#1{\chfplain{#1}{}}\r
-\r
-% @centerchap -- centered and unnumbered.\r
-\let\centerparametersmaybe = \relax\r
-\def\centerchfplain#1{{%\r
- \def\centerparametersmaybe{%\r
- \advance\rightskip by 3\rightskip\r
- \leftskip = \rightskip\r
- \parfillskip = 0pt\r
- }%\r
- \chfplain{#1}{}%\r
-}}\r
-\r
-\CHAPFplain % The default\r
-\r
-\def\unnchfopen #1{%\r
-\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000\r
- \parindent=0pt\raggedright\r
- \rm #1\hfill}}\bigskip \par\nobreak\r
-}\r
-\r
-\def\chfopen #1#2{\chapoddpage {\chapfonts\r
-\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%\r
-\par\penalty 5000 %\r
-}\r
-\r
-\def\centerchfopen #1{%\r
-\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000\r
- \parindent=0pt\r
- \hfill {\rm #1}\hfill}}\bigskip \par\nobreak\r
-}\r
-\r
-\def\CHAPFopen{\r
-\global\let\chapmacro=\chfopen\r
-\global\let\unnumbchapmacro=\unnchfopen\r
-\global\let\centerchapmacro=\centerchfopen}\r
-\r
-\r
-% Section titles.\r
-\newskip\secheadingskip\r
-\def\secheadingbreak{\dobreak \secheadingskip {-1000}}\r
-\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}}\r
-\def\plainsecheading#1{\sectionheading{sec}{}{#1}}\r
-\r
-% Subsection titles.\r
-\newskip \subsecheadingskip\r
-\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}}\r
-\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}}\r
-\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}}\r
-\r
-% Subsubsection titles.\r
-\let\subsubsecheadingskip = \subsecheadingskip\r
-\let\subsubsecheadingbreak = \subsecheadingbreak\r
-\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}}\r
-\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}}\r
-\r
-\r
-% Print any size section title.\r
-%\r
-% #1 is the section type (sec/subsec/subsubsec), #2 is the section\r
-% number (maybe empty), #3 the text.\r
-\def\sectionheading#1#2#3{%\r
- {%\r
- \expandafter\advance\csname #1headingskip\endcsname by \parskip\r
- \csname #1headingbreak\endcsname\r
- }%\r
- {%\r
- % Switch to the right set of fonts.\r
- \csname #1fonts\endcsname \rm\r
- %\r
- % Only insert the separating space if we have a section number.\r
- \def\secnum{#2}%\r
- \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}%\r
- %\r
- \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright\r
- \hangindent = \wd0 % zero if no section number\r
- \unhbox0 #3}%\r
- }%\r
- \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak\r
-}\r
-\r
-\r
-\message{toc,}\r
-% Table of contents.\r
-\newwrite\tocfile\r
-\r
-% Write an entry to the toc file, opening it if necessary.\r
-% Called from @chapter, etc. We supply {\folio} at the end of the\r
-% argument, which will end up as the last argument to the \...entry macro.\r
-%\r
-% We open the .toc file here instead of at @setfilename or any other\r
-% given time so that @contents can be put in the document anywhere.\r
-%\r
-\newif\iftocfileopened\r
-\def\writetocentry#1{%\r
- \iftocfileopened\else\r
- \immediate\openout\tocfile = \jobname.toc\r
- \global\tocfileopenedtrue\r
- \fi\r
- \iflinks \write\tocfile{#1{\folio}}\fi\r
-}\r
-\r
-\newskip\contentsrightmargin \contentsrightmargin=1in\r
-\newcount\savepageno\r
-\newcount\lastnegativepageno \lastnegativepageno = -1\r
-\r
-% Finish up the main text and prepare to read what we've written\r
-% to \tocfile.\r
-%\r
-\def\startcontents#1{%\r
- % If @setchapternewpage on, and @headings double, the contents should\r
- % start on an odd page, unlike chapters. Thus, we maintain\r
- % \contentsalignmacro in parallel with \pagealignmacro.\r
- % From: Torbjorn Granlund <tege@matematik.su.se>\r
- \contentsalignmacro\r
- \immediate\closeout\tocfile\r
- %\r
- % Don't need to put `Contents' or `Short Contents' in the headline.\r
- % It is abundantly clear what they are.\r
- \unnumbchapmacro{#1}\def\thischapter{}%\r
- \savepageno = \pageno\r
- \begingroup % Set up to handle contents files properly.\r
- \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11\r
- % We can't do this, because then an actual ^ in a section\r
- % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97.\r
- %\catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi\r
- \raggedbottom % Worry more about breakpoints than the bottom.\r
- \advance\hsize by -\contentsrightmargin % Don't use the full line length.\r
- %\r
- % Roman numerals for page numbers.\r
- \ifnum \pageno>0 \pageno = \lastnegativepageno \fi\r
-}\r
-\r
-\r
-% Normal (long) toc.\r
-\def\contents{%\r
- \startcontents{\putwordTOC}%\r
- \openin 1 \jobname.toc\r
- \ifeof 1 \else\r
- \closein 1\r
- \input \jobname.toc\r
- \fi\r
- \vfill \eject\r
- \contentsalignmacro % in case @setchapternewpage odd is in effect\r
- \pdfmakeoutlines\r
- \endgroup\r
- \lastnegativepageno = \pageno\r
- \pageno = \savepageno\r
-}\r
-\r
-% And just the chapters.\r
-\def\summarycontents{%\r
- \startcontents{\putwordShortTOC}%\r
- %\r
- \let\chapentry = \shortchapentry\r
- \let\unnumbchapentry = \shortunnumberedentry\r
- % We want a true roman here for the page numbers.\r
- \secfonts\r
- \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl\r
- \rm\r
- \hyphenpenalty = 10000\r
- \advance\baselineskip by 1pt % Open it up a little.\r
- \def\secentry ##1##2##3##4{}\r
- \def\unnumbsecentry ##1##2{}\r
- \def\subsecentry ##1##2##3##4##5{}\r
- \def\unnumbsubsecentry ##1##2{}\r
- \def\subsubsecentry ##1##2##3##4##5##6{}\r
- \def\unnumbsubsubsecentry ##1##2{}\r
- \openin 1 \jobname.toc\r
- \ifeof 1 \else\r
- \closein 1\r
- \input \jobname.toc\r
- \fi\r
- \vfill \eject\r
- \contentsalignmacro % in case @setchapternewpage odd is in effect\r
- \endgroup\r
- \lastnegativepageno = \pageno\r
- \pageno = \savepageno\r
-}\r
-\let\shortcontents = \summarycontents\r
-\r
-\ifpdf\r
- \pdfcatalog{/PageMode /UseOutlines}%\r
-\fi\r
-\r
-% These macros generate individual entries in the table of contents.\r
-% The first argument is the chapter or section name.\r
-% The last argument is the page number.\r
-% The arguments in between are the chapter number, section number, ...\r
-\r
-% Chapter-level things, for both the long and short contents.\r
-\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}}\r
-\r
-% See comments in \dochapentry re vbox and related settings\r
-\def\shortchapentry#1#2#3{%\r
- \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#3\egroup}%\r
-}\r
-\r
-% Typeset the label for a chapter or appendix for the short contents.\r
-% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter.\r
-% We could simplify the code here by writing out an \appendixentry\r
-% command in the toc file for appendices, instead of using \chapentry\r
-% for both, but it doesn't seem worth it.\r
-%\r
-\newdimen\shortappendixwidth\r
-%\r
-\def\shortchaplabel#1{%\r
- % Compute width of word "Appendix", may change with language.\r
- \setbox0 = \hbox{\shortcontrm \putwordAppendix}%\r
- \shortappendixwidth = \wd0\r
- %\r
- % We typeset #1 in a box of constant width, regardless of the text of\r
- % #1, so the chapter titles will come out aligned.\r
- \setbox0 = \hbox{#1}%\r
- \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi\r
- %\r
- % This space should be plenty, since a single number is .5em, and the\r
- % widest letter (M) is 1em, at least in the Computer Modern fonts.\r
- % (This space doesn't include the extra space that gets added after\r
- % the label; that gets put in by \shortchapentry above.)\r
- \advance\dimen0 by 1.1em\r
- \hbox to \dimen0{#1\hfil}%\r
-}\r
-\r
-\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}}\r
-\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno\bgroup#2\egroup}}\r
-\r
-% Sections.\r
-\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}}\r
-\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}}\r
-\r
-% Subsections.\r
-\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}}\r
-\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}}\r
-\r
-% And subsubsections.\r
-\def\subsubsecentry#1#2#3#4#5#6{%\r
- \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}}\r
-\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}}\r
-\r
-% This parameter controls the indentation of the various levels.\r
-\newdimen\tocindent \tocindent = 3pc\r
-\r
-% Now for the actual typesetting. In all these, #1 is the text and #2 is the\r
-% page number.\r
-%\r
-% If the toc has to be broken over pages, we want it to be at chapters\r
-% if at all possible; hence the \penalty.\r
-\def\dochapentry#1#2{%\r
- \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip\r
- \begingroup\r
- \chapentryfonts\r
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%\r
- \endgroup\r
- \nobreak\vskip .25\baselineskip plus.1\baselineskip\r
-}\r
-\r
-\def\dosecentry#1#2{\begingroup\r
- \secentryfonts \leftskip=\tocindent\r
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%\r
-\endgroup}\r
-\r
-\def\dosubsecentry#1#2{\begingroup\r
- \subsecentryfonts \leftskip=2\tocindent\r
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%\r
-\endgroup}\r
-\r
-\def\dosubsubsecentry#1#2{\begingroup\r
- \subsubsecentryfonts \leftskip=3\tocindent\r
- \tocentry{#1}{\dopageno\bgroup#2\egroup}%\r
-\endgroup}\r
-\r
-% Final typesetting of a toc entry; we use the same \entry macro as for\r
-% the index entries, but we want to suppress hyphenation here. (We\r
-% can't do that in the \entry macro, since index entries might consist\r
-% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.)\r
-\def\tocentry#1#2{\begingroup\r
- \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks\r
- % Do not use \turnoffactive in these arguments. Since the toc is\r
- % typeset in cmr, so characters such as _ would come out wrong; we\r
- % have to do the usual translation tricks.\r
- \entry{#1}{#2}%\r
-\endgroup}\r
-\r
-% Space between chapter (or whatever) number and the title.\r
-\def\labelspace{\hskip1em \relax}\r
-\r
-\def\dopageno#1{{\rm #1}}\r
-\def\doshortpageno#1{{\rm #1}}\r
-\r
-\def\chapentryfonts{\secfonts \rm}\r
-\def\secentryfonts{\textfonts}\r
-\let\subsecentryfonts = \textfonts\r
-\let\subsubsecentryfonts = \textfonts\r
-\r
-\r
-\message{environments,}\r
-% @foo ... @end foo.\r
-\r
-% Since these characters are used in examples, it should be an even number of\r
-% \tt widths. Each \tt character is 1en, so two makes it 1em.\r
-% Furthermore, these definitions must come after we define our fonts.\r
-\newbox\dblarrowbox \newbox\longdblarrowbox\r
-\newbox\pushcharbox \newbox\bullbox\r
-\newbox\equivbox \newbox\errorbox\r
-\r
-%{\tentt\r
-%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil}\r
-%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil}\r
-%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil}\r
-%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil}\r
-% Adapted from the manmac format (p.420 of TeXbook)\r
-%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex\r
-% depth .1ex\hfil}\r
-%}\r
-\r
-% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.\r
-\def\point{$\star$}\r
-\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}\r
-\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}}\r
-\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}\r
-\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}\r
-\r
-% Adapted from the TeXbook's \boxit.\r
-{\tentt \global\dimen0 = 3em}% Width of the box.\r
-\dimen2 = .55pt % Thickness of rules\r
-% The text. (`r' is open on the right, `e' somewhat less so on the left.)\r
-\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt}\r
-\r
-\global\setbox\errorbox=\hbox to \dimen0{\hfil\r
- \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.\r
- \advance\hsize by -2\dimen2 % Rules.\r
- \vbox{\r
- \hrule height\dimen2\r
- \hbox{\vrule width\dimen2 \kern3pt % Space to left of text.\r
- \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.\r
- \kern3pt\vrule width\dimen2}% Space to right.\r
- \hrule height\dimen2}\r
- \hfil}\r
-\r
-% The @error{} command.\r
-\def\error{\leavevmode\lower.7ex\copy\errorbox}\r
-\r
-% @tex ... @end tex escapes into raw Tex temporarily.\r
-% One exception: @ is still an escape character, so that @end tex works.\r
-% But \@ or @@ will get a plain tex @ character.\r
-\r
-\def\tex{\begingroup\r
- \catcode `\\=0 \catcode `\{=1 \catcode `\}=2\r
- \catcode `\$=3 \catcode `\&=4 \catcode `\#=6\r
- \catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie\r
- \catcode `\%=14\r
- \catcode 43=12 % plus\r
- \catcode`\"=12\r
- \catcode`\==12\r
- \catcode`\|=12\r
- \catcode`\<=12\r
- \catcode`\>=12\r
- \escapechar=`\\\r
- %\r
- \let\b=\ptexb\r
- \let\bullet=\ptexbullet\r
- \let\c=\ptexc\r
- \let\,=\ptexcomma\r
- \let\.=\ptexdot\r
- \let\dots=\ptexdots\r
- \let\equiv=\ptexequiv\r
- \let\!=\ptexexclam\r
- \let\i=\ptexi\r
- \let\{=\ptexlbrace\r
- \let\+=\tabalign\r
- \let\}=\ptexrbrace\r
- \let\*=\ptexstar\r
- \let\t=\ptext\r
- %\r
- \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%\r
- \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%\r
- \def\@{@}%\r
-\let\Etex=\endgroup}\r
-\r
-% Define @lisp ... @endlisp.\r
-% @lisp does a \begingroup so it can rebind things,\r
-% including the definition of @endlisp (which normally is erroneous).\r
-\r
-% Amount to narrow the margins by for @lisp.\r
-\newskip\lispnarrowing \lispnarrowing=0.4in\r
-\r
-% This is the definition that ^^M gets inside @lisp, @example, and other\r
-% such environments. \null is better than a space, since it doesn't\r
-% have any width.\r
-\def\lisppar{\null\endgraf}\r
-\r
-% Make each space character in the input produce a normal interword\r
-% space in the output. Don't allow a line break at this space, as this\r
-% is used only in environments like @example, where each line of input\r
-% should produce a line of output anyway.\r
-%\r
-{\obeyspaces %\r
-\gdef\sepspaces{\obeyspaces\let =\tie}}\r
-\r
-% Define \obeyedspace to be our active space, whatever it is. This is\r
-% for use in \parsearg.\r
-{\sepspaces%\r
-\global\let\obeyedspace= }\r
-\r
-% This space is always present above and below environments.\r
-\newskip\envskipamount \envskipamount = 0pt\r
-\r
-% Make spacing and below environment symmetrical. We use \parskip here\r
-% to help in doing that, since in @example-like environments \parskip\r
-% is reset to zero; thus the \afterenvbreak inserts no space -- but the\r
-% start of the next paragraph will insert \parskip\r
-%\r
-\def\aboveenvbreak{{\advance\envskipamount by \parskip\r
-\endgraf \ifdim\lastskip<\envskipamount\r
-\removelastskip \penalty-50 \vskip\envskipamount \fi}}\r
-\r
-\let\afterenvbreak = \aboveenvbreak\r
-\r
-% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins.\r
-\let\nonarrowing=\relax\r
-\r
-% @cartouche ... @end cartouche: draw rectangle w/rounded corners around\r
-% environment contents.\r
-\font\circle=lcircle10\r
-\newdimen\circthick\r
-\newdimen\cartouter\newdimen\cartinner\r
-\newskip\normbskip\newskip\normpskip\newskip\normlskip\r
-\circthick=\fontdimen8\circle\r
-%\r
-\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth\r
-\def\ctr{{\hskip 6pt\circle\char'010}}\r
-\def\cbl{{\circle\char'012\hskip -6pt}}\r
-\def\cbr{{\hskip 6pt\circle\char'011}}\r
-\def\carttop{\hbox to \cartouter{\hskip\lskip\r
- \ctl\leaders\hrule height\circthick\hfil\ctr\r
- \hskip\rskip}}\r
-\def\cartbot{\hbox to \cartouter{\hskip\lskip\r
- \cbl\leaders\hrule height\circthick\hfil\cbr\r
- \hskip\rskip}}\r
-%\r
-\newskip\lskip\newskip\rskip\r
-\r
-\long\def\cartouche{%\r
-\begingroup\r
- \lskip=\leftskip \rskip=\rightskip\r
- \leftskip=0pt\rightskip=0pt %we want these *outside*.\r
- \cartinner=\hsize \advance\cartinner by-\lskip\r
- \advance\cartinner by-\rskip\r
- \cartouter=\hsize\r
- \advance\cartouter by 18.4pt % allow for 3pt kerns on either\r
-% side, and for 6pt waste from\r
-% each corner char, and rule thickness\r
- \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip\r
- % Flag to tell @lisp, etc., not to narrow margin.\r
- \let\nonarrowing=\comment\r
- \vbox\bgroup\r
- \baselineskip=0pt\parskip=0pt\lineskip=0pt\r
- \carttop\r
- \hbox\bgroup\r
- \hskip\lskip\r
- \vrule\kern3pt\r
- \vbox\bgroup\r
- \hsize=\cartinner\r
- \kern3pt\r
- \begingroup\r
- \baselineskip=\normbskip\r
- \lineskip=\normlskip\r
- \parskip=\normpskip\r
- \vskip -\parskip\r
-\def\Ecartouche{%\r
- \endgroup\r
- \kern3pt\r
- \egroup\r
- \kern3pt\vrule\r
- \hskip\rskip\r
- \egroup\r
- \cartbot\r
- \egroup\r
-\endgroup\r
-}}\r
-\r
-\r
-% This macro is called at the beginning of all the @example variants,\r
-% inside a group.\r
-\def\nonfillstart{%\r
- \aboveenvbreak\r
- \inENV % This group ends at the end of the body\r
- \hfuzz = 12pt % Don't be fussy\r
- \sepspaces % Make spaces be word-separators rather than space tokens.\r
- \singlespace\r
- \let\par = \lisppar % don't ignore blank lines\r
- \obeylines % each line of input is a line of output\r
- \parskip = 0pt\r
- \parindent = 0pt\r
- \emergencystretch = 0pt % don't try to avoid overfull boxes\r
- % @cartouche defines \nonarrowing to inhibit narrowing\r
- % at next level down.\r
- \ifx\nonarrowing\relax\r
- \advance \leftskip by \lispnarrowing\r
- \exdentamount=\lispnarrowing\r
- \let\exdent=\nofillexdent\r
- \let\nonarrowing=\relax\r
- \fi\r
-}\r
-\r
-% Define the \E... control sequence only if we are inside the particular\r
-% environment, so the error checking in \end will work.\r
-%\r
-% To end an @example-like environment, we first end the paragraph (via\r
-% \afterenvbreak's vertical glue), and then the group. That way we keep\r
-% the zero \parskip that the environments set -- \parskip glue will be\r
-% inserted at the beginning of the next paragraph in the document, after\r
-% the environment.\r
-%\r
-\def\nonfillfinish{\afterenvbreak\endgroup}\r
-\r
-% @lisp: indented, narrowed, typewriter font.\r
-\def\lisp{\begingroup\r
- \nonfillstart\r
- \let\Elisp = \nonfillfinish\r
- \tt\r
- \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.\r
- \gobble % eat return\r
-}\r
-\r
-% @example: Same as @lisp.\r
-\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp}\r
-\r
-% @small... is usually equivalent to the non-small (@smallbook\r
-% redefines). We must call \example (or whatever) last in the\r
-% definition, since it reads the return following the @example (or\r
-% whatever) command.\r
-%\r
-% This actually allows (for example) @end display inside an\r
-% @smalldisplay. Too bad, but makeinfo will catch the error anyway.\r
-%\r
-\def\smalldisplay{\begingroup\def\Esmalldisplay{\nonfillfinish\endgroup}\display}\r
-\def\smallexample{\begingroup\def\Esmallexample{\nonfillfinish\endgroup}\lisp}\r
-\def\smallformat{\begingroup\def\Esmallformat{\nonfillfinish\endgroup}\format}\r
-\def\smalllisp{\begingroup\def\Esmalllisp{\nonfillfinish\endgroup}\lisp}\r
-\r
-% Real @smallexample and @smalllisp (when @smallbook): use smaller fonts.\r
-% Originally contributed by Pavel@xerox.\r
-\def\smalllispx{\begingroup\r
- \def\Esmalllisp{\nonfillfinish\endgroup}%\r
- \def\Esmallexample{\nonfillfinish\endgroup}%\r
- \smallfonts\r
- \lisp\r
-}\r
-\r
-% @display: same as @lisp except keep current font.\r
-%\r
-\def\display{\begingroup\r
- \nonfillstart\r
- \let\Edisplay = \nonfillfinish\r
- \gobble\r
-}\r
-\r
-% @smalldisplay (when @smallbook): @display plus smaller fonts.\r
-%\r
-\def\smalldisplayx{\begingroup\r
- \def\Esmalldisplay{\nonfillfinish\endgroup}%\r
- \smallfonts \rm\r
- \display\r
-}\r
-\r
-% @format: same as @display except don't narrow margins.\r
-%\r
-\def\format{\begingroup\r
- \let\nonarrowing = t\r
- \nonfillstart\r
- \let\Eformat = \nonfillfinish\r
- \gobble\r
-}\r
-\r
-% @smallformat (when @smallbook): @format plus smaller fonts.\r
-%\r
-\def\smallformatx{\begingroup\r
- \def\Esmallformat{\nonfillfinish\endgroup}%\r
- \smallfonts \rm\r
- \format\r
-}\r
-\r
-% @flushleft (same as @format).\r
-%\r
-\def\flushleft{\begingroup \def\Eflushleft{\nonfillfinish\endgroup}\format}\r
-\r
-% @flushright.\r
-%\r
-\def\flushright{\begingroup\r
- \let\nonarrowing = t\r
- \nonfillstart\r
- \let\Eflushright = \nonfillfinish\r
- \advance\leftskip by 0pt plus 1fill\r
- \gobble\r
-}\r
-\r
-% @quotation does normal linebreaking (hence we can't use \nonfillstart)\r
-% and narrows the margins.\r
-%\r
-\def\quotation{%\r
- \begingroup\inENV %This group ends at the end of the @quotation body\r
- {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip\r
- \singlespace\r
- \parindent=0pt\r
- % We have retained a nonzero parskip for the environment, since we're\r
- % doing normal filling. So to avoid extra space below the environment...\r
- \def\Equotation{\parskip = 0pt \nonfillfinish}%\r
- %\r
- % @cartouche defines \nonarrowing to inhibit narrowing at next level down.\r
- \ifx\nonarrowing\relax\r
- \advance\leftskip by \lispnarrowing\r
- \advance\rightskip by \lispnarrowing\r
- \exdentamount = \lispnarrowing\r
- \let\nonarrowing = \relax\r
- \fi\r
-}\r
-\r
-\r
-\message{defuns,}\r
-% @defun etc.\r
-\r
-% Allow user to change definition object font (\df) internally\r
-\def\setdeffont #1 {\csname DEF#1\endcsname}\r
-\r
-\newskip\defbodyindent \defbodyindent=.4in\r
-\newskip\defargsindent \defargsindent=50pt\r
-\newskip\deftypemargin \deftypemargin=12pt\r
-\newskip\deflastargmargin \deflastargmargin=18pt\r
-\r
-\newcount\parencount\r
-% define \functionparens, which makes ( and ) and & do special things.\r
-% \functionparens affects the group it is contained in.\r
-\def\activeparens{%\r
-\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active\r
-\catcode`\[=\active \catcode`\]=\active}\r
-\r
-% Make control sequences which act like normal parenthesis chars.\r
-\let\lparen = ( \let\rparen = )\r
-\r
-{\activeparens % Now, smart parens don't turn on until &foo (see \amprm)\r
-\r
-% Be sure that we always have a definition for `(', etc. For example,\r
-% if the fn name has parens in it, \boldbrax will not be in effect yet,\r
-% so TeX would otherwise complain about undefined control sequence.\r
-\global\let(=\lparen \global\let)=\rparen\r
-\global\let[=\lbrack \global\let]=\rbrack\r
-\r
-\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 }\r
-\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}\r
-% This is used to turn on special parens\r
-% but make & act ordinary (given that it's active).\r
-\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr}\r
-\r
-% Definitions of (, ) and & used in args for functions.\r
-% This is the definition of ( outside of all parentheses.\r
-\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested\r
- \global\advance\parencount by 1\r
-}\r
-%\r
-% This is the definition of ( when already inside a level of parens.\r
-\gdef\opnested{\char`\(\global\advance\parencount by 1 }\r
-%\r
-\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0.\r
- % also in that case restore the outer-level definition of (.\r
- \ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi\r
- \global\advance \parencount by -1 }\r
-% If we encounter &foo, then turn on ()-hacking afterwards\r
-\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ }\r
-%\r
-\gdef\normalparens{\boldbrax\let&=\ampnr}\r
-} % End of definition inside \activeparens\r
-%% These parens (in \boldbrax) actually are a little bolder than the\r
-%% contained text. This is especially needed for [ and ]\r
-\def\opnr{{\sf\char`\(}\global\advance\parencount by 1 }\r
-\def\clnr{{\sf\char`\)}\global\advance\parencount by -1 }\r
-\let\ampnr = \&\r
-\def\lbrb{{\bf\char`\[}}\r
-\def\rbrb{{\bf\char`\]}}\r
-\r
-% Active &'s sneak into the index arguments, so make sure it's defined.\r
-{\r
- \catcode`& = 13\r
- \global\let& = \ampnr\r
-}\r
-\r
-% First, defname, which formats the header line itself.\r
-% #1 should be the function name.\r
-% #2 should be the type of definition, such as "Function".\r
-\r
-\def\defname #1#2{%\r
-% Get the values of \leftskip and \rightskip as they were\r
-% outside the @def...\r
-\dimen2=\leftskip\r
-\advance\dimen2 by -\defbodyindent\r
-\noindent\r
-\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}%\r
-\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line\r
-\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations\r
-\parshape 2 0in \dimen0 \defargsindent \dimen1\r
-% Now output arg 2 ("Function" or some such)\r
-% ending at \deftypemargin from the right margin,\r
-% but stuck inside a box of width 0 so it does not interfere with linebreaking\r
-{% Adjust \hsize to exclude the ambient margins,\r
-% so that \rightline will obey them.\r
-\advance \hsize by -\dimen2\r
-\rlap{\rightline{{\rm #2}\hskip -1.25pc }}}%\r
-% Make all lines underfull and no complaints:\r
-\tolerance=10000 \hbadness=10000\r
-\advance\leftskip by -\defbodyindent\r
-\exdentamount=\defbodyindent\r
-{\df #1}\enskip % Generate function name\r
-}\r
-\r
-% Actually process the body of a definition\r
-% #1 should be the terminating control sequence, such as \Edefun.\r
-% #2 should be the "another name" control sequence, such as \defunx.\r
-% #3 should be the control sequence that actually processes the header,\r
-% such as \defunheader.\r
-\r
-\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody\r
-\medbreak %\r
-% Define the end token that this defining construct specifies\r
-% so that it will exit this group.\r
-\def#1{\endgraf\endgroup\medbreak}%\r
-\def#2{\begingroup\obeylines\activeparens\spacesplit#3}%\r
-\parindent=0in\r
-\advance\leftskip by \defbodyindent\r
-\exdentamount=\defbodyindent\r
-\begingroup %\r
-\catcode 61=\active % 61 is `='\r
-\obeylines\activeparens\spacesplit#3}\r
-\r
-% #1 is the \E... control sequence to end the definition (which we define).\r
-% #2 is the \...x control sequence for consecutive fns (which we define).\r
-% #3 is the control sequence to call to resume processing.\r
-% #4, delimited by the space, is the class name.\r
-%\r
-\def\defmethparsebody#1#2#3#4 {\begingroup\inENV %\r
-\medbreak %\r
-% Define the end token that this defining construct specifies\r
-% so that it will exit this group.\r
-\def#1{\endgraf\endgroup\medbreak}%\r
-\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}%\r
-\parindent=0in\r
-\advance\leftskip by \defbodyindent\r
-\exdentamount=\defbodyindent\r
-\begingroup\obeylines\activeparens\spacesplit{#3{#4}}}\r
-\r
-% Used for @deftypemethod and @deftypeivar.\r
-% #1 is the \E... control sequence to end the definition (which we define).\r
-% #2 is the \...x control sequence for consecutive fns (which we define).\r
-% #3 is the control sequence to call to resume processing.\r
-% #4, delimited by a space, is the class name.\r
-% #5 is the method's return type.\r
-%\r
-\def\deftypemethparsebody#1#2#3#4 #5 {\begingroup\inENV\r
- \medbreak\r
- \def#1{\endgraf\endgroup\medbreak}%\r
- \def#2##1 ##2 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}{##2}}}%\r
- \parindent=0in\r
- \advance\leftskip by \defbodyindent\r
- \exdentamount=\defbodyindent\r
- \begingroup\obeylines\activeparens\spacesplit{#3{#4}{#5}}}\r
-\r
-% Used for @deftypeop. The change from \deftypemethparsebody is an\r
-% extra argument at the beginning which is the `category', instead of it\r
-% being the hardwired string `Method' or `Instance Variable'. We have\r
-% to account for this both in the \...x definition and in parsing the\r
-% input at hand. Thus also need a control sequence (passed as #5) for\r
-% the \E... definition to assign the category name to.\r
-% \r
-\def\deftypeopparsebody#1#2#3#4#5 #6 {\begingroup\inENV\r
- \medbreak\r
- \def#1{\endgraf\endgroup\medbreak}%\r
- \def#2##1 ##2 ##3 {%\r
- \def#4{##1}%\r
- \begingroup\obeylines\activeparens\spacesplit{#3{##2}{##3}}}%\r
- \parindent=0in\r
- \advance\leftskip by \defbodyindent\r
- \exdentamount=\defbodyindent\r
- \begingroup\obeylines\activeparens\spacesplit{#3{#5}{#6}}}\r
-\r
-\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV %\r
-\medbreak %\r
-% Define the end token that this defining construct specifies\r
-% so that it will exit this group.\r
-\def#1{\endgraf\endgroup\medbreak}%\r
-\def#2##1 ##2 {\def#4{##1}%\r
-\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}%\r
-\parindent=0in\r
-\advance\leftskip by \defbodyindent\r
-\exdentamount=\defbodyindent\r
-\begingroup\obeylines\activeparens\spacesplit{#3{#5}}}\r
-\r
-% These parsing functions are similar to the preceding ones\r
-% except that they do not make parens into active characters.\r
-% These are used for "variables" since they have no arguments.\r
-\r
-\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody\r
-\medbreak %\r
-% Define the end token that this defining construct specifies\r
-% so that it will exit this group.\r
-\def#1{\endgraf\endgroup\medbreak}%\r
-\def#2{\begingroup\obeylines\spacesplit#3}%\r
-\parindent=0in\r
-\advance\leftskip by \defbodyindent\r
-\exdentamount=\defbodyindent\r
-\begingroup %\r
-\catcode 61=\active %\r
-\obeylines\spacesplit#3}\r
-\r
-% This is used for \def{tp,vr}parsebody. It could probably be used for\r
-% some of the others, too, with some judicious conditionals.\r
-%\r
-\def\parsebodycommon#1#2#3{%\r
- \begingroup\inENV %\r
- \medbreak %\r
- % Define the end token that this defining construct specifies\r
- % so that it will exit this group.\r
- \def#1{\endgraf\endgroup\medbreak}%\r
- \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}%\r
- \parindent=0in\r
- \advance\leftskip by \defbodyindent\r
- \exdentamount=\defbodyindent\r
- \begingroup\obeylines\r
-}\r
-\r
-\def\defvrparsebody#1#2#3#4 {%\r
- \parsebodycommon{#1}{#2}{#3}%\r
- \spacesplit{#3{#4}}%\r
-}\r
-\r
-% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the\r
-% type is just `struct', because we lose the braces in `{struct\r
-% termios}' when \spacesplit reads its undelimited argument. Sigh.\r
-% \let\deftpparsebody=\defvrparsebody\r
-%\r
-% So, to get around this, we put \empty in with the type name. That\r
-% way, TeX won't find exactly `{...}' as an undelimited argument, and\r
-% won't strip off the braces.\r
-%\r
-\def\deftpparsebody #1#2#3#4 {%\r
- \parsebodycommon{#1}{#2}{#3}%\r
- \spacesplit{\parsetpheaderline{#3{#4}}}\empty\r
-}\r
-\r
-% Fine, but then we have to eventually remove the \empty *and* the\r
-% braces (if any). That's what this does.\r
-%\r
-\def\removeemptybraces\empty#1\relax{#1}\r
-\r
-% After \spacesplit has done its work, this is called -- #1 is the final\r
-% thing to call, #2 the type name (which starts with \empty), and #3\r
-% (which might be empty) the arguments.\r
-%\r
-\def\parsetpheaderline#1#2#3{%\r
- #1{\removeemptybraces#2\relax}{#3}%\r
-}%\r
-\r
-\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV %\r
-\medbreak %\r
-% Define the end token that this defining construct specifies\r
-% so that it will exit this group.\r
-\def#1{\endgraf\endgroup\medbreak}%\r
-\def#2##1 ##2 {\def#4{##1}%\r
-\begingroup\obeylines\spacesplit{#3{##2}}}%\r
-\parindent=0in\r
-\advance\leftskip by \defbodyindent\r
-\exdentamount=\defbodyindent\r
-\begingroup\obeylines\spacesplit{#3{#5}}}\r
-\r
-% Split up #2 at the first space token.\r
-% call #1 with two arguments:\r
-% the first is all of #2 before the space token,\r
-% the second is all of #2 after that space token.\r
-% If #2 contains no space token, all of it is passed as the first arg\r
-% and the second is passed as empty.\r
-\r
-{\obeylines\r
-\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}%\r
-\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{%\r
-\ifx\relax #3%\r
-#1{#2}{}\else #1{#2}{#3#4}\fi}}\r
-\r
-% So much for the things common to all kinds of definitions.\r
-\r
-% Define @defun.\r
-\r
-% First, define the processing that is wanted for arguments of \defun\r
-% Use this to expand the args and terminate the paragraph they make up\r
-\r
-\def\defunargs#1{\functionparens \sl\r
-% Expand, preventing hyphenation at `-' chars.\r
-% Note that groups don't affect changes in \hyphenchar.\r
-% Set the font temporarily and use \font in case \setfont made \tensl a macro.\r
-{\tensl\hyphenchar\font=0}%\r
-#1%\r
-{\tensl\hyphenchar\font=45}%\r
-\ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi%\r
-\interlinepenalty=10000\r
-\advance\rightskip by 0pt plus 1fil\r
-\endgraf\nobreak\vskip -\parskip\nobreak\r
-}\r
-\r
-\def\deftypefunargs #1{%\r
-% Expand, preventing hyphenation at `-' chars.\r
-% Note that groups don't affect changes in \hyphenchar.\r
-% Use \boldbraxnoamp, not \functionparens, so that & is not special.\r
-\boldbraxnoamp\r
-\tclose{#1}% avoid \code because of side effects on active chars\r
-\interlinepenalty=10000\r
-\advance\rightskip by 0pt plus 1fil\r
-\endgraf\nobreak\vskip -\parskip\nobreak\r
-}\r
-\r
-% Do complete processing of one @defun or @defunx line already parsed.\r
-\r
-% @deffn Command forward-char nchars\r
-\r
-\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader}\r
-\r
-\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}%\r
-\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup %\r
-\catcode 61=\other % Turn off change made in \defparsebody\r
-}\r
-\r
-% @defun == @deffn Function\r
-\r
-\def\defun{\defparsebody\Edefun\defunx\defunheader}\r
-\r
-\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index\r
-\begingroup\defname {#1}{\putwordDeffunc}%\r
-\defunargs {#2}\endgroup %\r
-\catcode 61=\other % Turn off change made in \defparsebody\r
-}\r
-\r
-% @deftypefun int foobar (int @var{foo}, float @var{bar})\r
-\r
-\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader}\r
-\r
-% #1 is the data type. #2 is the name and args.\r
-\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax}\r
-% #1 is the data type, #2 the name, #3 the args.\r
-\def\deftypefunheaderx #1#2 #3\relax{%\r
-\doind {fn}{\code{#2}}% Make entry in function index\r
-\begingroup\defname {\defheaderxcond#1\relax$$$#2}{\putwordDeftypefun}%\r
-\deftypefunargs {#3}\endgroup %\r
-\catcode 61=\other % Turn off change made in \defparsebody\r
-}\r
-\r
-% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})\r
-\r
-\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader}\r
-\r
-% \defheaderxcond#1\relax$$$\r
-% puts #1 in @code, followed by a space, but does nothing if #1 is null.\r
-\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi}\r
-\r
-% #1 is the classification. #2 is the data type. #3 is the name and args.\r
-\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax}\r
-% #1 is the classification, #2 the data type, #3 the name, #4 the args.\r
-\def\deftypefnheaderx #1#2#3 #4\relax{%\r
-\doind {fn}{\code{#3}}% Make entry in function index\r
-\begingroup\r
-\normalparens % notably, turn off `&' magic, which prevents\r
-% at least some C++ text from working\r
-\defname {\defheaderxcond#2\relax$$$#3}{#1}%\r
-\deftypefunargs {#4}\endgroup %\r
-\catcode 61=\other % Turn off change made in \defparsebody\r
-}\r
-\r
-% @defmac == @deffn Macro\r
-\r
-\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader}\r
-\r
-\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index\r
-\begingroup\defname {#1}{\putwordDefmac}%\r
-\defunargs {#2}\endgroup %\r
-\catcode 61=\other % Turn off change made in \defparsebody\r
-}\r
-\r
-% @defspec == @deffn Special Form\r
-\r
-\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader}\r
-\r
-\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index\r
-\begingroup\defname {#1}{\putwordDefspec}%\r
-\defunargs {#2}\endgroup %\r
-\catcode 61=\other % Turn off change made in \defparsebody\r
-}\r
-\r
-% @defop CATEGORY CLASS OPERATION ARG...\r
-%\r
-\def\defop #1 {\def\defoptype{#1}%\r
-\defopparsebody\Edefop\defopx\defopheader\defoptype}\r
-%\r
-\def\defopheader#1#2#3{%\r
-\dosubind {fn}{\code{#2}}{\putwordon\ #1}% Make entry in function index\r
-\begingroup\defname {#2}{\defoptype\ \putwordon\ #1}%\r
-\defunargs {#3}\endgroup %\r
-}\r
-\r
-% @deftypeop CATEGORY CLASS TYPE OPERATION ARG...\r
-%\r
-\def\deftypeop #1 {\def\deftypeopcategory{#1}%\r
- \deftypeopparsebody\Edeftypeop\deftypeopx\deftypeopheader\r
- \deftypeopcategory}\r
-%\r
-% #1 is the class name, #2 the data type, #3 the operation name, #4 the args.\r
-\def\deftypeopheader#1#2#3#4{%\r
- \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index\r
- \begingroup\r
- \defname{\defheaderxcond#2\relax$$$#3}\r
- {\deftypeopcategory\ \putwordon\ \code{#1}}%\r
- \deftypefunargs{#4}%\r
- \endgroup\r
-}\r
-\r
-% @deftypemethod CLASS TYPE METHOD ARG...\r
-%\r
-\def\deftypemethod{%\r
- \deftypemethparsebody\Edeftypemethod\deftypemethodx\deftypemethodheader}\r
-%\r
-% #1 is the class name, #2 the data type, #3 the method name, #4 the args.\r
-\def\deftypemethodheader#1#2#3#4{%\r
- \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index\r
- \begingroup\r
- \defname{\defheaderxcond#2\relax$$$#3}{\putwordMethodon\ \code{#1}}%\r
- \deftypefunargs{#4}%\r
- \endgroup\r
-}\r
-\r
-% @deftypeivar CLASS TYPE VARNAME\r
-%\r
-\def\deftypeivar{%\r
- \deftypemethparsebody\Edeftypeivar\deftypeivarx\deftypeivarheader}\r
-%\r
-% #1 is the class name, #2 the data type, #3 the variable name.\r
-\def\deftypeivarheader#1#2#3{%\r
- \dosubind{vr}{\code{#3}}{\putwordof\ \code{#1}}% entry in variable index\r
- \begingroup\r
- \defname{\defheaderxcond#2\relax$$$#3}\r
- {\putwordInstanceVariableof\ \code{#1}}%\r
- \defvarargs{#3}%\r
- \endgroup\r
-}\r
-\r
-% @defmethod == @defop Method\r
-%\r
-\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader}\r
-%\r
-% #1 is the class name, #2 the method name, #3 the args.\r
-\def\defmethodheader#1#2#3{%\r
- \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% entry in function index\r
- \begingroup\r
- \defname{#2}{\putwordMethodon\ \code{#1}}%\r
- \defunargs{#3}%\r
- \endgroup\r
-}\r
-\r
-% @defcv {Class Option} foo-class foo-flag\r
-\r
-\def\defcv #1 {\def\defcvtype{#1}%\r
-\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype}\r
-\r
-\def\defcvarheader #1#2#3{%\r
-\dosubind {vr}{\code{#2}}{\putwordof\ #1}% Make entry in var index\r
-\begingroup\defname {#2}{\defcvtype\ \putwordof\ #1}%\r
-\defvarargs {#3}\endgroup %\r
-}\r
-\r
-% @defivar CLASS VARNAME == @defcv {Instance Variable} CLASS VARNAME\r
-%\r
-\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader}\r
-%\r
-\def\defivarheader#1#2#3{%\r
- \dosubind {vr}{\code{#2}}{\putwordof\ #1}% entry in var index\r
- \begingroup\r
- \defname{#2}{\putwordInstanceVariableof\ #1}%\r
- \defvarargs{#3}%\r
- \endgroup\r
-}\r
-\r
-% @defvar\r
-% First, define the processing that is wanted for arguments of @defvar.\r
-% This is actually simple: just print them in roman.\r
-% This must expand the args and terminate the paragraph they make up\r
-\def\defvarargs #1{\normalparens #1%\r
-\interlinepenalty=10000\r
-\endgraf\nobreak\vskip -\parskip\nobreak}\r
-\r
-% @defvr Counter foo-count\r
-\r
-\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader}\r
-\r
-\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}%\r
-\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup}\r
-\r
-% @defvar == @defvr Variable\r
-\r
-\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader}\r
-\r
-\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index\r
-\begingroup\defname {#1}{\putwordDefvar}%\r
-\defvarargs {#2}\endgroup %\r
-}\r
-\r
-% @defopt == @defvr {User Option}\r
-\r
-\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader}\r
-\r
-\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index\r
-\begingroup\defname {#1}{\putwordDefopt}%\r
-\defvarargs {#2}\endgroup %\r
-}\r
-\r
-% @deftypevar int foobar\r
-\r
-\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader}\r
-\r
-% #1 is the data type. #2 is the name, perhaps followed by text that\r
-% is actually part of the data type, which should not be put into the index.\r
-\def\deftypevarheader #1#2{%\r
-\dovarind#2 \relax% Make entry in variables index\r
-\begingroup\defname {\defheaderxcond#1\relax$$$#2}{\putwordDeftypevar}%\r
-\interlinepenalty=10000\r
-\endgraf\nobreak\vskip -\parskip\nobreak\r
-\endgroup}\r
-\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}}\r
-\r
-% @deftypevr {Global Flag} int enable\r
-\r
-\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader}\r
-\r
-\def\deftypevrheader #1#2#3{\dovarind#3 \relax%\r
-\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1}\r
-\interlinepenalty=10000\r
-\endgraf\nobreak\vskip -\parskip\nobreak\r
-\endgroup}\r
-\r
-% Now define @deftp\r
-% Args are printed in bold, a slight difference from @defvar.\r
-\r
-\def\deftpargs #1{\bf \defvarargs{#1}}\r
-\r
-% @deftp Class window height width ...\r
-\r
-\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader}\r
-\r
-\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}%\r
-\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup}\r
-\r
-% These definitions are used if you use @defunx (etc.)\r
-% anywhere other than immediately after a @defun or @defunx.\r
-% \r
-\def\defcvx#1 {\errmessage{@defcvx in invalid context}}\r
-\def\deffnx#1 {\errmessage{@deffnx in invalid context}}\r
-\def\defivarx#1 {\errmessage{@defivarx in invalid context}}\r
-\def\defmacx#1 {\errmessage{@defmacx in invalid context}}\r
-\def\defmethodx#1 {\errmessage{@defmethodx in invalid context}}\r
-\def\defoptx #1 {\errmessage{@defoptx in invalid context}}\r
-\def\defopx#1 {\errmessage{@defopx in invalid context}}\r
-\def\defspecx#1 {\errmessage{@defspecx in invalid context}}\r
-\def\deftpx#1 {\errmessage{@deftpx in invalid context}}\r
-\def\deftypefnx#1 {\errmessage{@deftypefnx in invalid context}}\r
-\def\deftypefunx#1 {\errmessage{@deftypefunx in invalid context}}\r
-\def\deftypeivarx#1 {\errmessage{@deftypeivarx in invalid context}}\r
-\def\deftypemethodx#1 {\errmessage{@deftypemethodx in invalid context}}\r
-\def\deftypeopx#1 {\errmessage{@deftypeopx in invalid context}}\r
-\def\deftypevarx#1 {\errmessage{@deftypevarx in invalid context}}\r
-\def\deftypevrx#1 {\errmessage{@deftypevrx in invalid context}}\r
-\def\defunx#1 {\errmessage{@defunx in invalid context}}\r
-\def\defvarx#1 {\errmessage{@defvarx in invalid context}}\r
-\def\defvrx#1 {\errmessage{@defvrx in invalid context}}\r
-\r
-\r
-\message{macros,}\r
-% @macro.\r
-\r
-% To do this right we need a feature of e-TeX, \scantokens,\r
-% which we arrange to emulate with a temporary file in ordinary TeX.\r
-\ifx\eTeXversion\undefined\r
- \newwrite\macscribble\r
- \def\scanmacro#1{%\r
- \begingroup \newlinechar`\^^M\r
- % Undo catcode changes of \startcontents and \doprintindex\r
- \catcode`\@=0 \catcode`\\=12 \escapechar=`\@\r
- % Append \endinput to make sure that TeX does not see the ending newline.\r
- \toks0={#1\endinput}%\r
- \immediate\openout\macscribble=\jobname.tmp\r
- \immediate\write\macscribble{\the\toks0}%\r
- \immediate\closeout\macscribble\r
- \let\xeatspaces\eatspaces\r
- \input \jobname.tmp\r
- \endgroup\r
-}\r
-\else\r
-\def\scanmacro#1{%\r
-\begingroup \newlinechar`\^^M\r
-% Undo catcode changes of \startcontents and \doprintindex\r
-\catcode`\@=0 \catcode`\\=12 \escapechar=`\@\r
-\let\xeatspaces\eatspaces\scantokens{#1\endinput}\endgroup}\r
-\fi\r
-\r
-\newcount\paramno % Count of parameters\r
-\newtoks\macname % Macro name\r
-\newif\ifrecursive % Is it recursive?\r
-\def\macrolist{} % List of all defined macros in the form\r
- % \do\macro1\do\macro2...\r
-\r
-% Utility routines.\r
-% Thisdoes \let #1 = #2, except with \csnames.\r
-\def\cslet#1#2{%\r
-\expandafter\expandafter\r
-\expandafter\let\r
-\expandafter\expandafter\r
-\csname#1\endcsname\r
-\csname#2\endcsname}\r
-\r
-% Trim leading and trailing spaces off a string.\r
-% Concepts from aro-bend problem 15 (see CTAN).\r
-{\catcode`\@=11\r
-\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}\r
-\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}\r
-\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}\r
-\def\unbrace#1{#1}\r
-\unbrace{\gdef\trim@@@ #1 } #2@{#1}\r
-}\r
-\r
-% Trim a single trailing ^^M off a string.\r
-{\catcode`\^^M=12\catcode`\Q=3%\r
-\gdef\eatcr #1{\eatcra #1Q^^MQ}%\r
-\gdef\eatcra#1^^MQ{\eatcrb#1Q}%\r
-\gdef\eatcrb#1Q#2Q{#1}%\r
-}\r
-\r
-% Macro bodies are absorbed as an argument in a context where\r
-% all characters are catcode 10, 11 or 12, except \ which is active\r
-% (as in normal texinfo). It is necessary to change the definition of \.\r
-\r
-% It's necessary to have hard CRs when the macro is executed. This is\r
-% done by making ^^M (\endlinechar) catcode 12 when reading the macro\r
-% body, and then making it the \newlinechar in \scanmacro.\r
-\r
-\def\macrobodyctxt{%\r
- \catcode`\~=12\r
- \catcode`\^=12\r
- \catcode`\_=12\r
- \catcode`\|=12\r
- \catcode`\<=12\r
- \catcode`\>=12\r
- \catcode`\+=12\r
- \catcode`\{=12\r
- \catcode`\}=12\r
- \catcode`\@=12\r
- \catcode`\^^M=12\r
- \usembodybackslash}\r
-\r
-\def\macroargctxt{%\r
- \catcode`\~=12\r
- \catcode`\^=12\r
- \catcode`\_=12\r
- \catcode`\|=12\r
- \catcode`\<=12\r
- \catcode`\>=12\r
- \catcode`\+=12\r
- \catcode`\@=12\r
- \catcode`\\=12}\r
-\r
-% \mbodybackslash is the definition of \ in @macro bodies.\r
-% It maps \foo\ => \csname macarg.foo\endcsname => #N\r
-% where N is the macro parameter number.\r
-% We define \csname macarg.\endcsname to be \realbackslash, so\r
-% \\ in macro replacement text gets you a backslash.\r
-\r
-{\catcode`@=0 @catcode`@\=@active\r
- @gdef@usembodybackslash{@let\=@mbodybackslash}\r
- @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}\r
-}\r
-\expandafter\def\csname macarg.\endcsname{\realbackslash}\r
-\r
-\def\macro{\recursivefalse\parsearg\macroxxx}\r
-\def\rmacro{\recursivetrue\parsearg\macroxxx}\r
-\r
-\def\macroxxx#1{%\r
- \getargs{#1}% now \macname is the macname and \argl the arglist\r
- \ifx\argl\empty % no arguments\r
- \paramno=0%\r
- \else\r
- \expandafter\parsemargdef \argl;%\r
- \fi\r
- \if1\csname ismacro.\the\macname\endcsname\r
- \message{Warning: redefining \the\macname}%\r
- \else\r
- \expandafter\ifx\csname \the\macname\endcsname \relax\r
- \else \errmessage{The name \the\macname\space is reserved}\fi\r
- \global\cslet{macsave.\the\macname}{\the\macname}%\r
- \global\expandafter\let\csname ismacro.\the\macname\endcsname=1%\r
- % Add the macroname to \macrolist\r
- \toks0 = \expandafter{\macrolist\do}%\r
- \xdef\macrolist{\the\toks0\r
- \expandafter\noexpand\csname\the\macname\endcsname}%\r
- \fi\r
- \begingroup \macrobodyctxt\r
- \ifrecursive \expandafter\parsermacbody\r
- \else \expandafter\parsemacbody\r
- \fi}\r
-\r
-\def\unmacro{\parsearg\unmacroxxx}\r
-\def\unmacroxxx#1{%\r
- \if1\csname ismacro.#1\endcsname\r
- \global\cslet{#1}{macsave.#1}%\r
- \global\expandafter\let \csname ismacro.#1\endcsname=0%\r
- % Remove the macro name from \macrolist\r
- \begingroup\r
- \edef\tempa{\expandafter\noexpand\csname#1\endcsname}%\r
- \def\do##1{%\r
- \def\tempb{##1}%\r
- \ifx\tempa\tempb\r
- % remove this\r
- \else\r
- \toks0 = \expandafter{\newmacrolist\do}%\r
- \edef\newmacrolist{\the\toks0\expandafter\noexpand\tempa}%\r
- \fi}%\r
- \def\newmacrolist{}%\r
- % Execute macro list to define \newmacrolist\r
- \macrolist\r
- \global\let\macrolist\newmacrolist\r
- \endgroup\r
- \else\r
- \errmessage{Macro #1 not defined}%\r
- \fi\r
-}\r
-\r
-% This makes use of the obscure feature that if the last token of a\r
-% <parameter list> is #, then the preceding argument is delimited by\r
-% an opening brace, and that opening brace is not consumed.\r
-\def\getargs#1{\getargsxxx#1{}}\r
-\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}\r
-\def\getmacname #1 #2\relax{\macname={#1}}\r
-\def\getmacargs#1{\def\argl{#1}}\r
-\r
-% Parse the optional {params} list. Set up \paramno and \paramlist\r
-% so \defmacro knows what to do. Define \macarg.blah for each blah\r
-% in the params list, to be ##N where N is the position in that list.\r
-% That gets used by \mbodybackslash (above).\r
-\r
-% We need to get `macro parameter char #' into several definitions.\r
-% The technique used is stolen from LaTeX: let \hash be something\r
-% unexpandable, insert that wherever you need a #, and then redefine\r
-% it to # just before using the token list produced.\r
-%\r
-% The same technique is used to protect \eatspaces till just before\r
-% the macro is used.\r
-\r
-\def\parsemargdef#1;{\paramno=0\def\paramlist{}%\r
- \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,}\r
-\def\parsemargdefxxx#1,{%\r
- \if#1;\let\next=\relax\r
- \else \let\next=\parsemargdefxxx\r
- \advance\paramno by 1%\r
- \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname\r
- {\xeatspaces{\hash\the\paramno}}%\r
- \edef\paramlist{\paramlist\hash\the\paramno,}%\r
- \fi\next}\r
-\r
-% These two commands read recursive and nonrecursive macro bodies.\r
-% (They're different since rec and nonrec macros end differently.)\r
-\r
-\long\def\parsemacbody#1@end macro%\r
-{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%\r
-\long\def\parsermacbody#1@end rmacro%\r
-{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%\r
-\r
-% This defines the macro itself. There are six cases: recursive and\r
-% nonrecursive macros of zero, one, and many arguments.\r
-% Much magic with \expandafter here.\r
-% \xdef is used so that macro definitions will survive the file\r
-% they're defined in; @include reads the file inside a group.\r
-\def\defmacro{%\r
- \let\hash=##% convert placeholders to macro parameter chars\r
- \ifrecursive\r
- \ifcase\paramno\r
- % 0\r
- \expandafter\xdef\csname\the\macname\endcsname{%\r
- \noexpand\scanmacro{\temp}}%\r
- \or % 1\r
- \expandafter\xdef\csname\the\macname\endcsname{%\r
- \bgroup\noexpand\macroargctxt\r
- \noexpand\braceorline\r
- \expandafter\noexpand\csname\the\macname xxx\endcsname}%\r
- \expandafter\xdef\csname\the\macname xxx\endcsname##1{%\r
- \egroup\noexpand\scanmacro{\temp}}%\r
- \else % many\r
- \expandafter\xdef\csname\the\macname\endcsname{%\r
- \bgroup\noexpand\macroargctxt\r
- \noexpand\csname\the\macname xx\endcsname}%\r
- \expandafter\xdef\csname\the\macname xx\endcsname##1{%\r
- \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%\r
- \expandafter\expandafter\r
- \expandafter\xdef\r
- \expandafter\expandafter\r
- \csname\the\macname xxx\endcsname\r
- \paramlist{\egroup\noexpand\scanmacro{\temp}}%\r
- \fi\r
- \else\r
- \ifcase\paramno\r
- % 0\r
- \expandafter\xdef\csname\the\macname\endcsname{%\r
- \noexpand\norecurse{\the\macname}%\r
- \noexpand\scanmacro{\temp}\egroup}%\r
- \or % 1\r
- \expandafter\xdef\csname\the\macname\endcsname{%\r
- \bgroup\noexpand\macroargctxt\r
- \noexpand\braceorline\r
- \expandafter\noexpand\csname\the\macname xxx\endcsname}%\r
- \expandafter\xdef\csname\the\macname xxx\endcsname##1{%\r
- \egroup\r
- \noexpand\norecurse{\the\macname}%\r
- \noexpand\scanmacro{\temp}\egroup}%\r
- \else % many\r
- \expandafter\xdef\csname\the\macname\endcsname{%\r
- \bgroup\noexpand\macroargctxt\r
- \expandafter\noexpand\csname\the\macname xx\endcsname}%\r
- \expandafter\xdef\csname\the\macname xx\endcsname##1{%\r
- \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%\r
- \expandafter\expandafter\r
- \expandafter\xdef\r
- \expandafter\expandafter\r
- \csname\the\macname xxx\endcsname\r
- \paramlist{%\r
- \egroup\r
- \noexpand\norecurse{\the\macname}%\r
- \noexpand\scanmacro{\temp}\egroup}%\r
- \fi\r
- \fi}\r
-\r
-\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}\r
-\r
-% \braceorline decides whether the next nonwhitespace character is a\r
-% {. If so it reads up to the closing }, if not, it reads the whole\r
-% line. Whatever was read is then fed to the next control sequence\r
-% as an argument (by \parsebrace or \parsearg)\r
-\def\braceorline#1{\let\next=#1\futurelet\nchar\braceorlinexxx}\r
-\def\braceorlinexxx{%\r
- \ifx\nchar\bgroup\else\r
- \expandafter\parsearg\r
- \fi \next}\r
-\r
-% We mant to disable all macros during \shipout so that they are not\r
-% expanded by \write.\r
-\def\turnoffmacros{\begingroup \def\do##1{\let\noexpand##1=\relax}%\r
- \edef\next{\macrolist}\expandafter\endgroup\next}\r
-\r
-\r
-% @alias.\r
-% We need some trickery to remove the optional spaces around the equal\r
-% sign. Just make them active and then expand them all to nothing.\r
-\def\alias{\begingroup\obeyspaces\parsearg\aliasxxx}\r
-\def\aliasxxx #1{\aliasyyy#1\relax}\r
-\def\aliasyyy #1=#2\relax{\ignoreactivespaces\r
-\edef\next{\global\let\expandafter\noexpand\csname#1\endcsname=%\r
- \expandafter\noexpand\csname#2\endcsname}%\r
-\expandafter\endgroup\next}\r
-\r
-\r
-\message{cross references,}\r
-% @xref etc.\r
-\r
-\newwrite\auxfile\r
-\r
-\newif\ifhavexrefs % True if xref values are known.\r
-\newif\ifwarnedxrefs % True if we warned once that they aren't known.\r
-\r
-% @inforef is relatively simple.\r
-\def\inforef #1{\inforefzzz #1,,,,**}\r
-\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},\r
- node \samp{\ignorespaces#1{}}}\r
-\r
-% @node's job is to define \lastnode.\r
-\def\node{\ENVcheck\parsearg\nodezzz}\r
-\def\nodezzz#1{\nodexxx [#1,]}\r
-\def\nodexxx[#1,#2]{\gdef\lastnode{#1}}\r
-\let\nwnode=\node\r
-\let\lastnode=\relax\r
-\r
-% The sectioning commands (@chapter, etc.) call these.\r
-\def\donoderef{%\r
- \ifx\lastnode\relax\else\r
- \expandafter\expandafter\expandafter\setref{\lastnode}%\r
- {Ysectionnumberandtype}%\r
- \global\let\lastnode=\relax\r
- \fi\r
-}\r
-\def\unnumbnoderef{%\r
- \ifx\lastnode\relax\else\r
- \expandafter\expandafter\expandafter\setref{\lastnode}{Ynothing}%\r
- \global\let\lastnode=\relax\r
- \fi\r
-}\r
-\def\appendixnoderef{%\r
- \ifx\lastnode\relax\else\r
- \expandafter\expandafter\expandafter\setref{\lastnode}%\r
- {Yappendixletterandtype}%\r
- \global\let\lastnode=\relax\r
- \fi\r
-}\r
-\r
-\r
-% @anchor{NAME} -- define xref target at arbitrary point.\r
-%\r
-\newcount\savesfregister\r
-\gdef\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}\r
-\gdef\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}\r
-\gdef\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}\r
-\r
-% \setref{NAME}{SNT} defines a cross-reference point NAME, namely\r
-% NAME-title, NAME-pg, and NAME-SNT. Called from \foonoderef. We have\r
-% to set \indexdummies so commands such as @code in a section title\r
-% aren't expanded. It would be nicer not to expand the titles in the\r
-% first place, but there's so many layers that that is hard to do.\r
-%\r
-\def\setref#1#2{{%\r
- \indexdummies\r
- \pdfmkdest{#1}%\r
- \dosetq{#1-title}{Ytitle}%\r
- \dosetq{#1-pg}{Ypagenumber}%\r
- \dosetq{#1-snt}{#2}%\r
-}}\r
-\r
-% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is\r
-% the node name, #2 the name of the Info cross-reference, #3 the printed\r
-% node name, #4 the name of the Info file, #5 the name of the printed\r
-% manual. All but the node name can be omitted.\r
-%\r
-\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]}\r
-\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}\r
-\def\ref#1{\xrefX[#1,,,,,,,]}\r
-\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup\r
- \unsepspaces\r
- \def\printedmanual{\ignorespaces #5}%\r
- \def\printednodename{\ignorespaces #3}%\r
- \setbox1=\hbox{\printedmanual}%\r
- \setbox0=\hbox{\printednodename}%\r
- \ifdim \wd0 = 0pt\r
- % No printed node name was explicitly given.\r
- \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax\r
- % Use the node name inside the square brackets.\r
- \def\printednodename{\ignorespaces #1}%\r
- \else\r
- % Use the actual chapter/section title appear inside\r
- % the square brackets. Use the real section title if we have it.\r
- \ifdim \wd1 > 0pt\r
- % It is in another manual, so we don't have it.\r
- \def\printednodename{\ignorespaces #1}%\r
- \else\r
- \ifhavexrefs\r
- % We know the real title if we have the xref values.\r
- \def\printednodename{\refx{#1-title}{}}%\r
- \else\r
- % Otherwise just copy the Info node name.\r
- \def\printednodename{\ignorespaces #1}%\r
- \fi%\r
- \fi\r
- \fi\r
- \fi\r
- %\r
- % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not\r
- % insert empty discretionaries after hyphens, which means that it will\r
- % not find a line break at a hyphen in a node names. Since some manuals\r
- % are best written with fairly long node names, containing hyphens, this\r
- % is a loss. Therefore, we give the text of the node name again, so it\r
- % is as if TeX is seeing it for the first time.\r
- \ifpdf\r
- \leavevmode\r
- \getfilename{#4}%\r
- \ifnum\filenamelength>0\r
- \startlink attr{/Border [0 0 0]}%\r
- goto file{\the\filename.pdf} name{#1@}%\r
- \else\r
- \startlink attr{/Border [0 0 0]}%\r
- goto name{#1@}%\r
- \fi\r
- \linkcolor\r
- \fi\r
- %\r
- \ifdim \wd1 > 0pt\r
- \putwordsection{} ``\printednodename'' \putwordin{} \cite{\printedmanual}%\r
- \else\r
- % _ (for example) has to be the character _ for the purposes of the\r
- % control sequence corresponding to the node, but it has to expand\r
- % into the usual \leavevmode...\vrule stuff for purposes of\r
- % printing. So we \turnoffactive for the \refx-snt, back on for the\r
- % printing, back off for the \refx-pg.\r
- {\normalturnoffactive\r
- % Only output a following space if the -snt ref is nonempty; for\r
- % @unnumbered and @anchor, it won't be.\r
- \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%\r
- \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi\r
- }%\r
- % [mynode],\r
- [\printednodename],\space\r
- % page 3\r
- \turnoffactive \putwordpage\tie\refx{#1-pg}{}%\r
- \fi\r
- \endlink\r
-\endgroup}\r
-\r
-% \dosetq is the interface for calls from other macros\r
-\r
-% Use \normalturnoffactive so that punctuation chars such as underscore\r
-% and backslash work in node names. (\turnoffactive doesn't do \.)\r
-\def\dosetq#1#2{%\r
- {\let\folio=0%\r
- \normalturnoffactive\r
- \edef\next{\write\auxfile{\internalsetq{#1}{#2}}}%\r
- \iflinks\r
- \next\r
- \fi\r
- }%\r
-}\r
-\r
-% \internalsetq {foo}{page} expands into\r
-% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...}\r
-% When the aux file is read, ' is the escape character\r
-\r
-\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}}\r
-\r
-% Things to be expanded by \internalsetq\r
-\r
-\def\Ypagenumber{\folio}\r
-\r
-\def\Ytitle{\thissection}\r
-\r
-\def\Ynothing{}\r
-\r
-\def\Ysectionnumberandtype{%\r
-\ifnum\secno=0 \putwordChapter\xreftie\the\chapno %\r
-\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno %\r
-\else \ifnum \subsubsecno=0 %\r
-\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno %\r
-\else %\r
-\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno %\r
-\fi \fi \fi }\r
-\r
-\def\Yappendixletterandtype{%\r
-\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}%\r
-\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno %\r
-\else \ifnum \subsubsecno=0 %\r
-\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno %\r
-\else %\r
-\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno %\r
-\fi \fi \fi }\r
-\r
-\gdef\xreftie{'tie}\r
-\r
-% Use TeX 3.0's \inputlineno to get the line number, for better error\r
-% messages, but if we're using an old version of TeX, don't do anything.\r
-%\r
-\ifx\inputlineno\thisisundefined\r
- \let\linenumber = \empty % Non-3.0.\r
-\else\r
- \def\linenumber{\the\inputlineno:\space}\r
-\fi\r
-\r
-% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.\r
-% If its value is nonempty, SUFFIX is output afterward.\r
-\r
-\def\refx#1#2{%\r
- \expandafter\ifx\csname X#1\endcsname\relax\r
- % If not defined, say something at least.\r
- \angleleft un\-de\-fined\angleright\r
- \iflinks\r
- \ifhavexrefs\r
- \message{\linenumber Undefined cross reference `#1'.}%\r
- \else\r
- \ifwarnedxrefs\else\r
- \global\warnedxrefstrue\r
- \message{Cross reference values unknown; you must run TeX again.}%\r
- \fi\r
- \fi\r
- \fi\r
- \else\r
- % It's defined, so just use it.\r
- \csname X#1\endcsname\r
- \fi\r
- #2% Output the suffix in any case.\r
-}\r
-\r
-% This is the macro invoked by entries in the aux file.\r
-%\r
-\def\xrdef#1{\begingroup\r
- % Reenable \ as an escape while reading the second argument.\r
- \catcode`\\ = 0\r
- \afterassignment\endgroup\r
- \expandafter\gdef\csname X#1\endcsname\r
-}\r
-\r
-% Read the last existing aux file, if any. No error if none exists.\r
-\def\readauxfile{\begingroup\r
- \catcode`\^^@=\other\r
- \catcode`\^^A=\other\r
- \catcode`\^^B=\other\r
- \catcode`\^^C=\other\r
- \catcode`\^^D=\other\r
- \catcode`\^^E=\other\r
- \catcode`\^^F=\other\r
- \catcode`\^^G=\other\r
- \catcode`\^^H=\other\r
- \catcode`\^^K=\other\r
- \catcode`\^^L=\other\r
- \catcode`\^^N=\other\r
- \catcode`\^^P=\other\r
- \catcode`\^^Q=\other\r
- \catcode`\^^R=\other\r
- \catcode`\^^S=\other\r
- \catcode`\^^T=\other\r
- \catcode`\^^U=\other\r
- \catcode`\^^V=\other\r
- \catcode`\^^W=\other\r
- \catcode`\^^X=\other\r
- \catcode`\^^Z=\other\r
- \catcode`\^^[=\other\r
- \catcode`\^^\=\other\r
- \catcode`\^^]=\other\r
- \catcode`\^^^=\other\r
- \catcode`\^^_=\other\r
- \catcode`\@=\other\r
- \catcode`\^=\other\r
- % It was suggested to define this as 7, which would allow ^^e4 etc.\r
- % in xref tags, i.e., node names. But since ^^e4 notation isn't\r
- % supported in the main text, it doesn't seem desirable. Furthermore,\r
- % that is not enough: for node names that actually contain a ^\r
- % character, we would end up writing a line like this: 'xrdef {'hat\r
- % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first\r
- % argument, and \hat is not an expandable control sequence. It could\r
- % all be worked out, but why? Either we support ^^ or we don't.\r
- %\r
- % The other change necessary for this was to define \auxhat:\r
- % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter\r
- % and then to call \auxhat in \setq.\r
- %\r
- \catcode`\~=\other\r
- \catcode`\[=\other\r
- \catcode`\]=\other\r
- \catcode`\"=\other\r
- \catcode`\_=\other\r
- \catcode`\|=\other\r
- \catcode`\<=\other\r
- \catcode`\>=\other\r
- \catcode`\$=\other\r
- \catcode`\#=\other\r
- \catcode`\&=\other\r
- \catcode`+=\other % avoid \+ for paranoia even though we've turned it off\r
- % Make the characters 128-255 be printing characters\r
- {%\r
- \count 1=128\r
- \def\loop{%\r
- \catcode\count 1=\other\r
- \advance\count 1 by 1\r
- \ifnum \count 1<256 \loop \fi\r
- }%\r
- }%\r
- % The aux file uses ' as the escape (for now).\r
- % Turn off \ as an escape so we do not lose on\r
- % entries which were dumped with control sequences in their names.\r
- % For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^\r
- % Reference to such entries still does not work the way one would wish,\r
- % but at least they do not bomb out when the aux file is read in.\r
- \catcode`\{=1\r
- \catcode`\}=2\r
- \catcode`\%=\other\r
- \catcode`\'=0\r
- \catcode`\\=\other\r
- %\r
- \openin 1 \jobname.aux\r
- \ifeof 1 \else\r
- \closein 1\r
- \input \jobname.aux\r
- \global\havexrefstrue\r
- \global\warnedobstrue\r
- \fi\r
- % Open the new aux file. TeX will close it automatically at exit.\r
- \openout\auxfile=\jobname.aux\r
-\endgroup}\r
-\r
-\r
-% Footnotes.\r
-\r
-\newcount \footnoteno\r
-\r
-% The trailing space in the following definition for supereject is\r
-% vital for proper filling; pages come out unaligned when you do a\r
-% pagealignmacro call if that space before the closing brace is\r
-% removed. (Generally, numeric constants should always be followed by a\r
-% space to prevent strange expansion errors.)\r
-\def\supereject{\par\penalty -20000\footnoteno =0 }\r
-\r
-% @footnotestyle is meaningful for info output only.\r
-\let\footnotestyle=\comment\r
-\r
-\let\ptexfootnote=\footnote\r
-\r
-{\catcode `\@=11\r
-%\r
-% Auto-number footnotes. Otherwise like plain.\r
-\gdef\footnote{%\r
- \global\advance\footnoteno by \@ne\r
- \edef\thisfootno{$^{\the\footnoteno}$}%\r
- %\r
- % In case the footnote comes at the end of a sentence, preserve the\r
- % extra spacing after we do the footnote number.\r
- \let\@sf\empty\r
- \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi\r
- %\r
- % Remove inadvertent blank space before typesetting the footnote number.\r
- \unskip\r
- \thisfootno\@sf\r
- \footnotezzz\r
-}%\r
-\r
-% Don't bother with the trickery in plain.tex to not require the\r
-% footnote text as a parameter. Our footnotes don't need to be so general.\r
-%\r
-% Oh yes, they do; otherwise, @ifset and anything else that uses\r
-% \parseargline fail inside footnotes because the tokens are fixed when\r
-% the footnote is read. --karl, 16nov96.\r
-%\r
-\long\gdef\footnotezzz{\insert\footins\bgroup\r
- % We want to typeset this text as a normal paragraph, even if the\r
- % footnote reference occurs in (for example) a display environment.\r
- % So reset some parameters.\r
- \interlinepenalty\interfootnotelinepenalty\r
- \splittopskip\ht\strutbox % top baseline for broken footnotes\r
- \splitmaxdepth\dp\strutbox\r
- \floatingpenalty\@MM\r
- \leftskip\z@skip\r
- \rightskip\z@skip\r
- \spaceskip\z@skip\r
- \xspaceskip\z@skip\r
- \parindent\defaultparindent\r
- %\r
- \smallfonts \rm\r
- %\r
- % Hang the footnote text off the number.\r
- \hang\r
- \textindent{\thisfootno}%\r
- %\r
- % Don't crash into the line above the footnote text. Since this\r
- % expands into a box, it must come within the paragraph, lest it\r
- % provide a place where TeX can split the footnote.\r
- \footstrut\r
- \futurelet\next\fo@t\r
-}\r
-\def\fo@t{\ifcat\bgroup\noexpand\next \let\next\f@@t\r
- \else\let\next\f@t\fi \next}\r
-\def\f@@t{\bgroup\aftergroup\@foot\let\next}\r
-\def\f@t#1{#1\@foot}\r
-\def\@foot{\strut\par\egroup}\r
-\r
-}%end \catcode `\@=11\r
-\r
-% Set the baselineskip to #1, and the lineskip and strut size\r
-% correspondingly. There is no deep meaning behind these magic numbers\r
-% used as factors; they just match (closely enough) what Knuth defined.\r
-%\r
-\def\lineskipfactor{.08333}\r
-\def\strutheightpercent{.70833}\r
-\def\strutdepthpercent {.29167}\r
-%\r
-\def\setleading#1{%\r
- \normalbaselineskip = #1\relax\r
- \normallineskip = \lineskipfactor\normalbaselineskip\r
- \normalbaselines\r
- \setbox\strutbox =\hbox{%\r
- \vrule width0pt height\strutheightpercent\baselineskip\r
- depth \strutdepthpercent \baselineskip\r
- }%\r
-}\r
-\r
-% @| inserts a changebar to the left of the current line. It should\r
-% surround any changed text. This approach does *not* work if the\r
-% change spans more than two lines of output. To handle that, we would\r
-% have adopt a much more difficult approach (putting marks into the main\r
-% vertical list for the beginning and end of each change).\r
-%\r
-\def\|{%\r
- % \vadjust can only be used in horizontal mode.\r
- \leavevmode\r
- %\r
- % Append this vertical mode material after the current line in the output.\r
- \vadjust{%\r
- % We want to insert a rule with the height and depth of the current\r
- % leading; that is exactly what \strutbox is supposed to record.\r
- \vskip-\baselineskip\r
- %\r
- % \vadjust-items are inserted at the left edge of the type. So\r
- % the \llap here moves out into the left-hand margin.\r
- \llap{%\r
- %\r
- % For a thicker or thinner bar, change the `1pt'.\r
- \vrule height\baselineskip width1pt\r
- %\r
- % This is the space between the bar and the text.\r
- \hskip 12pt\r
- }%\r
- }%\r
-}\r
-\r
-% For a final copy, take out the rectangles\r
-% that mark overfull boxes (in case you have decided\r
-% that the text looks ok even though it passes the margin).\r
-%\r
-\def\finalout{\overfullrule=0pt}\r
-\r
-% @image. We use the macros from epsf.tex to support this.\r
-% If epsf.tex is not installed and @image is used, we complain.\r
-%\r
-% Check for and read epsf.tex up front. If we read it only at @image\r
-% time, we might be inside a group, and then its definitions would get\r
-% undone and the next image would fail.\r
-\openin 1 = epsf.tex\r
-\ifeof 1 \else\r
- \closein 1\r
- % Do not bother showing banner with post-v2.7 epsf.tex (available in\r
- % doc/epsf.tex until it shows up on ctan).\r
- \def\epsfannounce{\toks0 = }%\r
- \input epsf.tex\r
-\fi\r
-%\r
-% We will only complain once about lack of epsf.tex.\r
-\newif\ifwarnednoepsf\r
-\newhelp\noepsfhelp{epsf.tex must be installed for images to\r
- work. It is also included in the Texinfo distribution, or you can get\r
- it from ftp://tug.org/tex/epsf.tex.}\r
-%\r
-\def\image#1{%\r
- \ifx\epsfbox\undefined\r
- \ifwarnednoepsf \else\r
- \errhelp = \noepsfhelp\r
- \errmessage{epsf.tex not found, images will be ignored}%\r
- \global\warnednoepsftrue\r
- \fi\r
- \else\r
- \imagexxx #1,,,\finish\r
- \fi\r
-}\r
-%\r
-% Arguments to @image:\r
-% #1 is (mandatory) image filename; we tack on .eps extension.\r
-% #2 is (optional) width, #3 is (optional) height.\r
-% #4 is just the usual extra ignored arg for parsing this stuff.\r
-\def\imagexxx#1,#2,#3,#4\finish{%\r
- \ifpdf\r
- \centerline{\dopdfimage{#1}{#2}{#3}}%\r
- \else\r
- % \epsfbox itself resets \epsf?size at each figure.\r
- \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi\r
- \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi\r
- \begingroup\r
- \catcode`\^^M = 5 % in case we're inside an example\r
- % If the image is by itself, center it.\r
- \ifvmode\r
- \nobreak\bigskip\r
- % Usually we'll have text after the image which will insert\r
- % \parskip glue, so insert it here too to equalize the space\r
- % above and below. \r
- \nobreak\vskip\parskip\r
- \nobreak\r
- \centerline{\epsfbox{#1.eps}}%\r
- \bigbreak\r
- \else\r
- % In the middle of a paragraph, no extra space.\r
- \epsfbox{#1.eps}%\r
- \fi\r
- \endgroup\r
- \fi\r
-}\r
-\r
-\r
-\message{localization,}\r
-% and i18n.\r
-\r
-% @documentlanguage is usually given very early, just after\r
-% @setfilename. If done too late, it may not override everything\r
-% properly. Single argument is the language abbreviation.\r
-% It would be nice if we could set up a hyphenation file here.\r
-%\r
-\def\documentlanguage{\parsearg\dodocumentlanguage}\r
-\def\dodocumentlanguage#1{%\r
- \tex % read txi-??.tex file in plain TeX.\r
- % Read the file if it exists.\r
- \openin 1 txi-#1.tex\r
- \ifeof1\r
- \errhelp = \nolanghelp\r
- \errmessage{Cannot read language file txi-#1.tex}%\r
- \let\temp = \relax\r
- \else\r
- \def\temp{\input txi-#1.tex }%\r
- \fi\r
- \temp\r
- \endgroup\r
-}\r
-\newhelp\nolanghelp{The given language definition file cannot be found or\r
-is empty. Maybe you need to install it? In the current directory\r
-should work if nowhere else does.}\r
-\r
-\r
-% @documentencoding should change something in TeX eventually, most\r
-% likely, but for now just recognize it.\r
-\let\documentencoding = \comment\r
-\r
-\r
-% Page size parameters.\r
-%\r
-\newdimen\defaultparindent \defaultparindent = 15pt\r
-\r
-\chapheadingskip = 15pt plus 4pt minus 2pt\r
-\secheadingskip = 12pt plus 3pt minus 2pt\r
-\subsecheadingskip = 9pt plus 2pt minus 2pt\r
-\r
-% Prevent underfull vbox error messages.\r
-\vbadness = 10000\r
-\r
-% Don't be so finicky about underfull hboxes, either.\r
-\hbadness = 2000\r
-\r
-% Following George Bush, just get rid of widows and orphans.\r
-\widowpenalty=10000\r
-\clubpenalty=10000\r
-\r
-% Use TeX 3.0's \emergencystretch to help line breaking, but if we're\r
-% using an old version of TeX, don't do anything. We want the amount of\r
-% stretch added to depend on the line length, hence the dependence on\r
-% \hsize. We call this whenever the paper size is set.\r
-%\r
-\def\setemergencystretch{%\r
- \ifx\emergencystretch\thisisundefined\r
- % Allow us to assign to \emergencystretch anyway.\r
- \def\emergencystretch{\dimen0}%\r
- \else\r
- \emergencystretch = .15\hsize\r
- \fi\r
-}\r
-\r
-% Parameters in order: 1) textheight; 2) textwidth; 3) voffset;\r
-% 4) hoffset; 5) binding offset; 6) topskip. Then whoever calls us can\r
-% set \parskip and call \setleading for \baselineskip.\r
-%\r
-\def\internalpagesizes#1#2#3#4#5#6{%\r
- \voffset = #3\relax\r
- \topskip = #6\relax\r
- \splittopskip = \topskip\r
- %\r
- \vsize = #1\relax\r
- \advance\vsize by \topskip\r
- \outervsize = \vsize\r
- \advance\outervsize by 2\topandbottommargin\r
- \pageheight = \vsize\r
- %\r
- \hsize = #2\relax\r
- \outerhsize = \hsize\r
- \advance\outerhsize by 0.5in\r
- \pagewidth = \hsize\r
- %\r
- \normaloffset = #4\relax\r
- \bindingoffset = #5\relax\r
- %\r
- \parindent = \defaultparindent\r
- \setemergencystretch\r
-}\r
-\r
-% @letterpaper (the default).\r
-\def\letterpaper{{\globaldefs = 1\r
- \parskip = 3pt plus 2pt minus 1pt\r
- \setleading{13.2pt}%\r
- %\r
- % If page is nothing but text, make it come out even.\r
- \internalpagesizes{46\baselineskip}{6in}{\voffset}{.25in}{\bindingoffset}{36pt}%\r
-}}\r
-\r
-% Use @smallbook to reset parameters for 7x9.5 (or so) format.\r
-\def\smallbook{{\globaldefs = 1\r
- \parskip = 2pt plus 1pt\r
- \setleading{12pt}%\r
- %\r
- \internalpagesizes{7.5in}{5.in}{\voffset}{.25in}{\bindingoffset}{16pt}%\r
- %\r
- \lispnarrowing = 0.3in\r
- \tolerance = 700\r
- \hfuzz = 1pt\r
- \contentsrightmargin = 0pt\r
- \deftypemargin = 0pt\r
- \defbodyindent = .5cm\r
- %\r
- \let\smalldisplay = \smalldisplayx\r
- \let\smallexample = \smalllispx\r
- \let\smallformat = \smallformatx\r
- \let\smalllisp = \smalllispx\r
-}}\r
-\r
-% Use @afourpaper to print on European A4 paper.\r
-\def\afourpaper{{\globaldefs = 1\r
- \setleading{12pt}%\r
- \parskip = 3pt plus 2pt minus 1pt\r
- %\r
- \internalpagesizes{53\baselineskip}{160mm}{\voffset}{4mm}{\bindingoffset}{44pt}%\r
- %\r
- \tolerance = 700\r
- \hfuzz = 1pt\r
-}}\r
-\r
-% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin\r
-% 29mm, hence bottom margin 28mm, nominal side margin 3cm.\r
-\def\afourlatex{{\globaldefs = 1\r
- \setleading{13.6pt}%\r
- %\r
- \afourpaper\r
- \internalpagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm}%\r
- %\r
- \globaldefs = 0\r
-}}\r
-\r
-% Use @afourwide to print on European A4 paper in wide format.\r
-\def\afourwide{%\r
- \afourpaper\r
- \internalpagesizes{6.5in}{9.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}%\r
- %\r
- \globaldefs = 0\r
-}\r
-\r
-% @pagesizes TEXTHEIGHT[,TEXTWIDTH]\r
-% Perhaps we should allow setting the margins, \topskip, \parskip,\r
-% and/or leading, also. Or perhaps we should compute them somehow.\r
-%\r
-\def\pagesizes{\parsearg\pagesizesxxx}\r
-\def\pagesizesxxx#1{\pagesizesyyy #1,,\finish}\r
-\def\pagesizesyyy#1,#2,#3\finish{{%\r
- \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi\r
- \globaldefs = 1\r
- %\r
- \parskip = 3pt plus 2pt minus 1pt\r
- \setleading{13.2pt}%\r
- %\r
- \internalpagesizes{#1}{\hsize}{\voffset}{\normaloffset}{\bindingoffset}{44pt}%\r
-}}\r
-\r
-% Set default to letter.\r
-%\r
-\letterpaper\r
-\r
-\r
-\message{and turning on texinfo input format.}\r
-\r
-% Define macros to output various characters with catcode for normal text.\r
-\catcode`\"=\other\r
-\catcode`\~=\other\r
-\catcode`\^=\other\r
-\catcode`\_=\other\r
-\catcode`\|=\other\r
-\catcode`\<=\other\r
-\catcode`\>=\other\r
-\catcode`\+=\other\r
-\catcode`\$=\other\r
-\def\normaldoublequote{"}\r
-\def\normaltilde{~}\r
-\def\normalcaret{^}\r
-\def\normalunderscore{_}\r
-\def\normalverticalbar{|}\r
-\def\normalless{<}\r
-\def\normalgreater{>}\r
-\def\normalplus{+}\r
-\def\normaldollar{$}\r
-\r
-% This macro is used to make a character print one way in ttfont\r
-% where it can probably just be output, and another way in other fonts,\r
-% where something hairier probably needs to be done.\r
-%\r
-% #1 is what to print if we are indeed using \tt; #2 is what to print\r
-% otherwise. Since all the Computer Modern typewriter fonts have zero\r
-% interword stretch (and shrink), and it is reasonable to expect all\r
-% typewriter fonts to have this, we can check that font parameter.\r
-%\r
-\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}\r
-\r
-% Same as above, but check for italic font. Actually this also catches\r
-% non-italic slanted fonts since it is impossible to distinguish them from\r
-% italic fonts. But since this is only used by $ and it uses \sl anyway\r
-% this is not a problem.\r
-\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}\r
-\r
-% Turn off all special characters except @\r
-% (and those which the user can use as if they were ordinary).\r
-% Most of these we simply print from the \tt font, but for some, we can\r
-% use math or other variants that look better in normal text.\r
-\r
-\catcode`\"=\active\r
-\def\activedoublequote{{\tt\char34}}\r
-\let"=\activedoublequote\r
-\catcode`\~=\active\r
-\def~{{\tt\char126}}\r
-\chardef\hat=`\^\r
-\catcode`\^=\active\r
-\def^{{\tt \hat}}\r
-\r
-\catcode`\_=\active\r
-\def_{\ifusingtt\normalunderscore\_}\r
-% Subroutine for the previous macro.\r
-\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}}\r
-\r
-\catcode`\|=\active\r
-\def|{{\tt\char124}}\r
-\chardef \less=`\<\r
-\catcode`\<=\active\r
-\def<{{\tt \less}}\r
-\chardef \gtr=`\>\r
-\catcode`\>=\active\r
-\def>{{\tt \gtr}}\r
-\catcode`\+=\active\r
-\def+{{\tt \char 43}}\r
-\catcode`\$=\active\r
-\def${\ifusingit{{\sl\$}}\normaldollar}\r
-%\catcode 27=\active\r
-%\def^^[{$\diamondsuit$}\r
-\r
-% Set up an active definition for =, but don't enable it most of the time.\r
-{\catcode`\==\active\r
-\global\def={{\tt \char 61}}}\r
-\r
-\catcode`+=\active\r
-\catcode`\_=\active\r
-\r
-% If a .fmt file is being used, characters that might appear in a file\r
-% name cannot be active until we have parsed the command line.\r
-% So turn them off again, and have \everyjob (or @setfilename) turn them on.\r
-% \otherifyactive is called near the end of this file.\r
-\def\otherifyactive{\catcode`+=\other \catcode`\_=\other}\r
-\r
-\catcode`\@=0\r
-\r
-% \rawbackslashxx output one backslash character in current font\r
-\global\chardef\rawbackslashxx=`\\\r
-%{\catcode`\\=\other\r
-%@gdef@rawbackslashxx{\}}\r
-\r
-% \rawbackslash redefines \ as input to do \rawbackslashxx.\r
-{\catcode`\\=\active\r
-@gdef@rawbackslash{@let\=@rawbackslashxx }}\r
-\r
-% \normalbackslash outputs one backslash in fixed width font.\r
-\def\normalbackslash{{\tt\rawbackslashxx}}\r
-\r
-% \catcode 17=0 % Define control-q\r
-\catcode`\\=\active\r
-\r
-% Used sometimes to turn off (effectively) the active characters\r
-% even after parsing them.\r
-@def@turnoffactive{@let"=@normaldoublequote\r
-@let\=@realbackslash\r
-@let~=@normaltilde\r
-@let^=@normalcaret\r
-@let_=@normalunderscore\r
-@let|=@normalverticalbar\r
-@let<=@normalless\r
-@let>=@normalgreater\r
-@let+=@normalplus\r
-@let$=@normaldollar}\r
-\r
-@def@normalturnoffactive{@let"=@normaldoublequote\r
-@let\=@normalbackslash\r
-@let~=@normaltilde\r
-@let^=@normalcaret\r
-@let_=@normalunderscore\r
-@let|=@normalverticalbar\r
-@let<=@normalless\r
-@let>=@normalgreater\r
-@let+=@normalplus\r
-@let$=@normaldollar}\r
-\r
-% Make _ and + \other characters, temporarily.\r
-% This is canceled by @fixbackslash.\r
-@otherifyactive\r
-\r
-% If a .fmt file is being used, we don't want the `\input texinfo' to show up.\r
-% That is what \eatinput is for; after that, the `\' should revert to printing\r
-% a backslash.\r
-%\r
-@gdef@eatinput input texinfo{@fixbackslash}\r
-@global@let\ = @eatinput\r
-\r
-% On the other hand, perhaps the file did not have a `\input texinfo'. Then\r
-% the first `\{ in the file would cause an error. This macro tries to fix\r
-% that, assuming it is called before the first `\' could plausibly occur.\r
-% Also back turn on active characters that might appear in the input\r
-% file name, in case not using a pre-dumped format.\r
-%\r
-@gdef@fixbackslash{%\r
- @ifx\@eatinput @let\ = @normalbackslash @fi\r
- @catcode`+=@active\r
- @catcode`@_=@active\r
-}\r
-\r
-% Say @foo, not \foo, in error messages.\r
-@escapechar = `@@\r
-\r
-% These look ok in all fonts, so just make them not special. \r
-@catcode`@& = @other\r
-@catcode`@# = @other\r
-@catcode`@% = @other\r
-\r
-@c Set initial fonts.\r
-@textfonts\r
-@rm\r
-\r
-\r
-@c Local variables:\r
-@c eval: (add-hook 'write-file-hooks 'time-stamp)\r
-@c page-delimiter: "^\\\\message"\r
-@c time-stamp-start: "def\\\\texinfoversion{"\r
-@c time-stamp-format: "%:y-%02m-%02d.%02H"\r
-@c time-stamp-end: "}"\r
-@c End:\r
+% texinfo.tex -- TeX macros to handle Texinfo files.
+%
+% Load plain if necessary, i.e., if running under initex.
+\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
+%
+\def\texinfoversion{2000-05-28.15}
+%
+% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99
+% Free Software Foundation, Inc.
+%
+% This texinfo.tex file 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.
+%
+% This texinfo.tex file 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 this texinfo.tex file; see the file COPYING. If not, write
+% to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+% Boston, MA 02111-1307, USA.
+%
+% In other words, you are welcome to use, share and improve this program.
+% You are forbidden to forbid anyone else to use, share and improve
+% what you give them. Help stamp out software-hoarding!
+%
+% Please try the latest version of texinfo.tex before submitting bug
+% reports; you can get the latest version from:
+% ftp://ftp.gnu.org/gnu/texinfo.tex
+% (and all GNU mirrors, see http://www.gnu.org/order/ftp.html)
+% ftp://texinfo.org/tex/texinfo.tex
+% ftp://us.ctan.org/macros/texinfo/texinfo.tex
+% (and all CTAN mirrors, finger ctan@us.ctan.org for a list).
+% /home/gd/gnu/doc/texinfo.tex on the GNU machines.
+% The texinfo.tex in any given Texinfo distribution could well be out
+% of date, so if that's what you're using, please check.
+% Texinfo has a small home page at http://texinfo.org/.
+%
+% Send bug reports to bug-texinfo@gnu.org. Please include including a
+% complete document in each bug report with which we can reproduce the
+% problem. Patches are, of course, greatly appreciated.
+%
+% To process a Texinfo manual with TeX, it's most reliable to use the
+% texi2dvi shell script that comes with the distribution. For a simple
+% manual foo.texi, however, you can get away with this:
+% tex foo.texi
+% texindex foo.??
+% tex foo.texi
+% tex foo.texi
+% dvips foo.dvi -o # or whatever, to process the dvi file; this makes foo.ps.
+% The extra runs of TeX get the cross-reference information correct.
+% Sometimes one run after texindex suffices, and sometimes you need more
+% than two; texi2dvi does it as many times as necessary.
+%
+% It is possible to adapt texinfo.tex for other languages. You can get
+% the existing language-specific files from ftp://ftp.gnu.org/gnu/texinfo/.
+
+\message{Loading texinfo [version \texinfoversion]:}
+
+% If in a .fmt file, print the version number
+% and turn on active characters that we couldn't do earlier because
+% they might have appeared in the input file name.
+\everyjob{\message{[Texinfo version \texinfoversion]}%
+ \catcode`+=\active \catcode`\_=\active}
+
+% Save some parts of plain tex whose names we will redefine.
+\let\ptexb=\b
+\let\ptexbullet=\bullet
+\let\ptexc=\c
+\let\ptexcomma=\,
+\let\ptexdot=\.
+\let\ptexdots=\dots
+\let\ptexend=\end
+\let\ptexequiv=\equiv
+\let\ptexexclam=\!
+\let\ptexi=\i
+\let\ptexlbrace=\{
+\let\ptexrbrace=\}
+\let\ptexstar=\*
+\let\ptext=\t
+
+% We never want plain's outer \+ definition in Texinfo.
+% For @tex, we can use \tabalign.
+\let\+ = \relax
+
+\message{Basics,}
+\chardef\other=12
+
+% If this character appears in an error message or help string, it
+% starts a new line in the output.
+\newlinechar = `^^J
+
+% Set up fixed words for English if not already set.
+\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi
+\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi
+\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi
+\ifx\putwordin\undefined \gdef\putwordin{in}\fi
+\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi
+\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi
+\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi
+\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi
+\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi
+\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi
+\ifx\putwordof\undefined \gdef\putwordof{of}\fi
+\ifx\putwordon\undefined \gdef\putwordon{on}\fi
+\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi
+\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi
+\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi
+\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi
+\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi
+\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi
+\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi
+%
+\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi
+\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi
+\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi
+\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi
+\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi
+\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi
+\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi
+\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi
+\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi
+\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi
+\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi
+\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi
+%
+\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi
+\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi
+\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi
+\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi
+\ifx\putwordDeftypevar\undefined\gdef\putwordDeftypevar{Variable}\fi
+\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi
+\ifx\putwordDeftypefun\undefined\gdef\putwordDeftypefun{Function}\fi
+
+% Ignore a token.
+%
+\def\gobble#1{}
+
+\hyphenation{ap-pen-dix}
+\hyphenation{mini-buf-fer mini-buf-fers}
+\hyphenation{eshell}
+\hyphenation{white-space}
+
+% Margin to add to right of even pages, to left of odd pages.
+\newdimen \bindingoffset
+\newdimen \normaloffset
+\newdimen\pagewidth \newdimen\pageheight
+
+% Sometimes it is convenient to have everything in the transcript file
+% and nothing on the terminal. We don't just call \tracingall here,
+% since that produces some useless output on the terminal.
+%
+\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%
+\ifx\eTeXversion\undefined
+\def\loggingall{\tracingcommands2 \tracingstats2
+ \tracingpages1 \tracingoutput1 \tracinglostchars1
+ \tracingmacros2 \tracingparagraphs1 \tracingrestores1
+ \showboxbreadth\maxdimen\showboxdepth\maxdimen
+}%
+\else
+\def\loggingall{\tracingcommands3 \tracingstats2
+ \tracingpages1 \tracingoutput1 \tracinglostchars1
+ \tracingmacros2 \tracingparagraphs1 \tracingrestores1
+ \tracingscantokens1 \tracingassigns1 \tracingifs1
+ \tracinggroups1 \tracingnesting2
+ \showboxbreadth\maxdimen\showboxdepth\maxdimen
+}%
+\fi
+
+% For @cropmarks command.
+% Do @cropmarks to get crop marks.
+%
+\newif\ifcropmarks
+\let\cropmarks = \cropmarkstrue
+%
+% Dimensions to add cropmarks at corners.
+% Added by P. A. MacKay, 12 Nov. 1986
+%
+\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines
+\newdimen\cornerlong \cornerlong=1pc
+\newdimen\cornerthick \cornerthick=.3pt
+\newdimen\topandbottommargin \topandbottommargin=.75in
+
+% Main output routine.
+\chardef\PAGE = 255
+\output = {\onepageout{\pagecontents\PAGE}}
+
+\newbox\headlinebox
+\newbox\footlinebox
+
+% \onepageout takes a vbox as an argument. Note that \pagecontents
+% does insertions, but you have to call it yourself.
+\def\onepageout#1{%
+ \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi
+ %
+ \ifodd\pageno \advance\hoffset by \bindingoffset
+ \else \advance\hoffset by -\bindingoffset\fi
+ %
+ % Do this outside of the \shipout so @code etc. will be expanded in
+ % the headline as they should be, not taken literally (outputting ''code).
+ \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}%
+ \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}%
+ %
+ {%
+ % Have to do this stuff outside the \shipout because we want it to
+ % take effect in \write's, yet the group defined by the \vbox ends
+ % before the \shipout runs.
+ %
+ \escapechar = `\\ % use backslash in output files.
+ \indexdummies % don't expand commands in the output.
+ \normalturnoffactive % \ in index entries must not stay \, e.g., if
+ % the page break happens to be in the middle of an example.
+ \shipout\vbox{%
+ % Do this early so pdf references go to the beginning of the page.
+ \ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi
+ %
+ \ifcropmarks \vbox to \outervsize\bgroup
+ \hsize = \outerhsize
+ \vskip-\topandbottommargin
+ \vtop to0pt{%
+ \line{\ewtop\hfil\ewtop}%
+ \nointerlineskip
+ \line{%
+ \vbox{\moveleft\cornerthick\nstop}%
+ \hfill
+ \vbox{\moveright\cornerthick\nstop}%
+ }%
+ \vss}%
+ \vskip\topandbottommargin
+ \line\bgroup
+ \hfil % center the page within the outer (page) hsize.
+ \ifodd\pageno\hskip\bindingoffset\fi
+ \vbox\bgroup
+ \fi
+ %
+ \unvbox\headlinebox
+ \pagebody{#1}%
+ \ifdim\ht\footlinebox > 0pt
+ % Only leave this space if the footline is nonempty.
+ % (We lessened \vsize for it in \oddfootingxxx.)
+ % The \baselineskip=24pt in plain's \makefootline has no effect.
+ \vskip 2\baselineskip
+ \unvbox\footlinebox
+ \fi
+ %
+ \ifcropmarks
+ \egroup % end of \vbox\bgroup
+ \hfil\egroup % end of (centering) \line\bgroup
+ \vskip\topandbottommargin plus1fill minus1fill
+ \boxmaxdepth = \cornerthick
+ \vbox to0pt{\vss
+ \line{%
+ \vbox{\moveleft\cornerthick\nsbot}%
+ \hfill
+ \vbox{\moveright\cornerthick\nsbot}%
+ }%
+ \nointerlineskip
+ \line{\ewbot\hfil\ewbot}%
+ }%
+ \egroup % \vbox from first cropmarks clause
+ \fi
+ }% end of \shipout\vbox
+ }% end of group with \turnoffactive
+ \advancepageno
+ \ifnum\outputpenalty>-20000 \else\dosupereject\fi
+}
+
+\newinsert\margin \dimen\margin=\maxdimen
+
+\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}
+{\catcode`\@ =11
+\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi
+% marginal hacks, juha@viisa.uucp (Juha Takala)
+\ifvoid\margin\else % marginal info is present
+ \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi
+\dimen@=\dp#1 \unvbox#1
+\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi
+\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
+}
+
+% Here are the rules for the cropmarks. Note that they are
+% offset so that the space between them is truly \outerhsize or \outervsize
+% (P. A. MacKay, 12 November, 1986)
+%
+\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}
+\def\nstop{\vbox
+ {\hrule height\cornerthick depth\cornerlong width\cornerthick}}
+\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}
+\def\nsbot{\vbox
+ {\hrule height\cornerlong depth\cornerthick width\cornerthick}}
+
+% Parse an argument, then pass it to #1. The argument is the rest of
+% the input line (except we remove a trailing comment). #1 should be a
+% macro which expects an ordinary undelimited TeX argument.
+%
+\def\parsearg#1{%
+ \let\next = #1%
+ \begingroup
+ \obeylines
+ \futurelet\temp\parseargx
+}
+
+% If the next token is an obeyed space (from an @example environment or
+% the like), remove it and recurse. Otherwise, we're done.
+\def\parseargx{%
+ % \obeyedspace is defined far below, after the definition of \sepspaces.
+ \ifx\obeyedspace\temp
+ \expandafter\parseargdiscardspace
+ \else
+ \expandafter\parseargline
+ \fi
+}
+
+% Remove a single space (as the delimiter token to the macro call).
+{\obeyspaces %
+ \gdef\parseargdiscardspace {\futurelet\temp\parseargx}}
+
+{\obeylines %
+ \gdef\parseargline#1^^M{%
+ \endgroup % End of the group started in \parsearg.
+ %
+ % First remove any @c comment, then any @comment.
+ % Result of each macro is put in \toks0.
+ \argremovec #1\c\relax %
+ \expandafter\argremovecomment \the\toks0 \comment\relax %
+ %
+ % Call the caller's macro, saved as \next in \parsearg.
+ \expandafter\next\expandafter{\the\toks0}%
+ }%
+}
+
+% Since all \c{,omment} does is throw away the argument, we can let TeX
+% do that for us. The \relax here is matched by the \relax in the call
+% in \parseargline; it could be more or less anything, its purpose is
+% just to delimit the argument to the \c.
+\def\argremovec#1\c#2\relax{\toks0 = {#1}}
+\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}}
+
+% \argremovec{,omment} might leave us with trailing spaces, though; e.g.,
+% @end itemize @c foo
+% will have two active spaces as part of the argument with the
+% `itemize'. Here we remove all active spaces from #1, and assign the
+% result to \toks0.
+%
+% This loses if there are any *other* active characters besides spaces
+% in the argument -- _ ^ +, for example -- since they get expanded.
+% Fortunately, Texinfo does not define any such commands. (If it ever
+% does, the catcode of the characters in questionwill have to be changed
+% here.) But this means we cannot call \removeactivespaces as part of
+% \argremovec{,omment}, since @c uses \parsearg, and thus the argument
+% that \parsearg gets might well have any character at all in it.
+%
+\def\removeactivespaces#1{%
+ \begingroup
+ \ignoreactivespaces
+ \edef\temp{#1}%
+ \global\toks0 = \expandafter{\temp}%
+ \endgroup
+}
+
+% Change the active space to expand to nothing.
+%
+\begingroup
+ \obeyspaces
+ \gdef\ignoreactivespaces{\obeyspaces\let =\empty}
+\endgroup
+
+
+\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}
+
+%% These are used to keep @begin/@end levels from running away
+%% Call \inENV within environments (after a \begingroup)
+\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi}
+\def\ENVcheck{%
+\ifENV\errmessage{Still within an environment; press RETURN to continue}
+\endgroup\fi} % This is not perfect, but it should reduce lossage
+
+% @begin foo is the same as @foo, for now.
+\newhelp\EMsimple{Press RETURN to continue.}
+
+\outer\def\begin{\parsearg\beginxxx}
+
+\def\beginxxx #1{%
+\expandafter\ifx\csname #1\endcsname\relax
+{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else
+\csname #1\endcsname\fi}
+
+% @end foo executes the definition of \Efoo.
+%
+\def\end{\parsearg\endxxx}
+\def\endxxx #1{%
+ \removeactivespaces{#1}%
+ \edef\endthing{\the\toks0}%
+ %
+ \expandafter\ifx\csname E\endthing\endcsname\relax
+ \expandafter\ifx\csname \endthing\endcsname\relax
+ % There's no \foo, i.e., no ``environment'' foo.
+ \errhelp = \EMsimple
+ \errmessage{Undefined command `@end \endthing'}%
+ \else
+ \unmatchedenderror\endthing
+ \fi
+ \else
+ % Everything's ok; the right environment has been started.
+ \csname E\endthing\endcsname
+ \fi
+}
+
+% There is an environment #1, but it hasn't been started. Give an error.
+%
+\def\unmatchedenderror#1{%
+ \errhelp = \EMsimple
+ \errmessage{This `@end #1' doesn't have a matching `@#1'}%
+}
+
+% Define the control sequence \E#1 to give an unmatched @end error.
+%
+\def\defineunmatchedend#1{%
+ \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}%
+}
+
+
+% Single-spacing is done by various environments (specifically, in
+% \nonfillstart and \quotations).
+\newskip\singlespaceskip \singlespaceskip = 12.5pt
+\def\singlespace{%
+ % Why was this kern here? It messes up equalizing space above and below
+ % environments. --karl, 6may93
+ %{\advance \baselineskip by -\singlespaceskip
+ %\kern \baselineskip}%
+ \setleading \singlespaceskip
+}
+
+%% Simple single-character @ commands
+
+% @@ prints an @
+% Kludge this until the fonts are right (grr).
+\def\@{{\tt\char64}}
+
+% This is turned off because it was never documented
+% and you can use @w{...} around a quote to suppress ligatures.
+%% Define @` and @' to be the same as ` and '
+%% but suppressing ligatures.
+%\def\`{{`}}
+%\def\'{{'}}
+
+% Used to generate quoted braces.
+\def\mylbrace {{\tt\char123}}
+\def\myrbrace {{\tt\char125}}
+\let\{=\mylbrace
+\let\}=\myrbrace
+\begingroup
+ % Definitions to produce actual \{ & \} command in an index.
+ \catcode`\{ = 12 \catcode`\} = 12
+ \catcode`\[ = 1 \catcode`\] = 2
+ \catcode`\@ = 0 \catcode`\\ = 12
+ @gdef@lbracecmd[\{]%
+ @gdef@rbracecmd[\}]%
+@endgroup
+
+% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent
+% Others are defined by plain TeX: @` @' @" @^ @~ @= @v @H.
+\let\, = \c
+\let\dotaccent = \.
+\def\ringaccent#1{{\accent23 #1}}
+\let\tieaccent = \t
+\let\ubaraccent = \b
+\let\udotaccent = \d
+
+% Other special characters: @questiondown @exclamdown
+% Plain TeX defines: @AA @AE @O @OE @L (and lowercase versions) @ss.
+\def\questiondown{?`}
+\def\exclamdown{!`}
+
+% Dotless i and dotless j, used for accents.
+\def\imacro{i}
+\def\jmacro{j}
+\def\dotless#1{%
+ \def\temp{#1}%
+ \ifx\temp\imacro \ptexi
+ \else\ifx\temp\jmacro \j
+ \else \errmessage{@dotless can be used only with i or j}%
+ \fi\fi
+}
+
+% Be sure we're in horizontal mode when doing a tie, since we make space
+% equivalent to this in @example-like environments. Otherwise, a space
+% at the beginning of a line will start with \penalty -- and
+% since \penalty is valid in vertical mode, we'd end up putting the
+% penalty on the vertical list instead of in the new paragraph.
+{\catcode`@ = 11
+ % Avoid using \@M directly, because that causes trouble
+ % if the definition is written into an index file.
+ \global\let\tiepenalty = \@M
+ \gdef\tie{\leavevmode\penalty\tiepenalty\ }
+}
+
+% @: forces normal size whitespace following.
+\def\:{\spacefactor=1000 }
+
+% @* forces a line break.
+\def\*{\hfil\break\hbox{}\ignorespaces}
+
+% @. is an end-of-sentence period.
+\def\.{.\spacefactor=3000 }
+
+% @! is an end-of-sentence bang.
+\def\!{!\spacefactor=3000 }
+
+% @? is an end-of-sentence query.
+\def\?{?\spacefactor=3000 }
+
+% @w prevents a word break. Without the \leavevmode, @w at the
+% beginning of a paragraph, when TeX is still in vertical mode, would
+% produce a whole line of output instead of starting the paragraph.
+\def\w#1{\leavevmode\hbox{#1}}
+
+% @group ... @end group forces ... to be all on one page, by enclosing
+% it in a TeX vbox. We use \vtop instead of \vbox to construct the box
+% to keep its height that of a normal line. According to the rules for
+% \topskip (p.114 of the TeXbook), the glue inserted is
+% max (\topskip - \ht (first item), 0). If that height is large,
+% therefore, no glue is inserted, and the space between the headline and
+% the text is small, which looks bad.
+%
+\def\group{\begingroup
+ \ifnum\catcode13=\active \else
+ \errhelp = \groupinvalidhelp
+ \errmessage{@group invalid in context where filling is enabled}%
+ \fi
+ %
+ % The \vtop we start below produces a box with normal height and large
+ % depth; thus, TeX puts \baselineskip glue before it, and (when the
+ % next line of text is done) \lineskip glue after it. (See p.82 of
+ % the TeXbook.) Thus, space below is not quite equal to space
+ % above. But it's pretty close.
+ \def\Egroup{%
+ \egroup % End the \vtop.
+ \endgroup % End the \group.
+ }%
+ %
+ \vtop\bgroup
+ % We have to put a strut on the last line in case the @group is in
+ % the midst of an example, rather than completely enclosing it.
+ % Otherwise, the interline space between the last line of the group
+ % and the first line afterwards is too small. But we can't put the
+ % strut in \Egroup, since there it would be on a line by itself.
+ % Hence this just inserts a strut at the beginning of each line.
+ \everypar = {\strut}%
+ %
+ % Since we have a strut on every line, we don't need any of TeX's
+ % normal interline spacing.
+ \offinterlineskip
+ %
+ % OK, but now we have to do something about blank
+ % lines in the input in @example-like environments, which normally
+ % just turn into \lisppar, which will insert no space now that we've
+ % turned off the interline space. Simplest is to make them be an
+ % empty paragraph.
+ \ifx\par\lisppar
+ \edef\par{\leavevmode \par}%
+ %
+ % Reset ^^M's definition to new definition of \par.
+ \obeylines
+ \fi
+ %
+ % Do @comment since we are called inside an environment such as
+ % @example, where each end-of-line in the input causes an
+ % end-of-line in the output. We don't want the end-of-line after
+ % the `@group' to put extra space in the output. Since @group
+ % should appear on a line by itself (according to the Texinfo
+ % manual), we don't worry about eating any user text.
+ \comment
+}
+%
+% TeX puts in an \escapechar (i.e., `@') at the beginning of the help
+% message, so this ends up printing `@group can only ...'.
+%
+\newhelp\groupinvalidhelp{%
+group can only be used in environments such as @example,^^J%
+where each line of input produces a line of output.}
+
+% @need space-in-mils
+% forces a page break if there is not space-in-mils remaining.
+
+\newdimen\mil \mil=0.001in
+
+\def\need{\parsearg\needx}
+
+% Old definition--didn't work.
+%\def\needx #1{\par %
+%% This method tries to make TeX break the page naturally
+%% if the depth of the box does not fit.
+%{\baselineskip=0pt%
+%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak
+%\prevdepth=-1000pt
+%}}
+
+\def\needx#1{%
+ % Ensure vertical mode, so we don't make a big box in the middle of a
+ % paragraph.
+ \par
+ %
+ % If the @need value is less than one line space, it's useless.
+ \dimen0 = #1\mil
+ \dimen2 = \ht\strutbox
+ \advance\dimen2 by \dp\strutbox
+ \ifdim\dimen0 > \dimen2
+ %
+ % Do a \strut just to make the height of this box be normal, so the
+ % normal leading is inserted relative to the preceding line.
+ % And a page break here is fine.
+ \vtop to #1\mil{\strut\vfil}%
+ %
+ % TeX does not even consider page breaks if a penalty added to the
+ % main vertical list is 10000 or more. But in order to see if the
+ % empty box we just added fits on the page, we must make it consider
+ % page breaks. On the other hand, we don't want to actually break the
+ % page after the empty box. So we use a penalty of 9999.
+ %
+ % There is an extremely small chance that TeX will actually break the
+ % page at this \penalty, if there are no other feasible breakpoints in
+ % sight. (If the user is using lots of big @group commands, which
+ % almost-but-not-quite fill up a page, TeX will have a hard time doing
+ % good page breaking, for example.) However, I could not construct an
+ % example where a page broke at this \penalty; if it happens in a real
+ % document, then we can reconsider our strategy.
+ \penalty9999
+ %
+ % Back up by the size of the box, whether we did a page break or not.
+ \kern -#1\mil
+ %
+ % Do not allow a page break right after this kern.
+ \nobreak
+ \fi
+}
+
+% @br forces paragraph break
+
+\let\br = \par
+
+% @dots{} output an ellipsis using the current font.
+% We do .5em per period so that it has the same spacing in a typewriter
+% font as three actual period characters.
+%
+\def\dots{%
+ \leavevmode
+ \hbox to 1.5em{%
+ \hskip 0pt plus 0.25fil minus 0.25fil
+ .\hss.\hss.%
+ \hskip 0pt plus 0.5fil minus 0.5fil
+ }%
+}
+
+% @enddots{} is an end-of-sentence ellipsis.
+%
+\def\enddots{%
+ \leavevmode
+ \hbox to 2em{%
+ \hskip 0pt plus 0.25fil minus 0.25fil
+ .\hss.\hss.\hss.%
+ \hskip 0pt plus 0.5fil minus 0.5fil
+ }%
+ \spacefactor=3000
+}
+
+
+% @page forces the start of a new page
+%
+\def\page{\par\vfill\supereject}
+
+% @exdent text....
+% outputs text on separate line in roman font, starting at standard page margin
+
+% This records the amount of indent in the innermost environment.
+% That's how much \exdent should take out.
+\newskip\exdentamount
+
+% This defn is used inside fill environments such as @defun.
+\def\exdent{\parsearg\exdentyyy}
+\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}}
+
+% This defn is used inside nofill environments such as @example.
+\def\nofillexdent{\parsearg\nofillexdentyyy}
+\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount
+\leftline{\hskip\leftskip{\rm#1}}}}
+
+% @inmargin{TEXT} puts TEXT in the margin next to the current paragraph.
+
+\def\inmargin#1{%
+\strut\vadjust{\nobreak\kern-\strutdepth
+ \vtop to \strutdepth{\baselineskip\strutdepth\vss
+ \llap{\rightskip=\inmarginspacing \vbox{\noindent #1}}\null}}}
+\newskip\inmarginspacing \inmarginspacing=1cm
+\def\strutdepth{\dp\strutbox}
+
+%\hbox{{\rm#1}}\hfil\break}}
+
+% @include file insert text of that file as input.
+% Allow normal characters that we make active in the argument (a file name).
+\def\include{\begingroup
+ \catcode`\\=12
+ \catcode`~=12
+ \catcode`^=12
+ \catcode`_=12
+ \catcode`|=12
+ \catcode`<=12
+ \catcode`>=12
+ \catcode`+=12
+ \parsearg\includezzz}
+% Restore active chars for included file.
+\def\includezzz#1{\endgroup\begingroup
+ % Read the included file in a group so nested @include's work.
+ \def\thisfile{#1}%
+ \input\thisfile
+\endgroup}
+
+\def\thisfile{}
+
+% @center line outputs that line, centered
+
+\def\center{\parsearg\centerzzz}
+\def\centerzzz #1{{\advance\hsize by -\leftskip
+\advance\hsize by -\rightskip
+\centerline{#1}}}
+
+% @sp n outputs n lines of vertical space
+
+\def\sp{\parsearg\spxxx}
+\def\spxxx #1{\vskip #1\baselineskip}
+
+% @comment ...line which is ignored...
+% @c is the same as @comment
+% @ignore ... @end ignore is another way to write a comment
+
+\def\comment{\begingroup \catcode`\^^M=\other%
+\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
+\commentxxx}
+{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}
+
+\let\c=\comment
+
+% @paragraphindent NCHARS
+% We'll use ems for NCHARS, close enough.
+% We cannot implement @paragraphindent asis, though.
+%
+\def\asisword{asis} % no translation, these are keywords
+\def\noneword{none}
+%
+\def\paragraphindent{\parsearg\doparagraphindent}
+\def\doparagraphindent#1{%
+ \def\temp{#1}%
+ \ifx\temp\asisword
+ \else
+ \ifx\temp\noneword
+ \defaultparindent = 0pt
+ \else
+ \defaultparindent = #1em
+ \fi
+ \fi
+ \parindent = \defaultparindent
+}
+
+% @exampleindent NCHARS
+% We'll use ems for NCHARS like @paragraphindent.
+% It seems @exampleindent asis isn't necessary, but
+% I preserve it to make it similar to @paragraphindent.
+\def\exampleindent{\parsearg\doexampleindent}
+\def\doexampleindent#1{%
+ \def\temp{#1}%
+ \ifx\temp\asisword
+ \else
+ \ifx\temp\noneword
+ \lispnarrowing = 0pt
+ \else
+ \lispnarrowing = #1em
+ \fi
+ \fi
+}
+
+% @asis just yields its argument. Used with @table, for example.
+%
+\def\asis#1{#1}
+
+% @math means output in math mode.
+% We don't use $'s directly in the definition of \math because control
+% sequences like \math are expanded when the toc file is written. Then,
+% we read the toc file back, the $'s will be normal characters (as they
+% should be, according to the definition of Texinfo). So we must use a
+% control sequence to switch into and out of math mode.
+%
+% This isn't quite enough for @math to work properly in indices, but it
+% seems unlikely it will ever be needed there.
+%
+\let\implicitmath = $
+\def\math#1{\implicitmath #1\implicitmath}
+
+% @bullet and @minus need the same treatment as @math, just above.
+\def\bullet{\implicitmath\ptexbullet\implicitmath}
+\def\minus{\implicitmath-\implicitmath}
+
+% @refill is a no-op.
+\let\refill=\relax
+
+% If working on a large document in chapters, it is convenient to
+% be able to disable indexing, cross-referencing, and contents, for test runs.
+% This is done with @novalidate (before @setfilename).
+%
+\newif\iflinks \linkstrue % by default we want the aux files.
+\let\novalidate = \linksfalse
+
+% @setfilename is done at the beginning of every texinfo file.
+% So open here the files we need to have open while reading the input.
+% This makes it possible to make a .fmt file for texinfo.
+\def\setfilename{%
+ \iflinks
+ \readauxfile
+ \fi % \openindices needs to do some work in any case.
+ \openindices
+ \fixbackslash % Turn off hack to swallow `\input texinfo'.
+ \global\let\setfilename=\comment % Ignore extra @setfilename cmds.
+ %
+ % If texinfo.cnf is present on the system, read it.
+ % Useful for site-wide @afourpaper, etc.
+ % Just to be on the safe side, close the input stream before the \input.
+ \openin 1 texinfo.cnf
+ \ifeof1 \let\temp=\relax \else \def\temp{\input texinfo.cnf }\fi
+ \closein1
+ \temp
+ %
+ \comment % Ignore the actual filename.
+}
+
+% Called from \setfilename.
+%
+\def\openindices{%
+ \newindex{cp}%
+ \newcodeindex{fn}%
+ \newcodeindex{vr}%
+ \newcodeindex{tp}%
+ \newcodeindex{ky}%
+ \newcodeindex{pg}%
+}
+
+% @bye.
+\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
+
+
+\message{pdf,}
+% adobe `portable' document format
+\newcount\tempnum
+\newcount\lnkcount
+\newtoks\filename
+\newcount\filenamelength
+\newcount\pgn
+\newtoks\toksA
+\newtoks\toksB
+\newtoks\toksC
+\newtoks\toksD
+\newbox\boxA
+\newcount\countA
+\newif\ifpdf
+\newif\ifpdfmakepagedest
+
+\ifx\pdfoutput\undefined
+ \pdffalse
+ \let\pdfmkdest = \gobble
+ \let\pdfurl = \gobble
+ \let\endlink = \relax
+ \let\linkcolor = \relax
+ \let\pdfmakeoutlines = \relax
+\else
+ \pdftrue
+ \pdfoutput = 1
+ \input pdfcolor
+ \def\dopdfimage#1#2#3{%
+ \def\imagewidth{#2}%
+ \def\imageheight{#3}%
+ \ifnum\pdftexversion < 14
+ \pdfimage
+ \else
+ \pdfximage
+ \fi
+ \ifx\empty\imagewidth\else width \imagewidth \fi
+ \ifx\empty\imageheight\else height \imageheight \fi
+ {#1.pdf}%
+ \ifnum\pdftexversion < 14 \else
+ \pdfrefximage \pdflastximage
+ \fi}
+ \def\pdfmkdest#1{\pdfdest name{#1@} xyz}
+ \def\pdfmkpgn#1{#1@}
+ \let\linkcolor = \Blue % was Cyan, but that seems light?
+ \def\endlink{\Black\pdfendlink}
+ % Adding outlines to PDF; macros for calculating structure of outlines
+ % come from Petr Olsak
+ \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%
+ \else \csname#1\endcsname \fi}
+ \def\advancenumber#1{\tempnum=\expnumber{#1}\relax
+ \advance\tempnum by1
+ \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
+ \def\pdfmakeoutlines{{%
+ \openin 1 \jobname.toc
+ \ifeof 1\else\bgroup
+ \closein 1
+ \indexnofonts
+ \def\tt{}
+ \let\_ = \normalunderscore
+ % Thanh's hack / proper braces in bookmarks
+ \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
+ \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
+ %
+ \def\chapentry ##1##2##3{}
+ \def\unnumbchapentry ##1##2{}
+ \def\secentry ##1##2##3##4{\advancenumber{chap##2}}
+ \def\unnumbsecentry ##1##2{}
+ \def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}}
+ \def\unnumbsubsecentry ##1##2{}
+ \def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}}
+ \def\unnumbsubsubsecentry ##1##2{}
+ \input \jobname.toc
+ \def\chapentry ##1##2##3{%
+ \pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}}
+ \def\unnumbchapentry ##1##2{%
+ \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \def\secentry ##1##2##3##4{%
+ \pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}}
+ \def\unnumbsecentry ##1##2{%
+ \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \def\subsecentry ##1##2##3##4##5{%
+ \pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}}
+ \def\unnumbsubsecentry ##1##2{%
+ \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \def\subsubsecentry ##1##2##3##4##5##6{%
+ \pdfoutline goto name{\pdfmkpgn{##6}}{##1}}
+ \def\unnumbsubsubsecentry ##1##2{%
+ \pdfoutline goto name{\pdfmkpgn{##2}}{##1}}
+ \input \jobname.toc
+ \egroup\fi
+ }}
+ \def\makelinks #1,{%
+ \def\params{#1}\def\E{END}%
+ \ifx\params\E
+ \let\nextmakelinks=\relax
+ \else
+ \let\nextmakelinks=\makelinks
+ \ifnum\lnkcount>0,\fi
+ \picknum{#1}%
+ \startlink attr{/Border [0 0 0]}
+ goto name{\pdfmkpgn{\the\pgn}}%
+ \linkcolor #1%
+ \advance\lnkcount by 1%
+ \endlink
+ \fi
+ \nextmakelinks
+ }
+ \def\picknum#1{\expandafter\pn#1}
+ \def\pn#1{%
+ \def\p{#1}%
+ \ifx\p\lbrace
+ \let\nextpn=\ppn
+ \else
+ \let\nextpn=\ppnn
+ \def\first{#1}
+ \fi
+ \nextpn
+ }
+ \def\ppn#1{\pgn=#1\gobble}
+ \def\ppnn{\pgn=\first}
+ \def\pdfmklnk#1{\lnkcount=0\makelinks #1,END,}
+ \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
+ \def\skipspaces#1{\def\PP{#1}\def\D{|}%
+ \ifx\PP\D\let\nextsp\relax
+ \else\let\nextsp\skipspaces
+ \ifx\p\space\else\addtokens{\filename}{\PP}%
+ \advance\filenamelength by 1
+ \fi
+ \fi
+ \nextsp}
+ \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax}
+ \ifnum\pdftexversion < 14
+ \let \startlink \pdfannotlink
+ \else
+ \let \startlink \pdfstartlink
+ \fi
+ \def\pdfurl#1{%
+ \begingroup
+ \normalturnoffactive\def\@{@}%
+ \leavevmode\Red
+ \startlink attr{/Border [0 0 0]}%
+ user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
+ % #1
+ \endgroup}
+ \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}
+ \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
+ \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}
+ \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}
+ \def\maketoks{%
+ \expandafter\poptoks\the\toksA|ENDTOKS|
+ \ifx\first0\adn0
+ \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
+ \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
+ \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
+ \else
+ \ifnum0=\countA\else\makelink\fi
+ \ifx\first.\let\next=\done\else
+ \let\next=\maketoks
+ \addtokens{\toksB}{\the\toksD}
+ \ifx\first,\addtokens{\toksB}{\space}\fi
+ \fi
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \next}
+ \def\makelink{\addtokens{\toksB}%
+ {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
+ \def\pdflink#1{%
+ \startlink attr{/Border [0 0 0]} goto name{\mkpgn{#1}}
+ \linkcolor #1\endlink}
+ \def\mkpgn#1{#1@}
+ \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
+\fi % \ifx\pdfoutput
+
+
+\message{fonts,}
+% Font-change commands.
+
+% Texinfo sort of supports the sans serif font style, which plain TeX does not.
+% So we set up a \sf analogous to plain's \rm, etc.
+\newfam\sffam
+\def\sf{\fam=\sffam \tensf}
+\let\li = \sf % Sometimes we call it \li, not \sf.
+
+% We don't need math for this one.
+\def\ttsl{\tenttsl}
+
+% Use Computer Modern fonts at \magstephalf (11pt).
+\newcount\mainmagstep
+\mainmagstep=\magstephalf
+
+% Set the font macro #1 to the font named #2, adding on the
+% specified font prefix (normally `cm').
+% #3 is the font's design size, #4 is a scale factor
+\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4}
+
+% Use cm as the default font prefix.
+% To specify the font prefix, you must define \fontprefix
+% before you read in texinfo.tex.
+\ifx\fontprefix\undefined
+\def\fontprefix{cm}
+\fi
+% Support font families that don't use the same naming scheme as CM.
+\def\rmshape{r}
+\def\rmbshape{bx} %where the normal face is bold
+\def\bfshape{b}
+\def\bxshape{bx}
+\def\ttshape{tt}
+\def\ttbshape{tt}
+\def\ttslshape{sltt}
+\def\itshape{ti}
+\def\itbshape{bxti}
+\def\slshape{sl}
+\def\slbshape{bxsl}
+\def\sfshape{ss}
+\def\sfbshape{ss}
+\def\scshape{csc}
+\def\scbshape{csc}
+
+\ifx\bigger\relax
+\let\mainmagstep=\magstep1
+\setfont\textrm\rmshape{12}{1000}
+\setfont\texttt\ttshape{12}{1000}
+\else
+\setfont\textrm\rmshape{10}{\mainmagstep}
+\setfont\texttt\ttshape{10}{\mainmagstep}
+\fi
+% Instead of cmb10, you many want to use cmbx10.
+% cmbx10 is a prettier font on its own, but cmb10
+% looks better when embedded in a line with cmr10.
+\setfont\textbf\bfshape{10}{\mainmagstep}
+\setfont\textit\itshape{10}{\mainmagstep}
+\setfont\textsl\slshape{10}{\mainmagstep}
+\setfont\textsf\sfshape{10}{\mainmagstep}
+\setfont\textsc\scshape{10}{\mainmagstep}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+
+% A few fonts for @defun, etc.
+\setfont\defbf\bxshape{10}{\magstep1} %was 1314
+\setfont\deftt\ttshape{10}{\magstep1}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\setfont\smallrm\rmshape{9}{1000}
+\setfont\smalltt\ttshape{9}{1000}
+\setfont\smallbf\bfshape{10}{900}
+\setfont\smallit\itshape{9}{1000}
+\setfont\smallsl\slshape{9}{1000}
+\setfont\smallsf\sfshape{9}{1000}
+\setfont\smallsc\scshape{10}{900}
+\setfont\smallttsl\ttslshape{10}{900}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+
+% Fonts for title page:
+\setfont\titlerm\rmbshape{12}{\magstep3}
+\setfont\titleit\itbshape{10}{\magstep4}
+\setfont\titlesl\slbshape{10}{\magstep4}
+\setfont\titlett\ttbshape{12}{\magstep3}
+\setfont\titlettsl\ttslshape{10}{\magstep4}
+\setfont\titlesf\sfbshape{17}{\magstep1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\authorrm{\secrm}
+
+% Chapter (and unnumbered) fonts (17.28pt).
+\setfont\chaprm\rmbshape{12}{\magstep2}
+\setfont\chapit\itbshape{10}{\magstep3}
+\setfont\chapsl\slbshape{10}{\magstep3}
+\setfont\chaptt\ttbshape{12}{\magstep2}
+\setfont\chapttsl\ttslshape{10}{\magstep3}
+\setfont\chapsf\sfbshape{17}{1000}
+\let\chapbf=\chaprm
+\setfont\chapsc\scbshape{10}{\magstep3}
+\font\chapi=cmmi12 scaled \magstep2
+\font\chapsy=cmsy10 scaled \magstep3
+
+% Section fonts (14.4pt).
+\setfont\secrm\rmbshape{12}{\magstep1}
+\setfont\secit\itbshape{10}{\magstep2}
+\setfont\secsl\slbshape{10}{\magstep2}
+\setfont\sectt\ttbshape{12}{\magstep1}
+\setfont\secttsl\ttslshape{10}{\magstep2}
+\setfont\secsf\sfbshape{12}{\magstep1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep2}
+\font\seci=cmmi12 scaled \magstep1
+\font\secsy=cmsy10 scaled \magstep2
+
+% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad.
+% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded.
+% \setfont\ssecsl\slshape{10}{\magstep1}
+% \setfont\ssectt\ttshape{10}{\magstep1}
+% \setfont\ssecsf\sfshape{10}{\magstep1}
+
+%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx.
+%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than
+%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1.
+%\setfont\ssectt\ttshape{10}{1315}
+%\setfont\ssecsf\sfshape{10}{1315}
+
+%\let\ssecbf=\ssecrm
+
+% Subsection fonts (13.15pt).
+\setfont\ssecrm\rmbshape{12}{\magstephalf}
+\setfont\ssecit\itbshape{10}{1315}
+\setfont\ssecsl\slbshape{10}{1315}
+\setfont\ssectt\ttbshape{12}{\magstephalf}
+\setfont\ssecttsl\ttslshape{10}{1315}
+\setfont\ssecsf\sfbshape{12}{\magstephalf}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{\magstep1}
+\font\sseci=cmmi12 scaled \magstephalf
+\font\ssecsy=cmsy10 scaled 1315
+% The smallcaps and symbol fonts should actually be scaled \magstep1.5,
+% but that is not a standard magnification.
+
+% In order for the font changes to affect most math symbols and letters,
+% we have to define the \textfont of the standard families. Since
+% texinfo doesn't allow for producing subscripts and superscripts, we
+% don't bother to reset \scriptfont and \scriptscriptfont (which would
+% also require loading a lot more fonts).
+%
+\def\resetmathfonts{%
+ \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy
+ \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf
+ \textfont\ttfam = \tentt \textfont\sffam = \tensf
+}
+
+
+% The font-changing commands redefine the meanings of \tenSTYLE, instead
+% of just \STYLE. We do this so that font changes will continue to work
+% in math mode, where it is the current \fam that is relevant in most
+% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam
+% \tenbf}, for example. By redefining \tenbf, we obviate the need to
+% redefine \bf itself.
+\def\textfonts{%
+ \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
+ \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
+ \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl
+ \resetmathfonts}
+\def\titlefonts{%
+ \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
+ \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
+ \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy
+ \let\tenttsl=\titlettsl
+ \resetmathfonts \setleading{25pt}}
+\def\titlefont#1{{\titlefonts\rm #1}}
+\def\chapfonts{%
+ \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
+ \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
+ \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl
+ \resetmathfonts \setleading{19pt}}
+\def\secfonts{%
+ \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl
+ \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc
+ \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl
+ \resetmathfonts \setleading{16pt}}
+\def\subsecfonts{%
+ \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl
+ \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc
+ \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl
+ \resetmathfonts \setleading{15pt}}
+\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf?
+\def\smallfonts{%
+ \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl
+ \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
+ \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
+ \let\tenttsl=\smallttsl
+ \resetmathfonts \setleading{11pt}}
+
+% Set up the default fonts, so we can use them for creating boxes.
+%
+\textfonts
+
+% Define these so they can be easily changed for other fonts.
+\def\angleleft{$\langle$}
+\def\angleright{$\rangle$}
+
+% Count depth in font-changes, for error checks
+\newcount\fontdepth \fontdepth=0
+
+% Fonts for short table of contents.
+\setfont\shortcontrm\rmshape{12}{1000}
+\setfont\shortcontbf\bxshape{12}{1000}
+\setfont\shortcontsl\slshape{12}{1000}
+
+%% Add scribe-like font environments, plus @l for inline lisp (usually sans
+%% serif) and @ii for TeX italic
+
+% \smartitalic{ARG} outputs arg in italics, followed by an italic correction
+% unless the following character is such as not to need one.
+\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi}
+\def\smartslanted#1{{\sl #1}\futurelet\next\smartitalicx}
+\def\smartitalic#1{{\it #1}\futurelet\next\smartitalicx}
+
+\let\i=\smartitalic
+\let\var=\smartslanted
+\let\dfn=\smartslanted
+\let\emph=\smartitalic
+\let\cite=\smartslanted
+
+\def\b#1{{\bf #1}}
+\let\strong=\b
+
+% We can't just use \exhyphenpenalty, because that only has effect at
+% the end of a paragraph. Restore normal hyphenation at the end of the
+% group within which \nohyphenation is presumably called.
+%
+\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation}
+\def\restorehyphenation{\hyphenchar\font = `- }
+
+\def\t#1{%
+ {\tt \rawbackslash \frenchspacing #1}%
+ \null
+}
+\let\ttfont=\t
+\def\samp#1{`\tclose{#1}'\null}
+\setfont\keyrm\rmshape{8}{1000}
+\font\keysy=cmsy9
+\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
+ \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
+ \vbox{\hrule\kern-0.4pt
+ \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
+ \kern-0.4pt\hrule}%
+ \kern-.06em\raise0.4pt\hbox{\angleright}}}}
+% The old definition, with no lozenge:
+%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null}
+\def\ctrl #1{{\tt \rawbackslash \hat}#1}
+
+% @file, @option are the same as @samp.
+\let\file=\samp
+\let\option=\samp
+
+% @code is a modification of @t,
+% which makes spaces the same size as normal in the surrounding text.
+\def\tclose#1{%
+ {%
+ % Change normal interword space to be same as for the current font.
+ \spaceskip = \fontdimen2\font
+ %
+ % Switch to typewriter.
+ \tt
+ %
+ % But `\ ' produces the large typewriter interword space.
+ \def\ {{\spaceskip = 0pt{} }}%
+ %
+ % Turn off hyphenation.
+ \nohyphenation
+ %
+ \rawbackslash
+ \frenchspacing
+ #1%
+ }%
+ \null
+}
+
+% We *must* turn on hyphenation at `-' and `_' in \code.
+% Otherwise, it is too hard to avoid overfull hboxes
+% in the Emacs manual, the Library manual, etc.
+
+% Unfortunately, TeX uses one parameter (\hyphenchar) to control
+% both hyphenation at - and hyphenation within words.
+% We must therefore turn them both off (\tclose does that)
+% and arrange explicitly to hyphenate at a dash.
+% -- rms.
+{
+ \catcode`\-=\active
+ \catcode`\_=\active
+ %
+ \global\def\code{\begingroup
+ \catcode`\-=\active \let-\codedash
+ \catcode`\_=\active \let_\codeunder
+ \codex
+ }
+ %
+ % If we end up with any active - characters when handling the index,
+ % just treat them as a normal -.
+ \global\def\indexbreaks{\catcode`\-=\active \let-\realdash}
+}
+
+\def\realdash{-}
+\def\codedash{-\discretionary{}{}{}}
+\def\codeunder{\ifusingtt{\normalunderscore\discretionary{}{}{}}{\_}}
+\def\codex #1{\tclose{#1}\endgroup}
+
+%\let\exp=\tclose %Was temporary
+
+% @kbd is like @code, except that if the argument is just one @key command,
+% then @kbd has no effect.
+
+% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
+% `example' (@kbd uses ttsl only inside of @example and friends),
+% or `code' (@kbd uses normal tty font always).
+\def\kbdinputstyle{\parsearg\kbdinputstylexxx}
+\def\kbdinputstylexxx#1{%
+ \def\arg{#1}%
+ \ifx\arg\worddistinct
+ \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%
+ \else\ifx\arg\wordexample
+ \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%
+ \else\ifx\arg\wordcode
+ \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%
+ \fi\fi\fi
+}
+\def\worddistinct{distinct}
+\def\wordexample{example}
+\def\wordcode{code}
+
+% Default is kbdinputdistinct. (Too much of a hassle to call the macro,
+% the catcodes are wrong for parsearg to work.)
+\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}
+
+\def\xkey{\key}
+\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%
+\ifx\one\xkey\ifx\threex\three \key{#2}%
+\else{\tclose{\kbdfont\look}}\fi
+\else{\tclose{\kbdfont\look}}\fi}
+
+% For @url, @env, @command quotes seem unnecessary, so use \code.
+\let\url=\code
+\let\env=\code
+\let\command=\code
+
+% @uref (abbreviation for `urlref') takes an optional (comma-separated)
+% second argument specifying the text to display and an optional third
+% arg as text to display instead of (rather than in addition to) the url
+% itself. First (mandatory) arg is the url. Perhaps eventually put in
+% a hypertex \special here.
+%
+\def\uref#1{\douref #1,,,\finish}
+\def\douref#1,#2,#3,#4\finish{\begingroup
+ \unsepspaces
+ \pdfurl{#1}%
+ \setbox0 = \hbox{\ignorespaces #3}%
+ \ifdim\wd0 > 0pt
+ \unhbox0 % third arg given, show only that
+ \else
+ \setbox0 = \hbox{\ignorespaces #2}%
+ \ifdim\wd0 > 0pt
+ \ifpdf
+ \unhbox0 % PDF: 2nd arg given, show only it
+ \else
+ \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url
+ \fi
+ \else
+ \code{#1}% only url given, so show it
+ \fi
+ \fi
+ \endlink
+\endgroup}
+
+% rms does not like angle brackets --karl, 17may97.
+% So now @email is just like @uref, unless we are pdf.
+%
+%\def\email#1{\angleleft{\tt #1}\angleright}
+\ifpdf
+ \def\email#1{\doemail#1,,\finish}
+ \def\doemail#1,#2,#3\finish{\begingroup
+ \unsepspaces
+ \pdfurl{mailto:#1}%
+ \setbox0 = \hbox{\ignorespaces #2}%
+ \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi
+ \endlink
+ \endgroup}
+\else
+ \let\email=\uref
+\fi
+
+% Check if we are currently using a typewriter font. Since all the
+% Computer Modern typewriter fonts have zero interword stretch (and
+% shrink), and it is reasonable to expect all typewriter fonts to have
+% this property, we can check that font parameter.
+%
+\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
+
+% Typeset a dimension, e.g., `in' or `pt'. The only reason for the
+% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.
+%
+\def\dmn#1{\thinspace #1}
+
+\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par}
+
+% @l was never documented to mean ``switch to the Lisp font'',
+% and it is not used as such in any manual I can find. We need it for
+% Polish suppressed-l. --karl, 22sep96.
+%\def\l#1{{\li #1}\null}
+
+% Explicit font changes: @r, @sc, undocumented @ii.
+\def\r#1{{\rm #1}} % roman font
+\def\sc#1{{\smallcaps#1}} % smallcaps font
+\def\ii#1{{\it #1}} % italic font
+
+% @acronym downcases the argument and prints in smallcaps.
+\def\acronym#1{{\smallcaps \lowercase{#1}}}
+
+% @pounds{} is a sterling sign.
+\def\pounds{{\it\$}}
+
+
+\message{page headings,}
+
+\newskip\titlepagetopglue \titlepagetopglue = 1.5in
+\newskip\titlepagebottomglue \titlepagebottomglue = 2pc
+
+% First the title page. Must do @settitle before @titlepage.
+\newif\ifseenauthor
+\newif\iffinishedtitlepage
+
+% Do an implicit @contents or @shortcontents after @end titlepage if the
+% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.
+%
+\newif\ifsetcontentsaftertitlepage
+ \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue
+\newif\ifsetshortcontentsaftertitlepage
+ \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue
+
+\def\shorttitlepage{\parsearg\shorttitlepagezzz}
+\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}%
+ \endgroup\page\hbox{}\page}
+
+\def\titlepage{\begingroup \parindent=0pt \textfonts
+ \let\subtitlerm=\tenrm
+ \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}%
+ %
+ \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}%
+ %
+ % Leave some space at the very top of the page.
+ \vglue\titlepagetopglue
+ %
+ % Now you can print the title using @title.
+ \def\title{\parsearg\titlezzz}%
+ \def\titlezzz##1{\leftline{\titlefonts\rm ##1}
+ % print a rule at the page bottom also.
+ \finishedtitlepagefalse
+ \vskip4pt \hrule height 4pt width \hsize \vskip4pt}%
+ % No rule at page bottom unless we print one at the top with @title.
+ \finishedtitlepagetrue
+ %
+ % Now you can put text using @subtitle.
+ \def\subtitle{\parsearg\subtitlezzz}%
+ \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}%
+ %
+ % @author should come last, but may come many times.
+ \def\author{\parsearg\authorzzz}%
+ \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi
+ {\authorfont \leftline{##1}}}%
+ %
+ % Most title ``pages'' are actually two pages long, with space
+ % at the top of the second. We don't want the ragged left on the second.
+ \let\oldpage = \page
+ \def\page{%
+ \iffinishedtitlepage\else
+ \finishtitlepage
+ \fi
+ \oldpage
+ \let\page = \oldpage
+ \hbox{}}%
+% \def\page{\oldpage \hbox{}}
+}
+
+\def\Etitlepage{%
+ \iffinishedtitlepage\else
+ \finishtitlepage
+ \fi
+ % It is important to do the page break before ending the group,
+ % because the headline and footline are only empty inside the group.
+ % If we use the new definition of \page, we always get a blank page
+ % after the title page, which we certainly don't want.
+ \oldpage
+ \endgroup
+ %
+ % If they want short, they certainly want long too.
+ \ifsetshortcontentsaftertitlepage
+ \shortcontents
+ \contents
+ \global\let\shortcontents = \relax
+ \global\let\contents = \relax
+ \fi
+ %
+ \ifsetcontentsaftertitlepage
+ \contents
+ \global\let\contents = \relax
+ \global\let\shortcontents = \relax
+ \fi
+ %
+ \ifpdf \pdfmakepagedesttrue \fi
+ %
+ \HEADINGSon
+}
+
+\def\finishtitlepage{%
+ \vskip4pt \hrule height 2pt width \hsize
+ \vskip\titlepagebottomglue
+ \finishedtitlepagetrue
+}
+
+%%% Set up page headings and footings.
+
+\let\thispage=\folio
+
+\newtoks\evenheadline % headline on even pages
+\newtoks\oddheadline % headline on odd pages
+\newtoks\evenfootline % footline on even pages
+\newtoks\oddfootline % footline on odd pages
+
+% Now make Tex use those variables
+\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
+ \else \the\evenheadline \fi}}
+\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
+ \else \the\evenfootline \fi}\HEADINGShook}
+\let\HEADINGShook=\relax
+
+% Commands to set those variables.
+% For example, this is what @headings on does
+% @evenheading @thistitle|@thispage|@thischapter
+% @oddheading @thischapter|@thispage|@thistitle
+% @evenfooting @thisfile||
+% @oddfooting ||@thisfile
+
+\def\evenheading{\parsearg\evenheadingxxx}
+\def\oddheading{\parsearg\oddheadingxxx}
+\def\everyheading{\parsearg\everyheadingxxx}
+
+\def\evenfooting{\parsearg\evenfootingxxx}
+\def\oddfooting{\parsearg\oddfootingxxx}
+\def\everyfooting{\parsearg\everyfootingxxx}
+
+{\catcode`\@=0 %
+
+\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish}
+\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{%
+\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish}
+\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{%
+\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\gdef\everyheadingxxx#1{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
+
+\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish}
+\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{%
+\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish}
+\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{%
+ \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%
+ %
+ % Leave some space for the footline. Hopefully ok to assume
+ % @evenfooting will not be used by itself.
+ \global\advance\pageheight by -\baselineskip
+ \global\advance\vsize by -\baselineskip
+}
+
+\gdef\everyfootingxxx#1{\oddfootingxxx{#1}\evenfootingxxx{#1}}
+%
+}% unbind the catcode of @.
+
+% @headings double turns headings on for double-sided printing.
+% @headings single turns headings on for single-sided printing.
+% @headings off turns them off.
+% @headings on same as @headings double, retained for compatibility.
+% @headings after turns on double-sided headings after this page.
+% @headings doubleafter turns on double-sided headings after this page.
+% @headings singleafter turns on single-sided headings after this page.
+% By default, they are off at the start of a document,
+% and turned `on' after @end titlepage.
+
+\def\headings #1 {\csname HEADINGS#1\endcsname}
+
+\def\HEADINGSoff{
+\global\evenheadline={\hfil} \global\evenfootline={\hfil}
+\global\oddheadline={\hfil} \global\oddfootline={\hfil}}
+\HEADINGSoff
+% When we turn headings on, set the page number to 1.
+% For double-sided printing, put current file name in lower left corner,
+% chapter name on inside top of right hand pages, document
+% title on inside top of left hand pages, and page numbers on outside top
+% edge of all pages.
+\def\HEADINGSdouble{
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+\let\contentsalignmacro = \chappager
+
+% For single-sided printing, chapter title goes across top left of page,
+% page number on top right.
+\def\HEADINGSsingle{
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+\def\HEADINGSon{\HEADINGSdouble}
+
+\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
+\let\HEADINGSdoubleafter=\HEADINGSafter
+\def\HEADINGSdoublex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+
+\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
+\def\HEADINGSsinglex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+
+% Subroutines used in generating headings
+% This produces Day Month Year style of output.
+% Only define if not already defined, in case a txi-??.tex file has set
+% up a different format (e.g., txi-cs.tex does this).
+\ifx\today\undefined
+\def\today{%
+ \number\day\space
+ \ifcase\month
+ \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr
+ \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug
+ \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec
+ \fi
+ \space\number\year}
+\fi
+
+% @settitle line... specifies the title of the document, for headings.
+% It generates no output of its own.
+\def\thistitle{\putwordNoTitle}
+\def\settitle{\parsearg\settitlezzz}
+\def\settitlezzz #1{\gdef\thistitle{#1}}
+
+
+\message{tables,}
+% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x).
+
+% default indentation of table text
+\newdimen\tableindent \tableindent=.8in
+% default indentation of @itemize and @enumerate text
+\newdimen\itemindent \itemindent=.3in
+% margin between end of table item and start of table text.
+\newdimen\itemmargin \itemmargin=.1in
+
+% used internally for \itemindent minus \itemmargin
+\newdimen\itemmax
+
+% Note @table, @vtable, and @vtable define @item, @itemx, etc., with
+% these defs.
+% They also define \itemindex
+% to index the item name in whatever manner is desired (perhaps none).
+
+\newif\ifitemxneedsnegativevskip
+
+\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}
+
+\def\internalBitem{\smallbreak \parsearg\itemzzz}
+\def\internalBitemx{\itemxpar \parsearg\itemzzz}
+
+\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz}
+\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz}
+
+\def\internalBkitem{\smallbreak \parsearg\kitemzzz}
+\def\internalBkitemx{\itemxpar \parsearg\kitemzzz}
+
+\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}%
+ \itemzzz {#1}}
+
+\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}%
+ \itemzzz {#1}}
+
+\def\itemzzz #1{\begingroup %
+ \advance\hsize by -\rightskip
+ \advance\hsize by -\tableindent
+ \setbox0=\hbox{\itemfont{#1}}%
+ \itemindex{#1}%
+ \nobreak % This prevents a break before @itemx.
+ %
+ % If the item text does not fit in the space we have, put it on a line
+ % by itself, and do not allow a page break either before or after that
+ % line. We do not start a paragraph here because then if the next
+ % command is, e.g., @kindex, the whatsit would get put into the
+ % horizontal list on a line by itself, resulting in extra blank space.
+ \ifdim \wd0>\itemmax
+ %
+ % Make this a paragraph so we get the \parskip glue and wrapping,
+ % but leave it ragged-right.
+ \begingroup
+ \advance\leftskip by-\tableindent
+ \advance\hsize by\tableindent
+ \advance\rightskip by0pt plus1fil
+ \leavevmode\unhbox0\par
+ \endgroup
+ %
+ % We're going to be starting a paragraph, but we don't want the
+ % \parskip glue -- logically it's part of the @item we just started.
+ \nobreak \vskip-\parskip
+ %
+ % Stop a page break at the \parskip glue coming up. Unfortunately
+ % we can't prevent a possible page break at the following
+ % \baselineskip glue.
+ \nobreak
+ \endgroup
+ \itemxneedsnegativevskipfalse
+ \else
+ % The item text fits into the space. Start a paragraph, so that the
+ % following text (if any) will end up on the same line.
+ \noindent
+ % Do this with kerns and \unhbox so that if there is a footnote in
+ % the item text, it can migrate to the main vertical list and
+ % eventually be printed.
+ \nobreak\kern-\tableindent
+ \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0
+ \unhbox0
+ \nobreak\kern\dimen0
+ \endgroup
+ \itemxneedsnegativevskiptrue
+ \fi
+}
+
+\def\item{\errmessage{@item while not in a table}}
+\def\itemx{\errmessage{@itemx while not in a table}}
+\def\kitem{\errmessage{@kitem while not in a table}}
+\def\kitemx{\errmessage{@kitemx while not in a table}}
+\def\xitem{\errmessage{@xitem while not in a table}}
+\def\xitemx{\errmessage{@xitemx while not in a table}}
+
+% Contains a kludge to get @end[description] to work.
+\def\description{\tablez{\dontindex}{1}{}{}{}{}}
+
+% @table, @ftable, @vtable.
+\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex}
+{\obeylines\obeyspaces%
+\gdef\tablex #1^^M{%
+\tabley\dontindex#1 \endtabley}}
+
+\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex}
+{\obeylines\obeyspaces%
+\gdef\ftablex #1^^M{%
+\tabley\fnitemindex#1 \endtabley
+\def\Eftable{\endgraf\afterenvbreak\endgroup}%
+\let\Etable=\relax}}
+
+\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex}
+{\obeylines\obeyspaces%
+\gdef\vtablex #1^^M{%
+\tabley\vritemindex#1 \endtabley
+\def\Evtable{\endgraf\afterenvbreak\endgroup}%
+\let\Etable=\relax}}
+
+\def\dontindex #1{}
+\def\fnitemindex #1{\doind {fn}{\code{#1}}}%
+\def\vritemindex #1{\doind {vr}{\code{#1}}}%
+
+{\obeyspaces %
+\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup%
+\tablez{#1}{#2}{#3}{#4}{#5}{#6}}}
+
+\def\tablez #1#2#3#4#5#6{%
+\aboveenvbreak %
+\begingroup %
+\def\Edescription{\Etable}% Necessary kludge.
+\let\itemindex=#1%
+\ifnum 0#3>0 \advance \leftskip by #3\mil \fi %
+\ifnum 0#4>0 \tableindent=#4\mil \fi %
+\ifnum 0#5>0 \advance \rightskip by #5\mil \fi %
+\def\itemfont{#2}%
+\itemmax=\tableindent %
+\advance \itemmax by -\itemmargin %
+\advance \leftskip by \tableindent %
+\exdentamount=\tableindent
+\parindent = 0pt
+\parskip = \smallskipamount
+\ifdim \parskip=0pt \parskip=2pt \fi%
+\def\Etable{\endgraf\afterenvbreak\endgroup}%
+\let\item = \internalBitem %
+\let\itemx = \internalBitemx %
+\let\kitem = \internalBkitem %
+\let\kitemx = \internalBkitemx %
+\let\xitem = \internalBxitem %
+\let\xitemx = \internalBxitemx %
+}
+
+% This is the counter used by @enumerate, which is really @itemize
+
+\newcount \itemno
+
+\def\itemize{\parsearg\itemizezzz}
+
+\def\itemizezzz #1{%
+ \begingroup % ended by the @end itemize
+ \itemizey {#1}{\Eitemize}
+}
+
+\def\itemizey #1#2{%
+\aboveenvbreak %
+\itemmax=\itemindent %
+\advance \itemmax by -\itemmargin %
+\advance \leftskip by \itemindent %
+\exdentamount=\itemindent
+\parindent = 0pt %
+\parskip = \smallskipamount %
+\ifdim \parskip=0pt \parskip=2pt \fi%
+\def#2{\endgraf\afterenvbreak\endgroup}%
+\def\itemcontents{#1}%
+\let\item=\itemizeitem}
+
+% Set sfcode to normal for the chars that usually have another value.
+% These are `.?!:;,'
+\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000
+ \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 }
+
+% \splitoff TOKENS\endmark defines \first to be the first token in
+% TOKENS, and \rest to be the remainder.
+%
+\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%
+
+% Allow an optional argument of an uppercase letter, lowercase letter,
+% or number, to specify the first label in the enumerated list. No
+% argument is the same as `1'.
+%
+\def\enumerate{\parsearg\enumeratezzz}
+\def\enumeratezzz #1{\enumeratey #1 \endenumeratey}
+\def\enumeratey #1 #2\endenumeratey{%
+ \begingroup % ended by the @end enumerate
+ %
+ % If we were given no argument, pretend we were given `1'.
+ \def\thearg{#1}%
+ \ifx\thearg\empty \def\thearg{1}\fi
+ %
+ % Detect if the argument is a single token. If so, it might be a
+ % letter. Otherwise, the only valid thing it can be is a number.
+ % (We will always have one token, because of the test we just made.
+ % This is a good thing, since \splitoff doesn't work given nothing at
+ % all -- the first parameter is undelimited.)
+ \expandafter\splitoff\thearg\endmark
+ \ifx\rest\empty
+ % Only one token in the argument. It could still be anything.
+ % A ``lowercase letter'' is one whose \lccode is nonzero.
+ % An ``uppercase letter'' is one whose \lccode is both nonzero, and
+ % not equal to itself.
+ % Otherwise, we assume it's a number.
+ %
+ % We need the \relax at the end of the \ifnum lines to stop TeX from
+ % continuing to look for a <number>.
+ %
+ \ifnum\lccode\expandafter`\thearg=0\relax
+ \numericenumerate % a number (we hope)
+ \else
+ % It's a letter.
+ \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax
+ \lowercaseenumerate % lowercase letter
+ \else
+ \uppercaseenumerate % uppercase letter
+ \fi
+ \fi
+ \else
+ % Multiple tokens in the argument. We hope it's a number.
+ \numericenumerate
+ \fi
+}
+
+% An @enumerate whose labels are integers. The starting integer is
+% given in \thearg.
+%
+\def\numericenumerate{%
+ \itemno = \thearg
+ \startenumeration{\the\itemno}%
+}
+
+% The starting (lowercase) letter is in \thearg.
+\def\lowercaseenumerate{%
+ \itemno = \expandafter`\thearg
+ \startenumeration{%
+ % Be sure we're not beyond the end of the alphabet.
+ \ifnum\itemno=0
+ \errmessage{No more lowercase letters in @enumerate; get a bigger
+ alphabet}%
+ \fi
+ \char\lccode\itemno
+ }%
+}
+
+% The starting (uppercase) letter is in \thearg.
+\def\uppercaseenumerate{%
+ \itemno = \expandafter`\thearg
+ \startenumeration{%
+ % Be sure we're not beyond the end of the alphabet.
+ \ifnum\itemno=0
+ \errmessage{No more uppercase letters in @enumerate; get a bigger
+ alphabet}
+ \fi
+ \char\uccode\itemno
+ }%
+}
+
+% Call itemizey, adding a period to the first argument and supplying the
+% common last two arguments. Also subtract one from the initial value in
+% \itemno, since @item increments \itemno.
+%
+\def\startenumeration#1{%
+ \advance\itemno by -1
+ \itemizey{#1.}\Eenumerate\flushcr
+}
+
+% @alphaenumerate and @capsenumerate are abbreviations for giving an arg
+% to @enumerate.
+%
+\def\alphaenumerate{\enumerate{a}}
+\def\capsenumerate{\enumerate{A}}
+\def\Ealphaenumerate{\Eenumerate}
+\def\Ecapsenumerate{\Eenumerate}
+
+% Definition of @item while inside @itemize.
+
+\def\itemizeitem{%
+\advance\itemno by 1
+{\let\par=\endgraf \smallbreak}%
+\ifhmode \errmessage{In hmode at itemizeitem}\fi
+{\parskip=0in \hskip 0pt
+\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}%
+\vadjust{\penalty 1200}}%
+\flushcr}
+
+% @multitable macros
+% Amy Hendrickson, 8/18/94, 3/6/96
+%
+% @multitable ... @end multitable will make as many columns as desired.
+% Contents of each column will wrap at width given in preamble. Width
+% can be specified either with sample text given in a template line,
+% or in percent of \hsize, the current width of text on page.
+
+% Table can continue over pages but will only break between lines.
+
+% To make preamble:
+%
+% Either define widths of columns in terms of percent of \hsize:
+% @multitable @columnfractions .25 .3 .45
+% @item ...
+%
+% Numbers following @columnfractions are the percent of the total
+% current hsize to be used for each column. You may use as many
+% columns as desired.
+
+
+% Or use a template:
+% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+% @item ...
+% using the widest term desired in each column.
+%
+% For those who want to use more than one line's worth of words in
+% the preamble, break the line within one argument and it
+% will parse correctly, i.e.,
+%
+% @multitable {Column 1 template} {Column 2 template} {Column 3
+% template}
+% Not:
+% @multitable {Column 1 template} {Column 2 template}
+% {Column 3 template}
+
+% Each new table line starts with @item, each subsequent new column
+% starts with @tab. Empty columns may be produced by supplying @tab's
+% with nothing between them for as many times as empty columns are needed,
+% ie, @tab@tab@tab will produce two empty columns.
+
+% @item, @tab, @multitable or @end multitable do not need to be on their
+% own lines, but it will not hurt if they are.
+
+% Sample multitable:
+
+% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+% @item first col stuff @tab second col stuff @tab third col
+% @item
+% first col stuff
+% @tab
+% second col stuff
+% @tab
+% third col
+% @item first col stuff @tab second col stuff
+% @tab Many paragraphs of text may be used in any column.
+%
+% They will wrap at the width determined by the template.
+% @item@tab@tab This will be in third column.
+% @end multitable
+
+% Default dimensions may be reset by user.
+% @multitableparskip is vertical space between paragraphs in table.
+% @multitableparindent is paragraph indent in table.
+% @multitablecolmargin is horizontal space to be left between columns.
+% @multitablelinespace is space to leave between table items, baseline
+% to baseline.
+% 0pt means it depends on current normal line spacing.
+%
+\newskip\multitableparskip
+\newskip\multitableparindent
+\newdimen\multitablecolspace
+\newskip\multitablelinespace
+\multitableparskip=0pt
+\multitableparindent=6pt
+\multitablecolspace=12pt
+\multitablelinespace=0pt
+
+% Macros used to set up halign preamble:
+%
+\let\endsetuptable\relax
+\def\xendsetuptable{\endsetuptable}
+\let\columnfractions\relax
+\def\xcolumnfractions{\columnfractions}
+\newif\ifsetpercent
+
+% #1 is the part of the @columnfraction before the decimal point, which
+% is presumably either 0 or the empty string (but we don't check, we
+% just throw it away). #2 is the decimal part, which we use as the
+% percent of \hsize for this column.
+\def\pickupwholefraction#1.#2 {%
+ \global\advance\colcount by 1
+ \expandafter\xdef\csname col\the\colcount\endcsname{.#2\hsize}%
+ \setuptable
+}
+
+\newcount\colcount
+\def\setuptable#1{%
+ \def\firstarg{#1}%
+ \ifx\firstarg\xendsetuptable
+ \let\go = \relax
+ \else
+ \ifx\firstarg\xcolumnfractions
+ \global\setpercenttrue
+ \else
+ \ifsetpercent
+ \let\go\pickupwholefraction
+ \else
+ \global\advance\colcount by 1
+ \setbox0=\hbox{#1\unskip }% Add a normal word space as a separator;
+ % typically that is always in the input, anyway.
+ \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%
+ \fi
+ \fi
+ \ifx\go\pickupwholefraction
+ % Put the argument back for the \pickupwholefraction call, so
+ % we'll always have a period there to be parsed.
+ \def\go{\pickupwholefraction#1}%
+ \else
+ \let\go = \setuptable
+ \fi%
+ \fi
+ \go
+}
+
+% This used to have \hskip1sp. But then the space in a template line is
+% not enough. That is bad. So let's go back to just & until we
+% encounter the problem it was intended to solve again.
+% --karl, nathan@acm.org, 20apr99.
+\def\tab{&}
+
+% @multitable ... @end multitable definitions:
+%
+\def\multitable{\parsearg\dotable}
+\def\dotable#1{\bgroup
+ \vskip\parskip
+ \let\item\crcr
+ \tolerance=9500
+ \hbadness=9500
+ \setmultitablespacing
+ \parskip=\multitableparskip
+ \parindent=\multitableparindent
+ \overfullrule=0pt
+ \global\colcount=0
+ \def\Emultitable{\global\setpercentfalse\cr\egroup\egroup}%
+ %
+ % To parse everything between @multitable and @item:
+ \setuptable#1 \endsetuptable
+ %
+ % \everycr will reset column counter, \colcount, at the end of
+ % each line. Every column entry will cause \colcount to advance by one.
+ % The table preamble
+ % looks at the current \colcount to find the correct column width.
+ \everycr{\noalign{%
+ %
+ % \filbreak%% keeps underfull box messages off when table breaks over pages.
+ % Maybe so, but it also creates really weird page breaks when the table
+ % breaks over pages. Wouldn't \vfil be better? Wait until the problem
+ % manifests itself, so it can be fixed for real --karl.
+ \global\colcount=0\relax}}%
+ %
+ % This preamble sets up a generic column definition, which will
+ % be used as many times as user calls for columns.
+ % \vtop will set a single line and will also let text wrap and
+ % continue for many paragraphs if desired.
+ \halign\bgroup&\global\advance\colcount by 1\relax
+ \multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname
+ %
+ % In order to keep entries from bumping into each other
+ % we will add a \leftskip of \multitablecolspace to all columns after
+ % the first one.
+ %
+ % If a template has been used, we will add \multitablecolspace
+ % to the width of each template entry.
+ %
+ % If the user has set preamble in terms of percent of \hsize we will
+ % use that dimension as the width of the column, and the \leftskip
+ % will keep entries from bumping into each other. Table will start at
+ % left margin and final column will justify at right margin.
+ %
+ % Make sure we don't inherit \rightskip from the outer environment.
+ \rightskip=0pt
+ \ifnum\colcount=1
+ % The first column will be indented with the surrounding text.
+ \advance\hsize by\leftskip
+ \else
+ \ifsetpercent \else
+ % If user has not set preamble in terms of percent of \hsize
+ % we will advance \hsize by \multitablecolspace.
+ \advance\hsize by \multitablecolspace
+ \fi
+ % In either case we will make \leftskip=\multitablecolspace:
+ \leftskip=\multitablecolspace
+ \fi
+ % Ignoring space at the beginning and end avoids an occasional spurious
+ % blank line, when TeX decides to break the line at the space before the
+ % box from the multistrut, so the strut ends up on a line by itself.
+ % For example:
+ % @multitable @columnfractions .11 .89
+ % @item @code{#}
+ % @tab Legal holiday which is valid in major parts of the whole country.
+ % Is automatically provided with highlighting sequences respectively marking
+ % characters.
+ \noindent\ignorespaces##\unskip\multistrut}\cr
+}
+
+\def\setmultitablespacing{% test to see if user has set \multitablelinespace.
+% If so, do nothing. If not, give it an appropriate dimension based on
+% current baselineskip.
+\ifdim\multitablelinespace=0pt
+\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip
+\global\advance\multitablelinespace by-\ht0
+%% strut to put in table in case some entry doesn't have descenders,
+%% to keep lines equally spaced
+\let\multistrut = \strut
+\else
+%% FIXME: what is \box0 supposed to be?
+\gdef\multistrut{\vrule height\multitablelinespace depth\dp0
+width0pt\relax} \fi
+%% Test to see if parskip is larger than space between lines of
+%% table. If not, do nothing.
+%% If so, set to same dimension as multitablelinespace.
+\ifdim\multitableparskip>\multitablelinespace
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
+ %% than skip between lines in the table.
+\fi%
+\ifdim\multitableparskip=0pt
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
+ %% than skip between lines in the table.
+\fi}
+
+
+\message{conditionals,}
+% Prevent errors for section commands.
+% Used in @ignore and in failing conditionals.
+\def\ignoresections{%
+ \let\chapter=\relax
+ \let\unnumbered=\relax
+ \let\top=\relax
+ \let\unnumberedsec=\relax
+ \let\unnumberedsection=\relax
+ \let\unnumberedsubsec=\relax
+ \let\unnumberedsubsection=\relax
+ \let\unnumberedsubsubsec=\relax
+ \let\unnumberedsubsubsection=\relax
+ \let\section=\relax
+ \let\subsec=\relax
+ \let\subsubsec=\relax
+ \let\subsection=\relax
+ \let\subsubsection=\relax
+ \let\appendix=\relax
+ \let\appendixsec=\relax
+ \let\appendixsection=\relax
+ \let\appendixsubsec=\relax
+ \let\appendixsubsection=\relax
+ \let\appendixsubsubsec=\relax
+ \let\appendixsubsubsection=\relax
+ \let\contents=\relax
+ \let\smallbook=\relax
+ \let\titlepage=\relax
+}
+
+% Used in nested conditionals, where we have to parse the Texinfo source
+% and so want to turn off most commands, in case they are used
+% incorrectly.
+%
+\def\ignoremorecommands{%
+ \let\defcodeindex = \relax
+ \let\defcv = \relax
+ \let\deffn = \relax
+ \let\deffnx = \relax
+ \let\defindex = \relax
+ \let\defivar = \relax
+ \let\defmac = \relax
+ \let\defmethod = \relax
+ \let\defop = \relax
+ \let\defopt = \relax
+ \let\defspec = \relax
+ \let\deftp = \relax
+ \let\deftypefn = \relax
+ \let\deftypefun = \relax
+ \let\deftypeivar = \relax
+ \let\deftypeop = \relax
+ \let\deftypevar = \relax
+ \let\deftypevr = \relax
+ \let\defun = \relax
+ \let\defvar = \relax
+ \let\defvr = \relax
+ \let\ref = \relax
+ \let\xref = \relax
+ \let\printindex = \relax
+ \let\pxref = \relax
+ \let\settitle = \relax
+ \let\setchapternewpage = \relax
+ \let\setchapterstyle = \relax
+ \let\everyheading = \relax
+ \let\evenheading = \relax
+ \let\oddheading = \relax
+ \let\everyfooting = \relax
+ \let\evenfooting = \relax
+ \let\oddfooting = \relax
+ \let\headings = \relax
+ \let\include = \relax
+ \let\lowersections = \relax
+ \let\down = \relax
+ \let\raisesections = \relax
+ \let\up = \relax
+ \let\set = \relax
+ \let\clear = \relax
+ \let\item = \relax
+}
+
+% Ignore @ignore ... @end ignore.
+%
+\def\ignore{\doignore{ignore}}
+
+% Ignore @ifinfo, @ifhtml, @ifnottex, @html, @menu, and @direntry text.
+%
+\def\ifinfo{\doignore{ifinfo}}
+\def\ifhtml{\doignore{ifhtml}}
+\def\ifnottex{\doignore{ifnottex}}
+\def\html{\doignore{html}}
+\def\menu{\doignore{menu}}
+\def\direntry{\doignore{direntry}}
+
+% @dircategory CATEGORY -- specify a category of the dir file
+% which this file should belong to. Ignore this in TeX.
+\let\dircategory = \comment
+
+% Ignore text until a line `@end #1'.
+%
+\def\doignore#1{\begingroup
+ % Don't complain about control sequences we have declared \outer.
+ \ignoresections
+ %
+ % Define a command to swallow text until we reach `@end #1'.
+ % This @ is a catcode 12 token (that is the normal catcode of @ in
+ % this texinfo.tex file). We change the catcode of @ below to match.
+ \long\def\doignoretext##1@end #1{\enddoignore}%
+ %
+ % Make sure that spaces turn into tokens that match what \doignoretext wants.
+ \catcode32 = 10
+ %
+ % Ignore braces, too, so mismatched braces don't cause trouble.
+ \catcode`\{ = 9
+ \catcode`\} = 9
+ %
+ % We must not have @c interpreted as a control sequence.
+ \catcode`\@ = 12
+ %
+ % Make the letter c a comment character so that the rest of the line
+ % will be ignored. This way, the document can have (for example)
+ % @c @end ifinfo
+ % and the @end ifinfo will be properly ignored.
+ % (We've just changed @ to catcode 12.)
+ \catcode`\c = 14
+ %
+ % And now expand that command.
+ \doignoretext
+}
+
+% What we do to finish off ignored text.
+%
+\def\enddoignore{\endgroup\ignorespaces}%
+
+\newif\ifwarnedobs\warnedobsfalse
+\def\obstexwarn{%
+ \ifwarnedobs\relax\else
+ % We need to warn folks that they may have trouble with TeX 3.0.
+ % This uses \immediate\write16 rather than \message to get newlines.
+ \immediate\write16{}
+ \immediate\write16{WARNING: for users of Unix TeX 3.0!}
+ \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).}
+ \immediate\write16{If you are running another version of TeX, relax.}
+ \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.}
+ \immediate\write16{ Then upgrade your TeX installation if you can.}
+ \immediate\write16{ (See ftp://ftp.gnu.org/pub/gnu/TeX.README.)}
+ \immediate\write16{If you are stuck with version 3.0, run the}
+ \immediate\write16{ script ``tex3patch'' from the Texinfo distribution}
+ \immediate\write16{ to use a workaround.}
+ \immediate\write16{}
+ \global\warnedobstrue
+ \fi
+}
+
+% **In TeX 3.0, setting text in \nullfont hangs tex. For a
+% workaround (which requires the file ``dummy.tfm'' to be installed),
+% uncomment the following line:
+%%%%%\font\nullfont=dummy\let\obstexwarn=\relax
+
+% Ignore text, except that we keep track of conditional commands for
+% purposes of nesting, up to an `@end #1' command.
+%
+\def\nestedignore#1{%
+ \obstexwarn
+ % We must actually expand the ignored text to look for the @end
+ % command, so that nested ignore constructs work. Thus, we put the
+ % text into a \vbox and then do nothing with the result. To minimize
+ % the change of memory overflow, we follow the approach outlined on
+ % page 401 of the TeXbook: make the current font be a dummy font.
+ %
+ \setbox0 = \vbox\bgroup
+ % Don't complain about control sequences we have declared \outer.
+ \ignoresections
+ %
+ % Define `@end #1' to end the box, which will in turn undefine the
+ % @end command again.
+ \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}%
+ %
+ % We are going to be parsing Texinfo commands. Most cause no
+ % trouble when they are used incorrectly, but some commands do
+ % complicated argument parsing or otherwise get confused, so we
+ % undefine them.
+ %
+ % We can't do anything about stray @-signs, unfortunately;
+ % they'll produce `undefined control sequence' errors.
+ \ignoremorecommands
+ %
+ % Set the current font to be \nullfont, a TeX primitive, and define
+ % all the font commands to also use \nullfont. We don't use
+ % dummy.tfm, as suggested in the TeXbook, because not all sites
+ % might have that installed. Therefore, math mode will still
+ % produce output, but that should be an extremely small amount of
+ % stuff compared to the main input.
+ %
+ \nullfont
+ \let\tenrm=\nullfont \let\tenit=\nullfont \let\tensl=\nullfont
+ \let\tenbf=\nullfont \let\tentt=\nullfont \let\smallcaps=\nullfont
+ \let\tensf=\nullfont
+ % Similarly for index fonts (mostly for their use in smallexample).
+ \let\smallrm=\nullfont \let\smallit=\nullfont \let\smallsl=\nullfont
+ \let\smallbf=\nullfont \let\smalltt=\nullfont \let\smallsc=\nullfont
+ \let\smallsf=\nullfont
+ %
+ % Don't complain when characters are missing from the fonts.
+ \tracinglostchars = 0
+ %
+ % Don't bother to do space factor calculations.
+ \frenchspacing
+ %
+ % Don't report underfull hboxes.
+ \hbadness = 10000
+ %
+ % Do minimal line-breaking.
+ \pretolerance = 10000
+ %
+ % Do not execute instructions in @tex
+ \def\tex{\doignore{tex}}%
+ % Do not execute macro definitions.
+ % `c' is a comment character, so the word `macro' will get cut off.
+ \def\macro{\doignore{ma}}%
+}
+
+% @set VAR sets the variable VAR to an empty value.
+% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.
+%
+% Since we want to separate VAR from REST-OF-LINE (which might be
+% empty), we can't just use \parsearg; we have to insert a space of our
+% own to delimit the rest of the line, and then take it out again if we
+% didn't need it. Make sure the catcode of space is correct to avoid
+% losing inside @example, for instance.
+%
+\def\set{\begingroup\catcode` =10
+ \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR.
+ \parsearg\setxxx}
+\def\setxxx#1{\setyyy#1 \endsetyyy}
+\def\setyyy#1 #2\endsetyyy{%
+ \def\temp{#2}%
+ \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty
+ \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted.
+ \fi
+ \endgroup
+}
+% Can't use \xdef to pre-expand #2 and save some time, since \temp or
+% \next or other control sequences that we've defined might get us into
+% an infinite loop. Consider `@set foo @cite{bar}'.
+\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}}
+
+% @clear VAR clears (i.e., unsets) the variable VAR.
+%
+\def\clear{\parsearg\clearxxx}
+\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax}
+
+% @value{foo} gets the text saved in variable foo.
+{
+ \catcode`\_ = \active
+ %
+ % We might end up with active _ or - characters in the argument if
+ % we're called from @code, as @code{@value{foo-bar_}}. So \let any
+ % such active characters to their normal equivalents.
+ \gdef\value{\begingroup
+ \catcode`\-=12 \catcode`\_=12
+ \indexbreaks \let_\normalunderscore
+ \valuexxx}
+}
+\def\valuexxx#1{\expandablevalue{#1}\endgroup}
+
+% We have this subroutine so that we can handle at least some @value's
+% properly in indexes (we \let\value to this in \indexdummies). Ones
+% whose names contain - or _ still won't work, but we can't do anything
+% about that. The command has to be fully expandable, since the result
+% winds up in the index file. This means that if the variable's value
+% contains other Texinfo commands, it's almost certain it will fail
+% (although perhaps we could fix that with sufficient work to do a
+% one-level expansion on the result, instead of complete).
+%
+\def\expandablevalue#1{%
+ \expandafter\ifx\csname SET#1\endcsname\relax
+ {[No value for ``#1'']}%
+ \else
+ \csname SET#1\endcsname
+ \fi
+}
+
+% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined
+% with @set.
+%
+\def\ifset{\parsearg\ifsetxxx}
+\def\ifsetxxx #1{%
+ \expandafter\ifx\csname SET#1\endcsname\relax
+ \expandafter\ifsetfail
+ \else
+ \expandafter\ifsetsucceed
+ \fi
+}
+\def\ifsetsucceed{\conditionalsucceed{ifset}}
+\def\ifsetfail{\nestedignore{ifset}}
+\defineunmatchedend{ifset}
+
+% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been
+% defined with @set, or has been undefined with @clear.
+%
+\def\ifclear{\parsearg\ifclearxxx}
+\def\ifclearxxx #1{%
+ \expandafter\ifx\csname SET#1\endcsname\relax
+ \expandafter\ifclearsucceed
+ \else
+ \expandafter\ifclearfail
+ \fi
+}
+\def\ifclearsucceed{\conditionalsucceed{ifclear}}
+\def\ifclearfail{\nestedignore{ifclear}}
+\defineunmatchedend{ifclear}
+
+% @iftex, @ifnothtml, @ifnotinfo always succeed; we read the text
+% following, through the first @end iftex (etc.). Make `@end iftex'
+% (etc.) valid only after an @iftex.
+%
+\def\iftex{\conditionalsucceed{iftex}}
+\def\ifnothtml{\conditionalsucceed{ifnothtml}}
+\def\ifnotinfo{\conditionalsucceed{ifnotinfo}}
+\defineunmatchedend{iftex}
+\defineunmatchedend{ifnothtml}
+\defineunmatchedend{ifnotinfo}
+
+% We can't just want to start a group at @iftex (for example) and end it
+% at @end iftex, since then @set commands inside the conditional have no
+% effect (they'd get reverted at the end of the group). So we must
+% define \Eiftex to redefine itself to be its previous value. (We can't
+% just define it to fail again with an ``unmatched end'' error, since
+% the @ifset might be nested.)
+%
+\def\conditionalsucceed#1{%
+ \edef\temp{%
+ % Remember the current value of \E#1.
+ \let\nece{prevE#1} = \nece{E#1}%
+ %
+ % At the `@end #1', redefine \E#1 to be its previous value.
+ \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}%
+ }%
+ \temp
+}
+
+% We need to expand lots of \csname's, but we don't want to expand the
+% control sequences after we've constructed them.
+%
+\def\nece#1{\expandafter\noexpand\csname#1\endcsname}
+
+% @defininfoenclose.
+\let\definfoenclose=\comment
+
+
+\message{indexing,}
+% Index generation facilities
+
+% Define \newwrite to be identical to plain tex's \newwrite
+% except not \outer, so it can be used within \newindex.
+{\catcode`\@=11
+\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}}
+
+% \newindex {foo} defines an index named foo.
+% It automatically defines \fooindex such that
+% \fooindex ...rest of line... puts an entry in the index foo.
+% It also defines \fooindfile to be the number of the output channel for
+% the file that accumulates this index. The file's extension is foo.
+% The name of an index should be no more than 2 characters long
+% for the sake of vms.
+%
+\def\newindex#1{%
+ \iflinks
+ \expandafter\newwrite \csname#1indfile\endcsname
+ \openout \csname#1indfile\endcsname \jobname.#1 % Open the file
+ \fi
+ \expandafter\xdef\csname#1index\endcsname{% % Define @#1index
+ \noexpand\doindex{#1}}
+}
+
+% @defindex foo == \newindex{foo}
+
+\def\defindex{\parsearg\newindex}
+
+% Define @defcodeindex, like @defindex except put all entries in @code.
+
+\def\newcodeindex#1{%
+ \iflinks
+ \expandafter\newwrite \csname#1indfile\endcsname
+ \openout \csname#1indfile\endcsname \jobname.#1
+ \fi
+ \expandafter\xdef\csname#1index\endcsname{%
+ \noexpand\docodeindex{#1}}
+}
+
+\def\defcodeindex{\parsearg\newcodeindex}
+
+% @synindex foo bar makes index foo feed into index bar.
+% Do this instead of @defindex foo if you don't want it as a separate index.
+% The \closeout helps reduce unnecessary open files; the limit on the
+% Acorn RISC OS is a mere 16 files.
+\def\synindex#1 #2 {%
+ \expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname
+ \expandafter\closeout\csname#1indfile\endcsname
+ \expandafter\let\csname#1indfile\endcsname=\synindexfoo
+ \expandafter\xdef\csname#1index\endcsname{% define \xxxindex
+ \noexpand\doindex{#2}}%
+}
+
+% @syncodeindex foo bar similar, but put all entries made for index foo
+% inside @code.
+\def\syncodeindex#1 #2 {%
+ \expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname
+ \expandafter\closeout\csname#1indfile\endcsname
+ \expandafter\let\csname#1indfile\endcsname=\synindexfoo
+ \expandafter\xdef\csname#1index\endcsname{% define \xxxindex
+ \noexpand\docodeindex{#2}}%
+}
+
+% Define \doindex, the driver for all \fooindex macros.
+% Argument #1 is generated by the calling \fooindex macro,
+% and it is "foo", the name of the index.
+
+% \doindex just uses \parsearg; it calls \doind for the actual work.
+% This is because \doind is more useful to call from other macros.
+
+% There is also \dosubind {index}{topic}{subtopic}
+% which makes an entry in a two-level index such as the operation index.
+
+\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer}
+\def\singleindexer #1{\doind{\indexname}{#1}}
+
+% like the previous two, but they put @code around the argument.
+\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}
+\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}
+
+\def\indexdummies{%
+\def\ { }%
+% Take care of the plain tex accent commands.
+\def\"{\realbackslash "}%
+\def\`{\realbackslash `}%
+\def\'{\realbackslash '}%
+\def\^{\realbackslash ^}%
+\def\~{\realbackslash ~}%
+\def\={\realbackslash =}%
+\def\b{\realbackslash b}%
+\def\c{\realbackslash c}%
+\def\d{\realbackslash d}%
+\def\u{\realbackslash u}%
+\def\v{\realbackslash v}%
+\def\H{\realbackslash H}%
+% Take care of the plain tex special European modified letters.
+\def\oe{\realbackslash oe}%
+\def\ae{\realbackslash ae}%
+\def\aa{\realbackslash aa}%
+\def\OE{\realbackslash OE}%
+\def\AE{\realbackslash AE}%
+\def\AA{\realbackslash AA}%
+\def\o{\realbackslash o}%
+\def\O{\realbackslash O}%
+\def\l{\realbackslash l}%
+\def\L{\realbackslash L}%
+\def\ss{\realbackslash ss}%
+% Take care of texinfo commands likely to appear in an index entry.
+% (Must be a way to avoid doing expansion at all, and thus not have to
+% laboriously list every single command here.)
+\def\@{@}% will be @@ when we switch to @ as escape char.
+% Need these in case \tex is in effect and \{ is a \delimiter again.
+% But can't use \lbracecmd and \rbracecmd because texindex assumes
+% braces and backslashes are used only as delimiters.
+\let\{ = \mylbrace
+\let\} = \myrbrace
+\def\_{{\realbackslash _}}%
+\def\w{\realbackslash w }%
+\def\bf{\realbackslash bf }%
+%\def\rm{\realbackslash rm }%
+\def\sl{\realbackslash sl }%
+\def\sf{\realbackslash sf}%
+\def\tt{\realbackslash tt}%
+\def\gtr{\realbackslash gtr}%
+\def\less{\realbackslash less}%
+\def\hat{\realbackslash hat}%
+\def\TeX{\realbackslash TeX}%
+\def\dots{\realbackslash dots }%
+\def\result{\realbackslash result}%
+\def\equiv{\realbackslash equiv}%
+\def\expansion{\realbackslash expansion}%
+\def\print{\realbackslash print}%
+\def\error{\realbackslash error}%
+\def\point{\realbackslash point}%
+\def\copyright{\realbackslash copyright}%
+\def\tclose##1{\realbackslash tclose {##1}}%
+\def\code##1{\realbackslash code {##1}}%
+\def\uref##1{\realbackslash uref {##1}}%
+\def\url##1{\realbackslash url {##1}}%
+\def\env##1{\realbackslash env {##1}}%
+\def\command##1{\realbackslash command {##1}}%
+\def\option##1{\realbackslash option {##1}}%
+\def\dotless##1{\realbackslash dotless {##1}}%
+\def\samp##1{\realbackslash samp {##1}}%
+\def\,##1{\realbackslash ,{##1}}%
+\def\t##1{\realbackslash t {##1}}%
+\def\r##1{\realbackslash r {##1}}%
+\def\i##1{\realbackslash i {##1}}%
+\def\b##1{\realbackslash b {##1}}%
+\def\sc##1{\realbackslash sc {##1}}%
+\def\cite##1{\realbackslash cite {##1}}%
+\def\key##1{\realbackslash key {##1}}%
+\def\file##1{\realbackslash file {##1}}%
+\def\var##1{\realbackslash var {##1}}%
+\def\kbd##1{\realbackslash kbd {##1}}%
+\def\dfn##1{\realbackslash dfn {##1}}%
+\def\emph##1{\realbackslash emph {##1}}%
+\def\acronym##1{\realbackslash acronym {##1}}%
+%
+% Handle some cases of @value -- where the variable name does not
+% contain - or _, and the value does not contain any
+% (non-fully-expandable) commands.
+\let\value = \expandablevalue
+%
+\unsepspaces
+% Turn off macro expansion
+\turnoffmacros
+}
+
+% If an index command is used in an @example environment, any spaces
+% therein should become regular spaces in the raw index file, not the
+% expansion of \tie (\\leavevmode \penalty \@M \ ).
+{\obeyspaces
+ \gdef\unsepspaces{\obeyspaces\let =\space}}
+
+% \indexnofonts no-ops all font-change commands.
+% This is used when outputting the strings to sort the index by.
+\def\indexdummyfont#1{#1}
+\def\indexdummytex{TeX}
+\def\indexdummydots{...}
+
+\def\indexnofonts{%
+% Just ignore accents.
+\let\,=\indexdummyfont
+\let\"=\indexdummyfont
+\let\`=\indexdummyfont
+\let\'=\indexdummyfont
+\let\^=\indexdummyfont
+\let\~=\indexdummyfont
+\let\==\indexdummyfont
+\let\b=\indexdummyfont
+\let\c=\indexdummyfont
+\let\d=\indexdummyfont
+\let\u=\indexdummyfont
+\let\v=\indexdummyfont
+\let\H=\indexdummyfont
+\let\dotless=\indexdummyfont
+% Take care of the plain tex special European modified letters.
+\def\oe{oe}%
+\def\ae{ae}%
+\def\aa{aa}%
+\def\OE{OE}%
+\def\AE{AE}%
+\def\AA{AA}%
+\def\o{o}%
+\def\O{O}%
+\def\l{l}%
+\def\L{L}%
+\def\ss{ss}%
+\let\w=\indexdummyfont
+\let\t=\indexdummyfont
+\let\r=\indexdummyfont
+\let\i=\indexdummyfont
+\let\b=\indexdummyfont
+\let\emph=\indexdummyfont
+\let\strong=\indexdummyfont
+\let\cite=\indexdummyfont
+\let\sc=\indexdummyfont
+%Don't no-op \tt, since it isn't a user-level command
+% and is used in the definitions of the active chars like <, >, |...
+%\let\tt=\indexdummyfont
+\let\tclose=\indexdummyfont
+\let\code=\indexdummyfont
+\let\url=\indexdummyfont
+\let\uref=\indexdummyfont
+\let\env=\indexdummyfont
+\let\acronym=\indexdummyfont
+\let\command=\indexdummyfont
+\let\option=\indexdummyfont
+\let\file=\indexdummyfont
+\let\samp=\indexdummyfont
+\let\kbd=\indexdummyfont
+\let\key=\indexdummyfont
+\let\var=\indexdummyfont
+\let\TeX=\indexdummytex
+\let\dots=\indexdummydots
+\def\@{@}%
+}
+
+% To define \realbackslash, we must make \ not be an escape.
+% We must first make another character (@) an escape
+% so we do not become unable to do a definition.
+
+{\catcode`\@=0 \catcode`\\=\other
+ @gdef@realbackslash{\}}
+
+\let\indexbackslash=0 %overridden during \printindex.
+\let\SETmarginindex=\relax % put index entries in margin (undocumented)?
+
+% For \ifx comparisons.
+\def\emptymacro{\empty}
+
+% Most index entries go through here, but \dosubind is the general case.
+%
+\def\doind#1#2{\dosubind{#1}{#2}\empty}
+
+% Workhorse for all \fooindexes.
+% #1 is name of index, #2 is stuff to put there, #3 is subentry --
+% \empty if called from \doind, as we usually are. The main exception
+% is with defuns, which call us directly.
+%
+\def\dosubind#1#2#3{%
+ % Put the index entry in the margin if desired.
+ \ifx\SETmarginindex\relax\else
+ \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}%
+ \fi
+ {%
+ \count255=\lastpenalty
+ {%
+ \indexdummies % Must do this here, since \bf, etc expand at this stage
+ \escapechar=`\\
+ {%
+ \let\folio = 0% We will expand all macros now EXCEPT \folio.
+ \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now
+ % so it will be output as is; and it will print as backslash.
+ %
+ \def\thirdarg{#3}%
+ %
+ % If third arg is present, precede it with space in sort key.
+ \ifx\thirdarg\emptymacro
+ \let\subentry = \empty
+ \else
+ \def\subentry{ #3}%
+ \fi
+ %
+ % First process the index entry with all font commands turned
+ % off to get the string to sort by.
+ {\indexnofonts \xdef\indexsorttmp{#2\subentry}}%
+ %
+ % Now the real index entry with the fonts.
+ \toks0 = {#2}%
+ %
+ % If third (subentry) arg is present, add it to the index
+ % string. And include a space.
+ \ifx\thirdarg\emptymacro \else
+ \toks0 = \expandafter{\the\toks0 \space #3}%
+ \fi
+ %
+ % Set up the complete index entry, with both the sort key
+ % and the original text, including any font commands. We write
+ % three arguments to \entry to the .?? file, texindex reduces to
+ % two when writing the .??s sorted result.
+ \edef\temp{%
+ \write\csname#1indfile\endcsname{%
+ \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}%
+ }%
+ %
+ % If a skip is the last thing on the list now, preserve it
+ % by backing up by \lastskip, doing the \write, then inserting
+ % the skip again. Otherwise, the whatsit generated by the
+ % \write will make \lastskip zero. The result is that sequences
+ % like this:
+ % @end defun
+ % @tindex whatever
+ % @defun ...
+ % will have extra space inserted, because the \medbreak in the
+ % start of the @defun won't see the skip inserted by the @end of
+ % the previous defun.
+ %
+ % But don't do any of this if we're not in vertical mode. We
+ % don't want to do a \vskip and prematurely end a paragraph.
+ %
+ % Avoid page breaks due to these extra skips, too.
+ %
+ \iflinks
+ \ifvmode
+ \skip0 = \lastskip
+ \ifdim\lastskip = 0pt \else \nobreak\vskip-\lastskip \fi
+ \fi
+ %
+ \temp % do the write
+ %
+ %
+ \ifvmode \ifdim\skip0 = 0pt \else \nobreak\vskip\skip0 \fi \fi
+ \fi
+ }%
+ }%
+ \penalty\count255
+ }%
+}
+
+% The index entry written in the file actually looks like
+% \entry {sortstring}{page}{topic}
+% or
+% \entry {sortstring}{page}{topic}{subtopic}
+% The texindex program reads in these files and writes files
+% containing these kinds of lines:
+% \initial {c}
+% before the first topic whose initial is c
+% \entry {topic}{pagelist}
+% for a topic that is used without subtopics
+% \primary {topic}
+% for the beginning of a topic that is used with subtopics
+% \secondary {subtopic}{pagelist}
+% for each subtopic.
+
+% Define the user-accessible indexing commands
+% @findex, @vindex, @kindex, @cindex.
+
+\def\findex {\fnindex}
+\def\kindex {\kyindex}
+\def\cindex {\cpindex}
+\def\vindex {\vrindex}
+\def\tindex {\tpindex}
+\def\pindex {\pgindex}
+
+\def\cindexsub {\begingroup\obeylines\cindexsub}
+{\obeylines %
+\gdef\cindexsub "#1" #2^^M{\endgroup %
+\dosubind{cp}{#2}{#1}}}
+
+% Define the macros used in formatting output of the sorted index material.
+
+% @printindex causes a particular index (the ??s file) to get printed.
+% It does not print any chapter heading (usually an @unnumbered).
+%
+\def\printindex{\parsearg\doprintindex}
+\def\doprintindex#1{\begingroup
+ \dobreak \chapheadingskip{10000}%
+ %
+ \smallfonts \rm
+ \tolerance = 9500
+ \indexbreaks
+ %
+ % See if the index file exists and is nonempty.
+ % Change catcode of @ here so that if the index file contains
+ % \initial {@}
+ % as its first line, TeX doesn't complain about mismatched braces
+ % (because it thinks @} is a control sequence).
+ \catcode`\@ = 11
+ \openin 1 \jobname.#1s
+ \ifeof 1
+ % \enddoublecolumns gets confused if there is no text in the index,
+ % and it loses the chapter title and the aux file entries for the
+ % index. The easiest way to prevent this problem is to make sure
+ % there is some text.
+ \putwordIndexNonexistent
+ \else
+ %
+ % If the index file exists but is empty, then \openin leaves \ifeof
+ % false. We have to make TeX try to read something from the file, so
+ % it can discover if there is anything in it.
+ \read 1 to \temp
+ \ifeof 1
+ \putwordIndexIsEmpty
+ \else
+ % Index files are almost Texinfo source, but we use \ as the escape
+ % character. It would be better to use @, but that's too big a change
+ % to make right now.
+ \def\indexbackslash{\rawbackslashxx}%
+ \catcode`\\ = 0
+ \escapechar = `\\
+ \begindoublecolumns
+ \input \jobname.#1s
+ \enddoublecolumns
+ \fi
+ \fi
+ \closein 1
+\endgroup}
+
+% These macros are used by the sorted index file itself.
+% Change them to control the appearance of the index.
+
+\def\initial#1{{%
+ % Some minor font changes for the special characters.
+ \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt
+ %
+ % Remove any glue we may have, we'll be inserting our own.
+ \removelastskip
+ %
+ % We like breaks before the index initials, so insert a bonus.
+ \penalty -300
+ %
+ % Typeset the initial. Making this add up to a whole number of
+ % baselineskips increases the chance of the dots lining up from column
+ % to column. It still won't often be perfect, because of the stretch
+ % we need before each entry, but it's better.
+ %
+ % No shrink because it confuses \balancecolumns.
+ \vskip 1.67\baselineskip plus .5\baselineskip
+ \leftline{\secbf #1}%
+ \vskip .33\baselineskip plus .1\baselineskip
+ %
+ % Do our best not to break after the initial.
+ \nobreak
+}}
+
+% This typesets a paragraph consisting of #1, dot leaders, and then #2
+% flush to the right margin. It is used for index and table of contents
+% entries. The paragraph is indented by \leftskip.
+%
+\def\entry#1#2{\begingroup
+ %
+ % Start a new paragraph if necessary, so our assignments below can't
+ % affect previous text.
+ \par
+ %
+ % Do not fill out the last line with white space.
+ \parfillskip = 0in
+ %
+ % No extra space above this paragraph.
+ \parskip = 0in
+ %
+ % Do not prefer a separate line ending with a hyphen to fewer lines.
+ \finalhyphendemerits = 0
+ %
+ % \hangindent is only relevant when the entry text and page number
+ % don't both fit on one line. In that case, bob suggests starting the
+ % dots pretty far over on the line. Unfortunately, a large
+ % indentation looks wrong when the entry text itself is broken across
+ % lines. So we use a small indentation and put up with long leaders.
+ %
+ % \hangafter is reset to 1 (which is the value we want) at the start
+ % of each paragraph, so we need not do anything with that.
+ \hangindent = 2em
+ %
+ % When the entry text needs to be broken, just fill out the first line
+ % with blank space.
+ \rightskip = 0pt plus1fil
+ %
+ % A bit of stretch before each entry for the benefit of balancing columns.
+ \vskip 0pt plus1pt
+ %
+ % Start a ``paragraph'' for the index entry so the line breaking
+ % parameters we've set above will have an effect.
+ \noindent
+ %
+ % Insert the text of the index entry. TeX will do line-breaking on it.
+ #1%
+ % The following is kludged to not output a line of dots in the index if
+ % there are no page numbers. The next person who breaks this will be
+ % cursed by a Unix daemon.
+ \def\tempa{{\rm }}%
+ \def\tempb{#2}%
+ \edef\tempc{\tempa}%
+ \edef\tempd{\tempb}%
+ \ifx\tempc\tempd\ \else%
+ %
+ % If we must, put the page number on a line of its own, and fill out
+ % this line with blank space. (The \hfil is overwhelmed with the
+ % fill leaders glue in \indexdotfill if the page number does fit.)
+ \hfil\penalty50
+ \null\nobreak\indexdotfill % Have leaders before the page number.
+ %
+ % The `\ ' here is removed by the implicit \unskip that TeX does as
+ % part of (the primitive) \par. Without it, a spurious underfull
+ % \hbox ensues.
+ \ifpdf
+ \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
+ \else
+ \ #2% The page number ends the paragraph.
+ \fi
+ \fi%
+ \par
+\endgroup}
+
+% Like \dotfill except takes at least 1 em.
+\def\indexdotfill{\cleaders
+ \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill}
+
+\def\primary #1{\line{#1\hfil}}
+
+\newskip\secondaryindent \secondaryindent=0.5cm
+
+\def\secondary #1#2{
+{\parfillskip=0in \parskip=0in
+\hangindent =1in \hangafter=1
+\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par
+}}
+
+% Define two-column mode, which we use to typeset indexes.
+% Adapted from the TeXbook, page 416, which is to say,
+% the manmac.tex format used to print the TeXbook itself.
+\catcode`\@=11
+
+\newbox\partialpage
+\newdimen\doublecolumnhsize
+
+\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
+ % Grab any single-column material above us.
+ \output = {%
+ %
+ % Here is a possibility not foreseen in manmac: if we accumulate a
+ % whole lot of material, we might end up calling this \output
+ % routine twice in a row (see the doublecol-lose test, which is
+ % essentially a couple of indexes with @setchapternewpage off). In
+ % that case we just ship out what is in \partialpage with the normal
+ % output routine. Generally, \partialpage will be empty when this
+ % runs and this will be a no-op. See the indexspread.tex test case.
+ \ifvoid\partialpage \else
+ \onepageout{\pagecontents\partialpage}%
+ \fi
+ %
+ \global\setbox\partialpage = \vbox{%
+ % Unvbox the main output page.
+ \unvbox\PAGE
+ \kern-\topskip \kern\baselineskip
+ }%
+ }%
+ \eject % run that output routine to set \partialpage
+ %
+ % Use the double-column output routine for subsequent pages.
+ \output = {\doublecolumnout}%
+ %
+ % Change the page size parameters. We could do this once outside this
+ % routine, in each of @smallbook, @afourpaper, and the default 8.5x11
+ % format, but then we repeat the same computation. Repeating a couple
+ % of assignments once per index is clearly meaningless for the
+ % execution time, so we may as well do it in one place.
+ %
+ % First we halve the line length, less a little for the gutter between
+ % the columns. We compute the gutter based on the line length, so it
+ % changes automatically with the paper format. The magic constant
+ % below is chosen so that the gutter has the same value (well, +-<1pt)
+ % as it did when we hard-coded it.
+ %
+ % We put the result in a separate register, \doublecolumhsize, so we
+ % can restore it in \pagesofar, after \hsize itself has (potentially)
+ % been clobbered.
+ %
+ \doublecolumnhsize = \hsize
+ \advance\doublecolumnhsize by -.04154\hsize
+ \divide\doublecolumnhsize by 2
+ \hsize = \doublecolumnhsize
+ %
+ % Double the \vsize as well. (We don't need a separate register here,
+ % since nobody clobbers \vsize.)
+ \advance\vsize by -\ht\partialpage
+ \vsize = 2\vsize
+}
+
+% The double-column output routine for all double-column pages except
+% the last.
+%
+\def\doublecolumnout{%
+ \splittopskip=\topskip \splitmaxdepth=\maxdepth
+ % Get the available space for the double columns -- the normal
+ % (undoubled) page height minus any material left over from the
+ % previous page.
+ \dimen@ = \vsize
+ \divide\dimen@ by 2
+ %
+ % box0 will be the left-hand column, box2 the right.
+ \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
+ \onepageout\pagesofar
+ \unvbox255
+ \penalty\outputpenalty
+}
+\def\pagesofar{%
+ % Re-output the contents of the output page -- any previous material,
+ % followed by the two boxes we just split, in box0 and box2.
+ \unvbox\partialpage
+ %
+ \hsize = \doublecolumnhsize
+ \wd0=\hsize \wd2=\hsize
+ \hbox to\pagewidth{\box0\hfil\box2}%
+}
+\def\enddoublecolumns{%
+ \output = {%
+ % Split the last of the double-column material. Leave it on the
+ % current page, no automatic page break.
+ \balancecolumns
+ %
+ % If we end up splitting too much material for the current page,
+ % though, there will be another page break right after this \output
+ % invocation ends. Having called \balancecolumns once, we do not
+ % want to call it again. Therefore, reset \output to its normal
+ % definition right away. (We hope \balancecolumns will never be
+ % called on to balance too much material, but if it is, this makes
+ % the output somewhat more palatable.)
+ \global\output = {\onepageout{\pagecontents\PAGE}}%
+ }%
+ \eject
+ \endgroup % started in \begindoublecolumns
+ %
+ % \pagegoal was set to the doubled \vsize above, since we restarted
+ % the current page. We're now back to normal single-column
+ % typesetting, so reset \pagegoal to the normal \vsize (after the
+ % \endgroup where \vsize got restored).
+ \pagegoal = \vsize
+}
+\def\balancecolumns{%
+ % Called at the end of the double column material.
+ \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
+ \dimen@ = \ht0
+ \advance\dimen@ by \topskip
+ \advance\dimen@ by-\baselineskip
+ \divide\dimen@ by 2 % target to split to
+ %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}%
+ \splittopskip = \topskip
+ % Loop until we get a decent breakpoint.
+ {%
+ \vbadness = 10000
+ \loop
+ \global\setbox3 = \copy0
+ \global\setbox1 = \vsplit3 to \dimen@
+ \ifdim\ht3>\dimen@
+ \global\advance\dimen@ by 1pt
+ \repeat
+ }%
+ %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}%
+ \setbox0=\vbox to\dimen@{\unvbox1}%
+ \setbox2=\vbox to\dimen@{\unvbox3}%
+ %
+ \pagesofar
+}
+\catcode`\@ = \other
+
+
+\message{sectioning,}
+% Chapters, sections, etc.
+
+\newcount\chapno
+\newcount\secno \secno=0
+\newcount\subsecno \subsecno=0
+\newcount\subsubsecno \subsubsecno=0
+
+% This counter is funny since it counts through charcodes of letters A, B, ...
+\newcount\appendixno \appendixno = `\@
+% \def\appendixletter{\char\the\appendixno}
+% We do the following for the sake of pdftex, which needs the actual
+% letter in the expansion, not just typeset.
+\def\appendixletter{%
+ \ifnum\appendixno=`A A%
+ \else\ifnum\appendixno=`B B%
+ \else\ifnum\appendixno=`C C%
+ \else\ifnum\appendixno=`D D%
+ \else\ifnum\appendixno=`E E%
+ \else\ifnum\appendixno=`F F%
+ \else\ifnum\appendixno=`G G%
+ \else\ifnum\appendixno=`H H%
+ \else\ifnum\appendixno=`I I%
+ \else\ifnum\appendixno=`J J%
+ \else\ifnum\appendixno=`K K%
+ \else\ifnum\appendixno=`L L%
+ \else\ifnum\appendixno=`M M%
+ \else\ifnum\appendixno=`N N%
+ \else\ifnum\appendixno=`O O%
+ \else\ifnum\appendixno=`P P%
+ \else\ifnum\appendixno=`Q Q%
+ \else\ifnum\appendixno=`R R%
+ \else\ifnum\appendixno=`S S%
+ \else\ifnum\appendixno=`T T%
+ \else\ifnum\appendixno=`U U%
+ \else\ifnum\appendixno=`V V%
+ \else\ifnum\appendixno=`W W%
+ \else\ifnum\appendixno=`X X%
+ \else\ifnum\appendixno=`Y Y%
+ \else\ifnum\appendixno=`Z Z%
+ % The \the is necessary, despite appearances, because \appendixletter is
+ % expanded while writing the .toc file. \char\appendixno is not
+ % expandable, thus it is written literally, thus all appendixes come out
+ % with the same letter (or @) in the toc without it.
+ \else\char\the\appendixno
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
+
+% Each @chapter defines this as the name of the chapter.
+% page headings and footings can use it. @section does likewise.
+\def\thischapter{}
+\def\thissection{}
+
+\newcount\absseclevel % used to calculate proper heading level
+\newcount\secbase\secbase=0 % @raise/lowersections modify this count
+
+% @raisesections: treat @section as chapter, @subsection as section, etc.
+\def\raisesections{\global\advance\secbase by -1}
+\let\up=\raisesections % original BFox name
+
+% @lowersections: treat @chapter as section, @section as subsection, etc.
+\def\lowersections{\global\advance\secbase by 1}
+\let\down=\lowersections % original BFox name
+
+% Choose a numbered-heading macro
+% #1 is heading level if unmodified by @raisesections or @lowersections
+% #2 is text for heading
+\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1
+\ifcase\absseclevel
+ \chapterzzz{#2}
+\or
+ \seczzz{#2}
+\or
+ \numberedsubseczzz{#2}
+\or
+ \numberedsubsubseczzz{#2}
+\else
+ \ifnum \absseclevel<0
+ \chapterzzz{#2}
+ \else
+ \numberedsubsubseczzz{#2}
+ \fi
+\fi
+}
+
+% like \numhead, but chooses appendix heading levels
+\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1
+\ifcase\absseclevel
+ \appendixzzz{#2}
+\or
+ \appendixsectionzzz{#2}
+\or
+ \appendixsubseczzz{#2}
+\or
+ \appendixsubsubseczzz{#2}
+\else
+ \ifnum \absseclevel<0
+ \appendixzzz{#2}
+ \else
+ \appendixsubsubseczzz{#2}
+ \fi
+\fi
+}
+
+% like \numhead, but chooses numberless heading levels
+\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1
+\ifcase\absseclevel
+ \unnumberedzzz{#2}
+\or
+ \unnumberedseczzz{#2}
+\or
+ \unnumberedsubseczzz{#2}
+\or
+ \unnumberedsubsubseczzz{#2}
+\else
+ \ifnum \absseclevel<0
+ \unnumberedzzz{#2}
+ \else
+ \unnumberedsubsubseczzz{#2}
+ \fi
+\fi
+}
+
+% @chapter, @appendix, @unnumbered.
+\def\thischaptername{No Chapter Title}
+\outer\def\chapter{\parsearg\chapteryyy}
+\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz
+\def\chapterzzz #1{%
+\secno=0 \subsecno=0 \subsubsecno=0
+\global\advance \chapno by 1 \message{\putwordChapter\space \the\chapno}%
+\chapmacro {#1}{\the\chapno}%
+\gdef\thissection{#1}%
+\gdef\thischaptername{#1}%
+% We don't substitute the actual chapter name into \thischapter
+% because we don't want its macros evaluated now.
+\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash chapentry{\the\toks0}%
+ {\the\chapno}}}%
+\temp
+\donoderef
+\global\let\section = \numberedsec
+\global\let\subsection = \numberedsubsec
+\global\let\subsubsection = \numberedsubsubsec
+}
+
+\outer\def\appendix{\parsearg\appendixyyy}
+\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz
+\def\appendixzzz #1{%
+\secno=0 \subsecno=0 \subsubsecno=0
+\global\advance \appendixno by 1
+\message{\putwordAppendix\space \appendixletter}%
+\chapmacro {#1}{\putwordAppendix{} \appendixletter}%
+\gdef\thissection{#1}%
+\gdef\thischaptername{#1}%
+\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash chapentry{\the\toks0}%
+ {\putwordAppendix{} \appendixletter}}}%
+\temp
+\appendixnoderef
+\global\let\section = \appendixsec
+\global\let\subsection = \appendixsubsec
+\global\let\subsubsection = \appendixsubsubsec
+}
+
+% @centerchap is like @unnumbered, but the heading is centered.
+\outer\def\centerchap{\parsearg\centerchapyyy}
+\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}}
+
+% @top is like @unnumbered.
+\outer\def\top{\parsearg\unnumberedyyy}
+
+\outer\def\unnumbered{\parsearg\unnumberedyyy}
+\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz
+\def\unnumberedzzz #1{%
+\secno=0 \subsecno=0 \subsubsecno=0
+%
+% This used to be simply \message{#1}, but TeX fully expands the
+% argument to \message. Therefore, if #1 contained @-commands, TeX
+% expanded them. For example, in `@unnumbered The @cite{Book}', TeX
+% expanded @cite (which turns out to cause errors because \cite is meant
+% to be executed, not expanded).
+%
+% Anyway, we don't want the fully-expanded definition of @cite to appear
+% as a result of the \message, we just want `@cite' itself. We use
+% \the<toks register> to achieve this: TeX expands \the<toks> only once,
+% simply yielding the contents of <toks register>. (We also do this for
+% the toc entries.)
+\toks0 = {#1}\message{(\the\toks0)}%
+%
+\unnumbchapmacro {#1}%
+\gdef\thischapter{#1}\gdef\thissection{#1}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash unnumbchapentry{\the\toks0}}}%
+\temp
+\unnumbnoderef
+\global\let\section = \unnumberedsec
+\global\let\subsection = \unnumberedsubsec
+\global\let\subsubsection = \unnumberedsubsubsec
+}
+
+% Sections.
+\outer\def\numberedsec{\parsearg\secyyy}
+\def\secyyy #1{\numhead1{#1}} % normally calls seczzz
+\def\seczzz #1{%
+\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 %
+\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash secentry{\the\toks0}%
+ {\the\chapno}{\the\secno}}}%
+\temp
+\donoderef
+\nobreak
+}
+
+\outer\def\appendixsection{\parsearg\appendixsecyyy}
+\outer\def\appendixsec{\parsearg\appendixsecyyy}
+\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz
+\def\appendixsectionzzz #1{%
+\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 %
+\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash secentry{\the\toks0}%
+ {\appendixletter}{\the\secno}}}%
+\temp
+\appendixnoderef
+\nobreak
+}
+
+\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy}
+\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz
+\def\unnumberedseczzz #1{%
+\plainsecheading {#1}\gdef\thissection{#1}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry{\the\toks0}}}%
+\temp
+\unnumbnoderef
+\nobreak
+}
+
+% Subsections.
+\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy}
+\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz
+\def\numberedsubseczzz #1{%
+\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 %
+\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash subsecentry{\the\toks0}%
+ {\the\chapno}{\the\secno}{\the\subsecno}}}%
+\temp
+\donoderef
+\nobreak
+}
+
+\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy}
+\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz
+\def\appendixsubseczzz #1{%
+\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 %
+\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash subsecentry{\the\toks0}%
+ {\appendixletter}{\the\secno}{\the\subsecno}}}%
+\temp
+\appendixnoderef
+\nobreak
+}
+
+\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy}
+\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz
+\def\unnumberedsubseczzz #1{%
+\plainsubsecheading {#1}\gdef\thissection{#1}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsecentry%
+ {\the\toks0}}}%
+\temp
+\unnumbnoderef
+\nobreak
+}
+
+% Subsubsections.
+\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy}
+\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz
+\def\numberedsubsubseczzz #1{%
+\gdef\thissection{#1}\global\advance \subsubsecno by 1 %
+\subsubsecheading {#1}
+ {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash subsubsecentry{\the\toks0}%
+ {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}%
+\temp
+\donoderef
+\nobreak
+}
+
+\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy}
+\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz
+\def\appendixsubsubseczzz #1{%
+\gdef\thissection{#1}\global\advance \subsubsecno by 1 %
+\subsubsecheading {#1}
+ {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash subsubsecentry{\the\toks0}%
+ {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}%
+\temp
+\appendixnoderef
+\nobreak
+}
+
+\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy}
+\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz
+\def\unnumberedsubsubseczzz #1{%
+\plainsubsubsecheading {#1}\gdef\thissection{#1}%
+\toks0 = {#1}%
+\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsubsecentry%
+ {\the\toks0}}}%
+\temp
+\unnumbnoderef
+\nobreak
+}
+
+% These are variants which are not "outer", so they can appear in @ifinfo.
+% Actually, they should now be obsolete; ordinary section commands should work.
+\def\infotop{\parsearg\unnumberedzzz}
+\def\infounnumbered{\parsearg\unnumberedzzz}
+\def\infounnumberedsec{\parsearg\unnumberedseczzz}
+\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz}
+\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz}
+
+\def\infoappendix{\parsearg\appendixzzz}
+\def\infoappendixsec{\parsearg\appendixseczzz}
+\def\infoappendixsubsec{\parsearg\appendixsubseczzz}
+\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz}
+
+\def\infochapter{\parsearg\chapterzzz}
+\def\infosection{\parsearg\sectionzzz}
+\def\infosubsection{\parsearg\subsectionzzz}
+\def\infosubsubsection{\parsearg\subsubsectionzzz}
+
+% These macros control what the section commands do, according
+% to what kind of chapter we are in (ordinary, appendix, or unnumbered).
+% Define them by default for a numbered chapter.
+\global\let\section = \numberedsec
+\global\let\subsection = \numberedsubsec
+\global\let\subsubsection = \numberedsubsubsec
+
+% Define @majorheading, @heading and @subheading
+
+% NOTE on use of \vbox for chapter headings, section headings, and such:
+% 1) We use \vbox rather than the earlier \line to permit
+% overlong headings to fold.
+% 2) \hyphenpenalty is set to 10000 because hyphenation in a
+% heading is obnoxious; this forbids it.
+% 3) Likewise, headings look best if no \parindent is used, and
+% if justification is not attempted. Hence \raggedright.
+
+
+\def\majorheading{\parsearg\majorheadingzzz}
+\def\majorheadingzzz #1{%
+{\advance\chapheadingskip by 10pt \chapbreak }%
+{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt\raggedright
+ \rm #1\hfill}}\bigskip \par\penalty 200}
+
+\def\chapheading{\parsearg\chapheadingzzz}
+\def\chapheadingzzz #1{\chapbreak %
+{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt\raggedright
+ \rm #1\hfill}}\bigskip \par\penalty 200}
+
+% @heading, @subheading, @subsubheading.
+\def\heading{\parsearg\plainsecheading}
+\def\subheading{\parsearg\plainsubsecheading}
+\def\subsubheading{\parsearg\plainsubsubsecheading}
+
+% These macros generate a chapter, section, etc. heading only
+% (including whitespace, linebreaking, etc. around it),
+% given all the information in convenient, parsed form.
+
+%%% Args are the skip and penalty (usually negative)
+\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}
+
+\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
+
+%%% Define plain chapter starts, and page on/off switching for it
+% Parameter controlling skip before chapter headings (if needed)
+
+\newskip\chapheadingskip
+
+\def\chapbreak{\dobreak \chapheadingskip {-4000}}
+\def\chappager{\par\vfill\supereject}
+\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi}
+
+\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}
+
+\def\CHAPPAGoff{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chapbreak
+\global\let\pagealignmacro=\chappager}
+
+\def\CHAPPAGon{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chappager
+\global\let\pagealignmacro=\chappager
+\global\def\HEADINGSon{\HEADINGSsingle}}
+
+\def\CHAPPAGodd{
+\global\let\contentsalignmacro = \chapoddpage
+\global\let\pchapsepmacro=\chapoddpage
+\global\let\pagealignmacro=\chapoddpage
+\global\def\HEADINGSon{\HEADINGSdouble}}
+
+\CHAPPAGon
+
+\def\CHAPFplain{
+\global\let\chapmacro=\chfplain
+\global\let\unnumbchapmacro=\unnchfplain
+\global\let\centerchapmacro=\centerchfplain}
+
+% Plain chapter opening.
+% #1 is the text, #2 the chapter number or empty if unnumbered.
+\def\chfplain#1#2{%
+ \pchapsepmacro
+ {%
+ \chapfonts \rm
+ \def\chapnum{#2}%
+ \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}%
+ \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
+ \hangindent = \wd0 \centerparametersmaybe
+ \unhbox0 #1\par}%
+ }%
+ \nobreak\bigskip % no page break after a chapter title
+ \nobreak
+}
+
+% Plain opening for unnumbered.
+\def\unnchfplain#1{\chfplain{#1}{}}
+
+% @centerchap -- centered and unnumbered.
+\let\centerparametersmaybe = \relax
+\def\centerchfplain#1{{%
+ \def\centerparametersmaybe{%
+ \advance\rightskip by 3\rightskip
+ \leftskip = \rightskip
+ \parfillskip = 0pt
+ }%
+ \chfplain{#1}{}%
+}}
+
+\CHAPFplain % The default
+
+\def\unnchfopen #1{%
+\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt\raggedright
+ \rm #1\hfill}}\bigskip \par\nobreak
+}
+
+\def\chfopen #1#2{\chapoddpage {\chapfonts
+\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
+\par\penalty 5000 %
+}
+
+\def\centerchfopen #1{%
+\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt
+ \hfill {\rm #1}\hfill}}\bigskip \par\nobreak
+}
+
+\def\CHAPFopen{
+\global\let\chapmacro=\chfopen
+\global\let\unnumbchapmacro=\unnchfopen
+\global\let\centerchapmacro=\centerchfopen}
+
+
+% Section titles.
+\newskip\secheadingskip
+\def\secheadingbreak{\dobreak \secheadingskip {-1000}}
+\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}}
+\def\plainsecheading#1{\sectionheading{sec}{}{#1}}
+
+% Subsection titles.
+\newskip \subsecheadingskip
+\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}}
+\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}}
+\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}}
+
+% Subsubsection titles.
+\let\subsubsecheadingskip = \subsecheadingskip
+\let\subsubsecheadingbreak = \subsecheadingbreak
+\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}}
+\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}}
+
+
+% Print any size section title.
+%
+% #1 is the section type (sec/subsec/subsubsec), #2 is the section
+% number (maybe empty), #3 the text.
+\def\sectionheading#1#2#3{%
+ {%
+ \expandafter\advance\csname #1headingskip\endcsname by \parskip
+ \csname #1headingbreak\endcsname
+ }%
+ {%
+ % Switch to the right set of fonts.
+ \csname #1fonts\endcsname \rm
+ %
+ % Only insert the separating space if we have a section number.
+ \def\secnum{#2}%
+ \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}%
+ %
+ \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
+ \hangindent = \wd0 % zero if no section number
+ \unhbox0 #3}%
+ }%
+ \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak
+}
+
+
+\message{toc,}
+% Table of contents.
+\newwrite\tocfile
+
+% Write an entry to the toc file, opening it if necessary.
+% Called from @chapter, etc. We supply {\folio} at the end of the
+% argument, which will end up as the last argument to the \...entry macro.
+%
+% We open the .toc file here instead of at @setfilename or any other
+% given time so that @contents can be put in the document anywhere.
+%
+\newif\iftocfileopened
+\def\writetocentry#1{%
+ \iftocfileopened\else
+ \immediate\openout\tocfile = \jobname.toc
+ \global\tocfileopenedtrue
+ \fi
+ \iflinks \write\tocfile{#1{\folio}}\fi
+}
+
+\newskip\contentsrightmargin \contentsrightmargin=1in
+\newcount\savepageno
+\newcount\lastnegativepageno \lastnegativepageno = -1
+
+% Finish up the main text and prepare to read what we've written
+% to \tocfile.
+%
+\def\startcontents#1{%
+ % If @setchapternewpage on, and @headings double, the contents should
+ % start on an odd page, unlike chapters. Thus, we maintain
+ % \contentsalignmacro in parallel with \pagealignmacro.
+ % From: Torbjorn Granlund <tege@matematik.su.se>
+ \contentsalignmacro
+ \immediate\closeout\tocfile
+ %
+ % Don't need to put `Contents' or `Short Contents' in the headline.
+ % It is abundantly clear what they are.
+ \unnumbchapmacro{#1}\def\thischapter{}%
+ \savepageno = \pageno
+ \begingroup % Set up to handle contents files properly.
+ \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11
+ % We can't do this, because then an actual ^ in a section
+ % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97.
+ %\catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi
+ \raggedbottom % Worry more about breakpoints than the bottom.
+ \advance\hsize by -\contentsrightmargin % Don't use the full line length.
+ %
+ % Roman numerals for page numbers.
+ \ifnum \pageno>0 \pageno = \lastnegativepageno \fi
+}
+
+
+% Normal (long) toc.
+\def\contents{%
+ \startcontents{\putwordTOC}%
+ \openin 1 \jobname.toc
+ \ifeof 1 \else
+ \closein 1
+ \input \jobname.toc
+ \fi
+ \vfill \eject
+ \contentsalignmacro % in case @setchapternewpage odd is in effect
+ \pdfmakeoutlines
+ \endgroup
+ \lastnegativepageno = \pageno
+ \pageno = \savepageno
+}
+
+% And just the chapters.
+\def\summarycontents{%
+ \startcontents{\putwordShortTOC}%
+ %
+ \let\chapentry = \shortchapentry
+ \let\unnumbchapentry = \shortunnumberedentry
+ % We want a true roman here for the page numbers.
+ \secfonts
+ \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl
+ \rm
+ \hyphenpenalty = 10000
+ \advance\baselineskip by 1pt % Open it up a little.
+ \def\secentry ##1##2##3##4{}
+ \def\unnumbsecentry ##1##2{}
+ \def\subsecentry ##1##2##3##4##5{}
+ \def\unnumbsubsecentry ##1##2{}
+ \def\subsubsecentry ##1##2##3##4##5##6{}
+ \def\unnumbsubsubsecentry ##1##2{}
+ \openin 1 \jobname.toc
+ \ifeof 1 \else
+ \closein 1
+ \input \jobname.toc
+ \fi
+ \vfill \eject
+ \contentsalignmacro % in case @setchapternewpage odd is in effect
+ \endgroup
+ \lastnegativepageno = \pageno
+ \pageno = \savepageno
+}
+\let\shortcontents = \summarycontents
+
+\ifpdf
+ \pdfcatalog{/PageMode /UseOutlines}%
+\fi
+
+% These macros generate individual entries in the table of contents.
+% The first argument is the chapter or section name.
+% The last argument is the page number.
+% The arguments in between are the chapter number, section number, ...
+
+% Chapter-level things, for both the long and short contents.
+\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}}
+
+% See comments in \dochapentry re vbox and related settings
+\def\shortchapentry#1#2#3{%
+ \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#3\egroup}%
+}
+
+% Typeset the label for a chapter or appendix for the short contents.
+% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter.
+% We could simplify the code here by writing out an \appendixentry
+% command in the toc file for appendices, instead of using \chapentry
+% for both, but it doesn't seem worth it.
+%
+\newdimen\shortappendixwidth
+%
+\def\shortchaplabel#1{%
+ % Compute width of word "Appendix", may change with language.
+ \setbox0 = \hbox{\shortcontrm \putwordAppendix}%
+ \shortappendixwidth = \wd0
+ %
+ % We typeset #1 in a box of constant width, regardless of the text of
+ % #1, so the chapter titles will come out aligned.
+ \setbox0 = \hbox{#1}%
+ \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi
+ %
+ % This space should be plenty, since a single number is .5em, and the
+ % widest letter (M) is 1em, at least in the Computer Modern fonts.
+ % (This space doesn't include the extra space that gets added after
+ % the label; that gets put in by \shortchapentry above.)
+ \advance\dimen0 by 1.1em
+ \hbox to \dimen0{#1\hfil}%
+}
+
+\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}}
+\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno\bgroup#2\egroup}}
+
+% Sections.
+\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}}
+\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}}
+
+% Subsections.
+\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}}
+\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}}
+
+% And subsubsections.
+\def\subsubsecentry#1#2#3#4#5#6{%
+ \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}}
+\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}}
+
+% This parameter controls the indentation of the various levels.
+\newdimen\tocindent \tocindent = 3pc
+
+% Now for the actual typesetting. In all these, #1 is the text and #2 is the
+% page number.
+%
+% If the toc has to be broken over pages, we want it to be at chapters
+% if at all possible; hence the \penalty.
+\def\dochapentry#1#2{%
+ \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip
+ \begingroup
+ \chapentryfonts
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+ \endgroup
+ \nobreak\vskip .25\baselineskip plus.1\baselineskip
+}
+
+\def\dosecentry#1#2{\begingroup
+ \secentryfonts \leftskip=\tocindent
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsecentry#1#2{\begingroup
+ \subsecentryfonts \leftskip=2\tocindent
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsubsecentry#1#2{\begingroup
+ \subsubsecentryfonts \leftskip=3\tocindent
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+% Final typesetting of a toc entry; we use the same \entry macro as for
+% the index entries, but we want to suppress hyphenation here. (We
+% can't do that in the \entry macro, since index entries might consist
+% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.)
+\def\tocentry#1#2{\begingroup
+ \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks
+ % Do not use \turnoffactive in these arguments. Since the toc is
+ % typeset in cmr, so characters such as _ would come out wrong; we
+ % have to do the usual translation tricks.
+ \entry{#1}{#2}%
+\endgroup}
+
+% Space between chapter (or whatever) number and the title.
+\def\labelspace{\hskip1em \relax}
+
+\def\dopageno#1{{\rm #1}}
+\def\doshortpageno#1{{\rm #1}}
+
+\def\chapentryfonts{\secfonts \rm}
+\def\secentryfonts{\textfonts}
+\let\subsecentryfonts = \textfonts
+\let\subsubsecentryfonts = \textfonts
+
+
+\message{environments,}
+% @foo ... @end foo.
+
+% Since these characters are used in examples, it should be an even number of
+% \tt widths. Each \tt character is 1en, so two makes it 1em.
+% Furthermore, these definitions must come after we define our fonts.
+\newbox\dblarrowbox \newbox\longdblarrowbox
+\newbox\pushcharbox \newbox\bullbox
+\newbox\equivbox \newbox\errorbox
+
+%{\tentt
+%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil}
+%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil}
+%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil}
+%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil}
+% Adapted from the manmac format (p.420 of TeXbook)
+%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex
+% depth .1ex\hfil}
+%}
+
+% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
+\def\point{$\star$}
+\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
+\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}}
+\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
+\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}
+
+% Adapted from the TeXbook's \boxit.
+{\tentt \global\dimen0 = 3em}% Width of the box.
+\dimen2 = .55pt % Thickness of rules
+% The text. (`r' is open on the right, `e' somewhat less so on the left.)
+\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt}
+
+\global\setbox\errorbox=\hbox to \dimen0{\hfil
+ \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
+ \advance\hsize by -2\dimen2 % Rules.
+ \vbox{
+ \hrule height\dimen2
+ \hbox{\vrule width\dimen2 \kern3pt % Space to left of text.
+ \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
+ \kern3pt\vrule width\dimen2}% Space to right.
+ \hrule height\dimen2}
+ \hfil}
+
+% The @error{} command.
+\def\error{\leavevmode\lower.7ex\copy\errorbox}
+
+% @tex ... @end tex escapes into raw Tex temporarily.
+% One exception: @ is still an escape character, so that @end tex works.
+% But \@ or @@ will get a plain tex @ character.
+
+\def\tex{\begingroup
+ \catcode `\\=0 \catcode `\{=1 \catcode `\}=2
+ \catcode `\$=3 \catcode `\&=4 \catcode `\#=6
+ \catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie
+ \catcode `\%=14
+ \catcode 43=12 % plus
+ \catcode`\"=12
+ \catcode`\==12
+ \catcode`\|=12
+ \catcode`\<=12
+ \catcode`\>=12
+ \escapechar=`\\
+ %
+ \let\b=\ptexb
+ \let\bullet=\ptexbullet
+ \let\c=\ptexc
+ \let\,=\ptexcomma
+ \let\.=\ptexdot
+ \let\dots=\ptexdots
+ \let\equiv=\ptexequiv
+ \let\!=\ptexexclam
+ \let\i=\ptexi
+ \let\{=\ptexlbrace
+ \let\+=\tabalign
+ \let\}=\ptexrbrace
+ \let\*=\ptexstar
+ \let\t=\ptext
+ %
+ \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
+ \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
+ \def\@{@}%
+\let\Etex=\endgroup}
+
+% Define @lisp ... @endlisp.
+% @lisp does a \begingroup so it can rebind things,
+% including the definition of @endlisp (which normally is erroneous).
+
+% Amount to narrow the margins by for @lisp.
+\newskip\lispnarrowing \lispnarrowing=0.4in
+
+% This is the definition that ^^M gets inside @lisp, @example, and other
+% such environments. \null is better than a space, since it doesn't
+% have any width.
+\def\lisppar{\null\endgraf}
+
+% Make each space character in the input produce a normal interword
+% space in the output. Don't allow a line break at this space, as this
+% is used only in environments like @example, where each line of input
+% should produce a line of output anyway.
+%
+{\obeyspaces %
+\gdef\sepspaces{\obeyspaces\let =\tie}}
+
+% Define \obeyedspace to be our active space, whatever it is. This is
+% for use in \parsearg.
+{\sepspaces%
+\global\let\obeyedspace= }
+
+% This space is always present above and below environments.
+\newskip\envskipamount \envskipamount = 0pt
+
+% Make spacing and below environment symmetrical. We use \parskip here
+% to help in doing that, since in @example-like environments \parskip
+% is reset to zero; thus the \afterenvbreak inserts no space -- but the
+% start of the next paragraph will insert \parskip
+%
+\def\aboveenvbreak{{\advance\envskipamount by \parskip
+\endgraf \ifdim\lastskip<\envskipamount
+\removelastskip \penalty-50 \vskip\envskipamount \fi}}
+
+\let\afterenvbreak = \aboveenvbreak
+
+% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins.
+\let\nonarrowing=\relax
+
+% @cartouche ... @end cartouche: draw rectangle w/rounded corners around
+% environment contents.
+\font\circle=lcircle10
+\newdimen\circthick
+\newdimen\cartouter\newdimen\cartinner
+\newskip\normbskip\newskip\normpskip\newskip\normlskip
+\circthick=\fontdimen8\circle
+%
+\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth
+\def\ctr{{\hskip 6pt\circle\char'010}}
+\def\cbl{{\circle\char'012\hskip -6pt}}
+\def\cbr{{\hskip 6pt\circle\char'011}}
+\def\carttop{\hbox to \cartouter{\hskip\lskip
+ \ctl\leaders\hrule height\circthick\hfil\ctr
+ \hskip\rskip}}
+\def\cartbot{\hbox to \cartouter{\hskip\lskip
+ \cbl\leaders\hrule height\circthick\hfil\cbr
+ \hskip\rskip}}
+%
+\newskip\lskip\newskip\rskip
+
+\long\def\cartouche{%
+\begingroup
+ \lskip=\leftskip \rskip=\rightskip
+ \leftskip=0pt\rightskip=0pt %we want these *outside*.
+ \cartinner=\hsize \advance\cartinner by-\lskip
+ \advance\cartinner by-\rskip
+ \cartouter=\hsize
+ \advance\cartouter by 18.4pt % allow for 3pt kerns on either
+% side, and for 6pt waste from
+% each corner char, and rule thickness
+ \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip
+ % Flag to tell @lisp, etc., not to narrow margin.
+ \let\nonarrowing=\comment
+ \vbox\bgroup
+ \baselineskip=0pt\parskip=0pt\lineskip=0pt
+ \carttop
+ \hbox\bgroup
+ \hskip\lskip
+ \vrule\kern3pt
+ \vbox\bgroup
+ \hsize=\cartinner
+ \kern3pt
+ \begingroup
+ \baselineskip=\normbskip
+ \lineskip=\normlskip
+ \parskip=\normpskip
+ \vskip -\parskip
+\def\Ecartouche{%
+ \endgroup
+ \kern3pt
+ \egroup
+ \kern3pt\vrule
+ \hskip\rskip
+ \egroup
+ \cartbot
+ \egroup
+\endgroup
+}}
+
+
+% This macro is called at the beginning of all the @example variants,
+% inside a group.
+\def\nonfillstart{%
+ \aboveenvbreak
+ \inENV % This group ends at the end of the body
+ \hfuzz = 12pt % Don't be fussy
+ \sepspaces % Make spaces be word-separators rather than space tokens.
+ \singlespace
+ \let\par = \lisppar % don't ignore blank lines
+ \obeylines % each line of input is a line of output
+ \parskip = 0pt
+ \parindent = 0pt
+ \emergencystretch = 0pt % don't try to avoid overfull boxes
+ % @cartouche defines \nonarrowing to inhibit narrowing
+ % at next level down.
+ \ifx\nonarrowing\relax
+ \advance \leftskip by \lispnarrowing
+ \exdentamount=\lispnarrowing
+ \let\exdent=\nofillexdent
+ \let\nonarrowing=\relax
+ \fi
+}
+
+% Define the \E... control sequence only if we are inside the particular
+% environment, so the error checking in \end will work.
+%
+% To end an @example-like environment, we first end the paragraph (via
+% \afterenvbreak's vertical glue), and then the group. That way we keep
+% the zero \parskip that the environments set -- \parskip glue will be
+% inserted at the beginning of the next paragraph in the document, after
+% the environment.
+%
+\def\nonfillfinish{\afterenvbreak\endgroup}
+
+% @lisp: indented, narrowed, typewriter font.
+\def\lisp{\begingroup
+ \nonfillstart
+ \let\Elisp = \nonfillfinish
+ \tt
+ \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
+ \gobble % eat return
+}
+
+% @example: Same as @lisp.
+\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp}
+
+% @small... is usually equivalent to the non-small (@smallbook
+% redefines). We must call \example (or whatever) last in the
+% definition, since it reads the return following the @example (or
+% whatever) command.
+%
+% This actually allows (for example) @end display inside an
+% @smalldisplay. Too bad, but makeinfo will catch the error anyway.
+%
+\def\smalldisplay{\begingroup\def\Esmalldisplay{\nonfillfinish\endgroup}\display}
+\def\smallexample{\begingroup\def\Esmallexample{\nonfillfinish\endgroup}\lisp}
+\def\smallformat{\begingroup\def\Esmallformat{\nonfillfinish\endgroup}\format}
+\def\smalllisp{\begingroup\def\Esmalllisp{\nonfillfinish\endgroup}\lisp}
+
+% Real @smallexample and @smalllisp (when @smallbook): use smaller fonts.
+% Originally contributed by Pavel@xerox.
+\def\smalllispx{\begingroup
+ \def\Esmalllisp{\nonfillfinish\endgroup}%
+ \def\Esmallexample{\nonfillfinish\endgroup}%
+ \smallfonts
+ \lisp
+}
+
+% @display: same as @lisp except keep current font.
+%
+\def\display{\begingroup
+ \nonfillstart
+ \let\Edisplay = \nonfillfinish
+ \gobble
+}
+
+% @smalldisplay (when @smallbook): @display plus smaller fonts.
+%
+\def\smalldisplayx{\begingroup
+ \def\Esmalldisplay{\nonfillfinish\endgroup}%
+ \smallfonts \rm
+ \display
+}
+
+% @format: same as @display except don't narrow margins.
+%
+\def\format{\begingroup
+ \let\nonarrowing = t
+ \nonfillstart
+ \let\Eformat = \nonfillfinish
+ \gobble
+}
+
+% @smallformat (when @smallbook): @format plus smaller fonts.
+%
+\def\smallformatx{\begingroup
+ \def\Esmallformat{\nonfillfinish\endgroup}%
+ \smallfonts \rm
+ \format
+}
+
+% @flushleft (same as @format).
+%
+\def\flushleft{\begingroup \def\Eflushleft{\nonfillfinish\endgroup}\format}
+
+% @flushright.
+%
+\def\flushright{\begingroup
+ \let\nonarrowing = t
+ \nonfillstart
+ \let\Eflushright = \nonfillfinish
+ \advance\leftskip by 0pt plus 1fill
+ \gobble
+}
+
+% @quotation does normal linebreaking (hence we can't use \nonfillstart)
+% and narrows the margins.
+%
+\def\quotation{%
+ \begingroup\inENV %This group ends at the end of the @quotation body
+ {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
+ \singlespace
+ \parindent=0pt
+ % We have retained a nonzero parskip for the environment, since we're
+ % doing normal filling. So to avoid extra space below the environment...
+ \def\Equotation{\parskip = 0pt \nonfillfinish}%
+ %
+ % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
+ \ifx\nonarrowing\relax
+ \advance\leftskip by \lispnarrowing
+ \advance\rightskip by \lispnarrowing
+ \exdentamount = \lispnarrowing
+ \let\nonarrowing = \relax
+ \fi
+}
+
+
+\message{defuns,}
+% @defun etc.
+
+% Allow user to change definition object font (\df) internally
+\def\setdeffont #1 {\csname DEF#1\endcsname}
+
+\newskip\defbodyindent \defbodyindent=.4in
+\newskip\defargsindent \defargsindent=50pt
+\newskip\deftypemargin \deftypemargin=12pt
+\newskip\deflastargmargin \deflastargmargin=18pt
+
+\newcount\parencount
+% define \functionparens, which makes ( and ) and & do special things.
+% \functionparens affects the group it is contained in.
+\def\activeparens{%
+\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active
+\catcode`\[=\active \catcode`\]=\active}
+
+% Make control sequences which act like normal parenthesis chars.
+\let\lparen = ( \let\rparen = )
+
+{\activeparens % Now, smart parens don't turn on until &foo (see \amprm)
+
+% Be sure that we always have a definition for `(', etc. For example,
+% if the fn name has parens in it, \boldbrax will not be in effect yet,
+% so TeX would otherwise complain about undefined control sequence.
+\global\let(=\lparen \global\let)=\rparen
+\global\let[=\lbrack \global\let]=\rbrack
+
+\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 }
+\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}
+% This is used to turn on special parens
+% but make & act ordinary (given that it's active).
+\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr}
+
+% Definitions of (, ) and & used in args for functions.
+% This is the definition of ( outside of all parentheses.
+\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested
+ \global\advance\parencount by 1
+}
+%
+% This is the definition of ( when already inside a level of parens.
+\gdef\opnested{\char`\(\global\advance\parencount by 1 }
+%
+\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0.
+ % also in that case restore the outer-level definition of (.
+ \ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi
+ \global\advance \parencount by -1 }
+% If we encounter &foo, then turn on ()-hacking afterwards
+\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ }
+%
+\gdef\normalparens{\boldbrax\let&=\ampnr}
+} % End of definition inside \activeparens
+%% These parens (in \boldbrax) actually are a little bolder than the
+%% contained text. This is especially needed for [ and ]
+\def\opnr{{\sf\char`\(}\global\advance\parencount by 1 }
+\def\clnr{{\sf\char`\)}\global\advance\parencount by -1 }
+\let\ampnr = \&
+\def\lbrb{{\bf\char`\[}}
+\def\rbrb{{\bf\char`\]}}
+
+% Active &'s sneak into the index arguments, so make sure it's defined.
+{
+ \catcode`& = 13
+ \global\let& = \ampnr
+}
+
+% First, defname, which formats the header line itself.
+% #1 should be the function name.
+% #2 should be the type of definition, such as "Function".
+
+\def\defname #1#2{%
+% Get the values of \leftskip and \rightskip as they were
+% outside the @def...
+\dimen2=\leftskip
+\advance\dimen2 by -\defbodyindent
+\noindent
+\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}%
+\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line
+\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations
+\parshape 2 0in \dimen0 \defargsindent \dimen1
+% Now output arg 2 ("Function" or some such)
+% ending at \deftypemargin from the right margin,
+% but stuck inside a box of width 0 so it does not interfere with linebreaking
+{% Adjust \hsize to exclude the ambient margins,
+% so that \rightline will obey them.
+\advance \hsize by -\dimen2
+\rlap{\rightline{{\rm #2}\hskip -1.25pc }}}%
+% Make all lines underfull and no complaints:
+\tolerance=10000 \hbadness=10000
+\advance\leftskip by -\defbodyindent
+\exdentamount=\defbodyindent
+{\df #1}\enskip % Generate function name
+}
+
+% Actually process the body of a definition
+% #1 should be the terminating control sequence, such as \Edefun.
+% #2 should be the "another name" control sequence, such as \defunx.
+% #3 should be the control sequence that actually processes the header,
+% such as \defunheader.
+
+\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody
+\medbreak %
+% Define the end token that this defining construct specifies
+% so that it will exit this group.
+\def#1{\endgraf\endgroup\medbreak}%
+\def#2{\begingroup\obeylines\activeparens\spacesplit#3}%
+\parindent=0in
+\advance\leftskip by \defbodyindent
+\exdentamount=\defbodyindent
+\begingroup %
+\catcode 61=\active % 61 is `='
+\obeylines\activeparens\spacesplit#3}
+
+% #1 is the \E... control sequence to end the definition (which we define).
+% #2 is the \...x control sequence for consecutive fns (which we define).
+% #3 is the control sequence to call to resume processing.
+% #4, delimited by the space, is the class name.
+%
+\def\defmethparsebody#1#2#3#4 {\begingroup\inENV %
+\medbreak %
+% Define the end token that this defining construct specifies
+% so that it will exit this group.
+\def#1{\endgraf\endgroup\medbreak}%
+\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}%
+\parindent=0in
+\advance\leftskip by \defbodyindent
+\exdentamount=\defbodyindent
+\begingroup\obeylines\activeparens\spacesplit{#3{#4}}}
+
+% Used for @deftypemethod and @deftypeivar.
+% #1 is the \E... control sequence to end the definition (which we define).
+% #2 is the \...x control sequence for consecutive fns (which we define).
+% #3 is the control sequence to call to resume processing.
+% #4, delimited by a space, is the class name.
+% #5 is the method's return type.
+%
+\def\deftypemethparsebody#1#2#3#4 #5 {\begingroup\inENV
+ \medbreak
+ \def#1{\endgraf\endgroup\medbreak}%
+ \def#2##1 ##2 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}{##2}}}%
+ \parindent=0in
+ \advance\leftskip by \defbodyindent
+ \exdentamount=\defbodyindent
+ \begingroup\obeylines\activeparens\spacesplit{#3{#4}{#5}}}
+
+% Used for @deftypeop. The change from \deftypemethparsebody is an
+% extra argument at the beginning which is the `category', instead of it
+% being the hardwired string `Method' or `Instance Variable'. We have
+% to account for this both in the \...x definition and in parsing the
+% input at hand. Thus also need a control sequence (passed as #5) for
+% the \E... definition to assign the category name to.
+%
+\def\deftypeopparsebody#1#2#3#4#5 #6 {\begingroup\inENV
+ \medbreak
+ \def#1{\endgraf\endgroup\medbreak}%
+ \def#2##1 ##2 ##3 {%
+ \def#4{##1}%
+ \begingroup\obeylines\activeparens\spacesplit{#3{##2}{##3}}}%
+ \parindent=0in
+ \advance\leftskip by \defbodyindent
+ \exdentamount=\defbodyindent
+ \begingroup\obeylines\activeparens\spacesplit{#3{#5}{#6}}}
+
+\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV %
+\medbreak %
+% Define the end token that this defining construct specifies
+% so that it will exit this group.
+\def#1{\endgraf\endgroup\medbreak}%
+\def#2##1 ##2 {\def#4{##1}%
+\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}%
+\parindent=0in
+\advance\leftskip by \defbodyindent
+\exdentamount=\defbodyindent
+\begingroup\obeylines\activeparens\spacesplit{#3{#5}}}
+
+% These parsing functions are similar to the preceding ones
+% except that they do not make parens into active characters.
+% These are used for "variables" since they have no arguments.
+
+\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody
+\medbreak %
+% Define the end token that this defining construct specifies
+% so that it will exit this group.
+\def#1{\endgraf\endgroup\medbreak}%
+\def#2{\begingroup\obeylines\spacesplit#3}%
+\parindent=0in
+\advance\leftskip by \defbodyindent
+\exdentamount=\defbodyindent
+\begingroup %
+\catcode 61=\active %
+\obeylines\spacesplit#3}
+
+% This is used for \def{tp,vr}parsebody. It could probably be used for
+% some of the others, too, with some judicious conditionals.
+%
+\def\parsebodycommon#1#2#3{%
+ \begingroup\inENV %
+ \medbreak %
+ % Define the end token that this defining construct specifies
+ % so that it will exit this group.
+ \def#1{\endgraf\endgroup\medbreak}%
+ \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}%
+ \parindent=0in
+ \advance\leftskip by \defbodyindent
+ \exdentamount=\defbodyindent
+ \begingroup\obeylines
+}
+
+\def\defvrparsebody#1#2#3#4 {%
+ \parsebodycommon{#1}{#2}{#3}%
+ \spacesplit{#3{#4}}%
+}
+
+% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the
+% type is just `struct', because we lose the braces in `{struct
+% termios}' when \spacesplit reads its undelimited argument. Sigh.
+% \let\deftpparsebody=\defvrparsebody
+%
+% So, to get around this, we put \empty in with the type name. That
+% way, TeX won't find exactly `{...}' as an undelimited argument, and
+% won't strip off the braces.
+%
+\def\deftpparsebody #1#2#3#4 {%
+ \parsebodycommon{#1}{#2}{#3}%
+ \spacesplit{\parsetpheaderline{#3{#4}}}\empty
+}
+
+% Fine, but then we have to eventually remove the \empty *and* the
+% braces (if any). That's what this does.
+%
+\def\removeemptybraces\empty#1\relax{#1}
+
+% After \spacesplit has done its work, this is called -- #1 is the final
+% thing to call, #2 the type name (which starts with \empty), and #3
+% (which might be empty) the arguments.
+%
+\def\parsetpheaderline#1#2#3{%
+ #1{\removeemptybraces#2\relax}{#3}%
+}%
+
+\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV %
+\medbreak %
+% Define the end token that this defining construct specifies
+% so that it will exit this group.
+\def#1{\endgraf\endgroup\medbreak}%
+\def#2##1 ##2 {\def#4{##1}%
+\begingroup\obeylines\spacesplit{#3{##2}}}%
+\parindent=0in
+\advance\leftskip by \defbodyindent
+\exdentamount=\defbodyindent
+\begingroup\obeylines\spacesplit{#3{#5}}}
+
+% Split up #2 at the first space token.
+% call #1 with two arguments:
+% the first is all of #2 before the space token,
+% the second is all of #2 after that space token.
+% If #2 contains no space token, all of it is passed as the first arg
+% and the second is passed as empty.
+
+{\obeylines
+\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}%
+\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{%
+\ifx\relax #3%
+#1{#2}{}\else #1{#2}{#3#4}\fi}}
+
+% So much for the things common to all kinds of definitions.
+
+% Define @defun.
+
+% First, define the processing that is wanted for arguments of \defun
+% Use this to expand the args and terminate the paragraph they make up
+
+\def\defunargs#1{\functionparens \sl
+% Expand, preventing hyphenation at `-' chars.
+% Note that groups don't affect changes in \hyphenchar.
+% Set the font temporarily and use \font in case \setfont made \tensl a macro.
+{\tensl\hyphenchar\font=0}%
+#1%
+{\tensl\hyphenchar\font=45}%
+\ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi%
+\interlinepenalty=10000
+\advance\rightskip by 0pt plus 1fil
+\endgraf\nobreak\vskip -\parskip\nobreak
+}
+
+\def\deftypefunargs #1{%
+% Expand, preventing hyphenation at `-' chars.
+% Note that groups don't affect changes in \hyphenchar.
+% Use \boldbraxnoamp, not \functionparens, so that & is not special.
+\boldbraxnoamp
+\tclose{#1}% avoid \code because of side effects on active chars
+\interlinepenalty=10000
+\advance\rightskip by 0pt plus 1fil
+\endgraf\nobreak\vskip -\parskip\nobreak
+}
+
+% Do complete processing of one @defun or @defunx line already parsed.
+
+% @deffn Command forward-char nchars
+
+\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader}
+
+\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}%
+\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup %
+\catcode 61=\other % Turn off change made in \defparsebody
+}
+
+% @defun == @deffn Function
+
+\def\defun{\defparsebody\Edefun\defunx\defunheader}
+
+\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index
+\begingroup\defname {#1}{\putwordDeffunc}%
+\defunargs {#2}\endgroup %
+\catcode 61=\other % Turn off change made in \defparsebody
+}
+
+% @deftypefun int foobar (int @var{foo}, float @var{bar})
+
+\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader}
+
+% #1 is the data type. #2 is the name and args.
+\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax}
+% #1 is the data type, #2 the name, #3 the args.
+\def\deftypefunheaderx #1#2 #3\relax{%
+\doind {fn}{\code{#2}}% Make entry in function index
+\begingroup\defname {\defheaderxcond#1\relax$$$#2}{\putwordDeftypefun}%
+\deftypefunargs {#3}\endgroup %
+\catcode 61=\other % Turn off change made in \defparsebody
+}
+
+% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
+
+\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader}
+
+% \defheaderxcond#1\relax$$$
+% puts #1 in @code, followed by a space, but does nothing if #1 is null.
+\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi}
+
+% #1 is the classification. #2 is the data type. #3 is the name and args.
+\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax}
+% #1 is the classification, #2 the data type, #3 the name, #4 the args.
+\def\deftypefnheaderx #1#2#3 #4\relax{%
+\doind {fn}{\code{#3}}% Make entry in function index
+\begingroup
+\normalparens % notably, turn off `&' magic, which prevents
+% at least some C++ text from working
+\defname {\defheaderxcond#2\relax$$$#3}{#1}%
+\deftypefunargs {#4}\endgroup %
+\catcode 61=\other % Turn off change made in \defparsebody
+}
+
+% @defmac == @deffn Macro
+
+\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader}
+
+\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index
+\begingroup\defname {#1}{\putwordDefmac}%
+\defunargs {#2}\endgroup %
+\catcode 61=\other % Turn off change made in \defparsebody
+}
+
+% @defspec == @deffn Special Form
+
+\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader}
+
+\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index
+\begingroup\defname {#1}{\putwordDefspec}%
+\defunargs {#2}\endgroup %
+\catcode 61=\other % Turn off change made in \defparsebody
+}
+
+% @defop CATEGORY CLASS OPERATION ARG...
+%
+\def\defop #1 {\def\defoptype{#1}%
+\defopparsebody\Edefop\defopx\defopheader\defoptype}
+%
+\def\defopheader#1#2#3{%
+\dosubind {fn}{\code{#2}}{\putwordon\ #1}% Make entry in function index
+\begingroup\defname {#2}{\defoptype\ \putwordon\ #1}%
+\defunargs {#3}\endgroup %
+}
+
+% @deftypeop CATEGORY CLASS TYPE OPERATION ARG...
+%
+\def\deftypeop #1 {\def\deftypeopcategory{#1}%
+ \deftypeopparsebody\Edeftypeop\deftypeopx\deftypeopheader
+ \deftypeopcategory}
+%
+% #1 is the class name, #2 the data type, #3 the operation name, #4 the args.
+\def\deftypeopheader#1#2#3#4{%
+ \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index
+ \begingroup
+ \defname{\defheaderxcond#2\relax$$$#3}
+ {\deftypeopcategory\ \putwordon\ \code{#1}}%
+ \deftypefunargs{#4}%
+ \endgroup
+}
+
+% @deftypemethod CLASS TYPE METHOD ARG...
+%
+\def\deftypemethod{%
+ \deftypemethparsebody\Edeftypemethod\deftypemethodx\deftypemethodheader}
+%
+% #1 is the class name, #2 the data type, #3 the method name, #4 the args.
+\def\deftypemethodheader#1#2#3#4{%
+ \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index
+ \begingroup
+ \defname{\defheaderxcond#2\relax$$$#3}{\putwordMethodon\ \code{#1}}%
+ \deftypefunargs{#4}%
+ \endgroup
+}
+
+% @deftypeivar CLASS TYPE VARNAME
+%
+\def\deftypeivar{%
+ \deftypemethparsebody\Edeftypeivar\deftypeivarx\deftypeivarheader}
+%
+% #1 is the class name, #2 the data type, #3 the variable name.
+\def\deftypeivarheader#1#2#3{%
+ \dosubind{vr}{\code{#3}}{\putwordof\ \code{#1}}% entry in variable index
+ \begingroup
+ \defname{\defheaderxcond#2\relax$$$#3}
+ {\putwordInstanceVariableof\ \code{#1}}%
+ \defvarargs{#3}%
+ \endgroup
+}
+
+% @defmethod == @defop Method
+%
+\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader}
+%
+% #1 is the class name, #2 the method name, #3 the args.
+\def\defmethodheader#1#2#3{%
+ \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% entry in function index
+ \begingroup
+ \defname{#2}{\putwordMethodon\ \code{#1}}%
+ \defunargs{#3}%
+ \endgroup
+}
+
+% @defcv {Class Option} foo-class foo-flag
+
+\def\defcv #1 {\def\defcvtype{#1}%
+\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype}
+
+\def\defcvarheader #1#2#3{%
+\dosubind {vr}{\code{#2}}{\putwordof\ #1}% Make entry in var index
+\begingroup\defname {#2}{\defcvtype\ \putwordof\ #1}%
+\defvarargs {#3}\endgroup %
+}
+
+% @defivar CLASS VARNAME == @defcv {Instance Variable} CLASS VARNAME
+%
+\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader}
+%
+\def\defivarheader#1#2#3{%
+ \dosubind {vr}{\code{#2}}{\putwordof\ #1}% entry in var index
+ \begingroup
+ \defname{#2}{\putwordInstanceVariableof\ #1}%
+ \defvarargs{#3}%
+ \endgroup
+}
+
+% @defvar
+% First, define the processing that is wanted for arguments of @defvar.
+% This is actually simple: just print them in roman.
+% This must expand the args and terminate the paragraph they make up
+\def\defvarargs #1{\normalparens #1%
+\interlinepenalty=10000
+\endgraf\nobreak\vskip -\parskip\nobreak}
+
+% @defvr Counter foo-count
+
+\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader}
+
+\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}%
+\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup}
+
+% @defvar == @defvr Variable
+
+\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader}
+
+\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index
+\begingroup\defname {#1}{\putwordDefvar}%
+\defvarargs {#2}\endgroup %
+}
+
+% @defopt == @defvr {User Option}
+
+\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader}
+
+\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index
+\begingroup\defname {#1}{\putwordDefopt}%
+\defvarargs {#2}\endgroup %
+}
+
+% @deftypevar int foobar
+
+\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader}
+
+% #1 is the data type. #2 is the name, perhaps followed by text that
+% is actually part of the data type, which should not be put into the index.
+\def\deftypevarheader #1#2{%
+\dovarind#2 \relax% Make entry in variables index
+\begingroup\defname {\defheaderxcond#1\relax$$$#2}{\putwordDeftypevar}%
+\interlinepenalty=10000
+\endgraf\nobreak\vskip -\parskip\nobreak
+\endgroup}
+\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}}
+
+% @deftypevr {Global Flag} int enable
+
+\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader}
+
+\def\deftypevrheader #1#2#3{\dovarind#3 \relax%
+\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1}
+\interlinepenalty=10000
+\endgraf\nobreak\vskip -\parskip\nobreak
+\endgroup}
+
+% Now define @deftp
+% Args are printed in bold, a slight difference from @defvar.
+
+\def\deftpargs #1{\bf \defvarargs{#1}}
+
+% @deftp Class window height width ...
+
+\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader}
+
+\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}%
+\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup}
+
+% These definitions are used if you use @defunx (etc.)
+% anywhere other than immediately after a @defun or @defunx.
+%
+\def\defcvx#1 {\errmessage{@defcvx in invalid context}}
+\def\deffnx#1 {\errmessage{@deffnx in invalid context}}
+\def\defivarx#1 {\errmessage{@defivarx in invalid context}}
+\def\defmacx#1 {\errmessage{@defmacx in invalid context}}
+\def\defmethodx#1 {\errmessage{@defmethodx in invalid context}}
+\def\defoptx #1 {\errmessage{@defoptx in invalid context}}
+\def\defopx#1 {\errmessage{@defopx in invalid context}}
+\def\defspecx#1 {\errmessage{@defspecx in invalid context}}
+\def\deftpx#1 {\errmessage{@deftpx in invalid context}}
+\def\deftypefnx#1 {\errmessage{@deftypefnx in invalid context}}
+\def\deftypefunx#1 {\errmessage{@deftypefunx in invalid context}}
+\def\deftypeivarx#1 {\errmessage{@deftypeivarx in invalid context}}
+\def\deftypemethodx#1 {\errmessage{@deftypemethodx in invalid context}}
+\def\deftypeopx#1 {\errmessage{@deftypeopx in invalid context}}
+\def\deftypevarx#1 {\errmessage{@deftypevarx in invalid context}}
+\def\deftypevrx#1 {\errmessage{@deftypevrx in invalid context}}
+\def\defunx#1 {\errmessage{@defunx in invalid context}}
+\def\defvarx#1 {\errmessage{@defvarx in invalid context}}
+\def\defvrx#1 {\errmessage{@defvrx in invalid context}}
+
+
+\message{macros,}
+% @macro.
+
+% To do this right we need a feature of e-TeX, \scantokens,
+% which we arrange to emulate with a temporary file in ordinary TeX.
+\ifx\eTeXversion\undefined
+ \newwrite\macscribble
+ \def\scanmacro#1{%
+ \begingroup \newlinechar`\^^M
+ % Undo catcode changes of \startcontents and \doprintindex
+ \catcode`\@=0 \catcode`\\=12 \escapechar=`\@
+ % Append \endinput to make sure that TeX does not see the ending newline.
+ \toks0={#1\endinput}%
+ \immediate\openout\macscribble=\jobname.tmp
+ \immediate\write\macscribble{\the\toks0}%
+ \immediate\closeout\macscribble
+ \let\xeatspaces\eatspaces
+ \input \jobname.tmp
+ \endgroup
+}
+\else
+\def\scanmacro#1{%
+\begingroup \newlinechar`\^^M
+% Undo catcode changes of \startcontents and \doprintindex
+\catcode`\@=0 \catcode`\\=12 \escapechar=`\@
+\let\xeatspaces\eatspaces\scantokens{#1\endinput}\endgroup}
+\fi
+
+\newcount\paramno % Count of parameters
+\newtoks\macname % Macro name
+\newif\ifrecursive % Is it recursive?
+\def\macrolist{} % List of all defined macros in the form
+ % \do\macro1\do\macro2...
+
+% Utility routines.
+% Thisdoes \let #1 = #2, except with \csnames.
+\def\cslet#1#2{%
+\expandafter\expandafter
+\expandafter\let
+\expandafter\expandafter
+\csname#1\endcsname
+\csname#2\endcsname}
+
+% Trim leading and trailing spaces off a string.
+% Concepts from aro-bend problem 15 (see CTAN).
+{\catcode`\@=11
+\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}
+\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}
+\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}
+\def\unbrace#1{#1}
+\unbrace{\gdef\trim@@@ #1 } #2@{#1}
+}
+
+% Trim a single trailing ^^M off a string.
+{\catcode`\^^M=12\catcode`\Q=3%
+\gdef\eatcr #1{\eatcra #1Q^^MQ}%
+\gdef\eatcra#1^^MQ{\eatcrb#1Q}%
+\gdef\eatcrb#1Q#2Q{#1}%
+}
+
+% Macro bodies are absorbed as an argument in a context where
+% all characters are catcode 10, 11 or 12, except \ which is active
+% (as in normal texinfo). It is necessary to change the definition of \.
+
+% It's necessary to have hard CRs when the macro is executed. This is
+% done by making ^^M (\endlinechar) catcode 12 when reading the macro
+% body, and then making it the \newlinechar in \scanmacro.
+
+\def\macrobodyctxt{%
+ \catcode`\~=12
+ \catcode`\^=12
+ \catcode`\_=12
+ \catcode`\|=12
+ \catcode`\<=12
+ \catcode`\>=12
+ \catcode`\+=12
+ \catcode`\{=12
+ \catcode`\}=12
+ \catcode`\@=12
+ \catcode`\^^M=12
+ \usembodybackslash}
+
+\def\macroargctxt{%
+ \catcode`\~=12
+ \catcode`\^=12
+ \catcode`\_=12
+ \catcode`\|=12
+ \catcode`\<=12
+ \catcode`\>=12
+ \catcode`\+=12
+ \catcode`\@=12
+ \catcode`\\=12}
+
+% \mbodybackslash is the definition of \ in @macro bodies.
+% It maps \foo\ => \csname macarg.foo\endcsname => #N
+% where N is the macro parameter number.
+% We define \csname macarg.\endcsname to be \realbackslash, so
+% \\ in macro replacement text gets you a backslash.
+
+{\catcode`@=0 @catcode`@\=@active
+ @gdef@usembodybackslash{@let\=@mbodybackslash}
+ @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}
+}
+\expandafter\def\csname macarg.\endcsname{\realbackslash}
+
+\def\macro{\recursivefalse\parsearg\macroxxx}
+\def\rmacro{\recursivetrue\parsearg\macroxxx}
+
+\def\macroxxx#1{%
+ \getargs{#1}% now \macname is the macname and \argl the arglist
+ \ifx\argl\empty % no arguments
+ \paramno=0%
+ \else
+ \expandafter\parsemargdef \argl;%
+ \fi
+ \if1\csname ismacro.\the\macname\endcsname
+ \message{Warning: redefining \the\macname}%
+ \else
+ \expandafter\ifx\csname \the\macname\endcsname \relax
+ \else \errmessage{The name \the\macname\space is reserved}\fi
+ \global\cslet{macsave.\the\macname}{\the\macname}%
+ \global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
+ % Add the macroname to \macrolist
+ \toks0 = \expandafter{\macrolist\do}%
+ \xdef\macrolist{\the\toks0
+ \expandafter\noexpand\csname\the\macname\endcsname}%
+ \fi
+ \begingroup \macrobodyctxt
+ \ifrecursive \expandafter\parsermacbody
+ \else \expandafter\parsemacbody
+ \fi}
+
+\def\unmacro{\parsearg\unmacroxxx}
+\def\unmacroxxx#1{%
+ \if1\csname ismacro.#1\endcsname
+ \global\cslet{#1}{macsave.#1}%
+ \global\expandafter\let \csname ismacro.#1\endcsname=0%
+ % Remove the macro name from \macrolist
+ \begingroup
+ \edef\tempa{\expandafter\noexpand\csname#1\endcsname}%
+ \def\do##1{%
+ \def\tempb{##1}%
+ \ifx\tempa\tempb
+ % remove this
+ \else
+ \toks0 = \expandafter{\newmacrolist\do}%
+ \edef\newmacrolist{\the\toks0\expandafter\noexpand\tempa}%
+ \fi}%
+ \def\newmacrolist{}%
+ % Execute macro list to define \newmacrolist
+ \macrolist
+ \global\let\macrolist\newmacrolist
+ \endgroup
+ \else
+ \errmessage{Macro #1 not defined}%
+ \fi
+}
+
+% This makes use of the obscure feature that if the last token of a
+% <parameter list> is #, then the preceding argument is delimited by
+% an opening brace, and that opening brace is not consumed.
+\def\getargs#1{\getargsxxx#1{}}
+\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
+\def\getmacname #1 #2\relax{\macname={#1}}
+\def\getmacargs#1{\def\argl{#1}}
+
+% Parse the optional {params} list. Set up \paramno and \paramlist
+% so \defmacro knows what to do. Define \macarg.blah for each blah
+% in the params list, to be ##N where N is the position in that list.
+% That gets used by \mbodybackslash (above).
+
+% We need to get `macro parameter char #' into several definitions.
+% The technique used is stolen from LaTeX: let \hash be something
+% unexpandable, insert that wherever you need a #, and then redefine
+% it to # just before using the token list produced.
+%
+% The same technique is used to protect \eatspaces till just before
+% the macro is used.
+
+\def\parsemargdef#1;{\paramno=0\def\paramlist{}%
+ \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,}
+\def\parsemargdefxxx#1,{%
+ \if#1;\let\next=\relax
+ \else \let\next=\parsemargdefxxx
+ \advance\paramno by 1%
+ \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
+ {\xeatspaces{\hash\the\paramno}}%
+ \edef\paramlist{\paramlist\hash\the\paramno,}%
+ \fi\next}
+
+% These two commands read recursive and nonrecursive macro bodies.
+% (They're different since rec and nonrec macros end differently.)
+
+\long\def\parsemacbody#1@end macro%
+{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+\long\def\parsermacbody#1@end rmacro%
+{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+
+% This defines the macro itself. There are six cases: recursive and
+% nonrecursive macros of zero, one, and many arguments.
+% Much magic with \expandafter here.
+% \xdef is used so that macro definitions will survive the file
+% they're defined in; @include reads the file inside a group.
+\def\defmacro{%
+ \let\hash=##% convert placeholders to macro parameter chars
+ \ifrecursive
+ \ifcase\paramno
+ % 0
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \noexpand\scanmacro{\temp}}%
+ \or % 1
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \noexpand\braceorline
+ \expandafter\noexpand\csname\the\macname xxx\endcsname}%
+ \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+ \egroup\noexpand\scanmacro{\temp}}%
+ \else % many
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \noexpand\csname\the\macname xx\endcsname}%
+ \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+ \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+ \expandafter\expandafter
+ \expandafter\xdef
+ \expandafter\expandafter
+ \csname\the\macname xxx\endcsname
+ \paramlist{\egroup\noexpand\scanmacro{\temp}}%
+ \fi
+ \else
+ \ifcase\paramno
+ % 0
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \noexpand\norecurse{\the\macname}%
+ \noexpand\scanmacro{\temp}\egroup}%
+ \or % 1
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \noexpand\braceorline
+ \expandafter\noexpand\csname\the\macname xxx\endcsname}%
+ \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+ \egroup
+ \noexpand\norecurse{\the\macname}%
+ \noexpand\scanmacro{\temp}\egroup}%
+ \else % many
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \expandafter\noexpand\csname\the\macname xx\endcsname}%
+ \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+ \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+ \expandafter\expandafter
+ \expandafter\xdef
+ \expandafter\expandafter
+ \csname\the\macname xxx\endcsname
+ \paramlist{%
+ \egroup
+ \noexpand\norecurse{\the\macname}%
+ \noexpand\scanmacro{\temp}\egroup}%
+ \fi
+ \fi}
+
+\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
+
+% \braceorline decides whether the next nonwhitespace character is a
+% {. If so it reads up to the closing }, if not, it reads the whole
+% line. Whatever was read is then fed to the next control sequence
+% as an argument (by \parsebrace or \parsearg)
+\def\braceorline#1{\let\next=#1\futurelet\nchar\braceorlinexxx}
+\def\braceorlinexxx{%
+ \ifx\nchar\bgroup\else
+ \expandafter\parsearg
+ \fi \next}
+
+% We mant to disable all macros during \shipout so that they are not
+% expanded by \write.
+\def\turnoffmacros{\begingroup \def\do##1{\let\noexpand##1=\relax}%
+ \edef\next{\macrolist}\expandafter\endgroup\next}
+
+
+% @alias.
+% We need some trickery to remove the optional spaces around the equal
+% sign. Just make them active and then expand them all to nothing.
+\def\alias{\begingroup\obeyspaces\parsearg\aliasxxx}
+\def\aliasxxx #1{\aliasyyy#1\relax}
+\def\aliasyyy #1=#2\relax{\ignoreactivespaces
+\edef\next{\global\let\expandafter\noexpand\csname#1\endcsname=%
+ \expandafter\noexpand\csname#2\endcsname}%
+\expandafter\endgroup\next}
+
+
+\message{cross references,}
+% @xref etc.
+
+\newwrite\auxfile
+
+\newif\ifhavexrefs % True if xref values are known.
+\newif\ifwarnedxrefs % True if we warned once that they aren't known.
+
+% @inforef is relatively simple.
+\def\inforef #1{\inforefzzz #1,,,,**}
+\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},
+ node \samp{\ignorespaces#1{}}}
+
+% @node's job is to define \lastnode.
+\def\node{\ENVcheck\parsearg\nodezzz}
+\def\nodezzz#1{\nodexxx [#1,]}
+\def\nodexxx[#1,#2]{\gdef\lastnode{#1}}
+\let\nwnode=\node
+\let\lastnode=\relax
+
+% The sectioning commands (@chapter, etc.) call these.
+\def\donoderef{%
+ \ifx\lastnode\relax\else
+ \expandafter\expandafter\expandafter\setref{\lastnode}%
+ {Ysectionnumberandtype}%
+ \global\let\lastnode=\relax
+ \fi
+}
+\def\unnumbnoderef{%
+ \ifx\lastnode\relax\else
+ \expandafter\expandafter\expandafter\setref{\lastnode}{Ynothing}%
+ \global\let\lastnode=\relax
+ \fi
+}
+\def\appendixnoderef{%
+ \ifx\lastnode\relax\else
+ \expandafter\expandafter\expandafter\setref{\lastnode}%
+ {Yappendixletterandtype}%
+ \global\let\lastnode=\relax
+ \fi
+}
+
+
+% @anchor{NAME} -- define xref target at arbitrary point.
+%
+\newcount\savesfregister
+\gdef\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}
+\gdef\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}
+\gdef\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}
+
+% \setref{NAME}{SNT} defines a cross-reference point NAME, namely
+% NAME-title, NAME-pg, and NAME-SNT. Called from \foonoderef. We have
+% to set \indexdummies so commands such as @code in a section title
+% aren't expanded. It would be nicer not to expand the titles in the
+% first place, but there's so many layers that that is hard to do.
+%
+\def\setref#1#2{{%
+ \indexdummies
+ \pdfmkdest{#1}%
+ \dosetq{#1-title}{Ytitle}%
+ \dosetq{#1-pg}{Ypagenumber}%
+ \dosetq{#1-snt}{#2}%
+}}
+
+% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is
+% the node name, #2 the name of the Info cross-reference, #3 the printed
+% node name, #4 the name of the Info file, #5 the name of the printed
+% manual. All but the node name can be omitted.
+%
+\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]}
+\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}
+\def\ref#1{\xrefX[#1,,,,,,,]}
+\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
+ \unsepspaces
+ \def\printedmanual{\ignorespaces #5}%
+ \def\printednodename{\ignorespaces #3}%
+ \setbox1=\hbox{\printedmanual}%
+ \setbox0=\hbox{\printednodename}%
+ \ifdim \wd0 = 0pt
+ % No printed node name was explicitly given.
+ \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax
+ % Use the node name inside the square brackets.
+ \def\printednodename{\ignorespaces #1}%
+ \else
+ % Use the actual chapter/section title appear inside
+ % the square brackets. Use the real section title if we have it.
+ \ifdim \wd1 > 0pt
+ % It is in another manual, so we don't have it.
+ \def\printednodename{\ignorespaces #1}%
+ \else
+ \ifhavexrefs
+ % We know the real title if we have the xref values.
+ \def\printednodename{\refx{#1-title}{}}%
+ \else
+ % Otherwise just copy the Info node name.
+ \def\printednodename{\ignorespaces #1}%
+ \fi%
+ \fi
+ \fi
+ \fi
+ %
+ % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not
+ % insert empty discretionaries after hyphens, which means that it will
+ % not find a line break at a hyphen in a node names. Since some manuals
+ % are best written with fairly long node names, containing hyphens, this
+ % is a loss. Therefore, we give the text of the node name again, so it
+ % is as if TeX is seeing it for the first time.
+ \ifpdf
+ \leavevmode
+ \getfilename{#4}%
+ \ifnum\filenamelength>0
+ \startlink attr{/Border [0 0 0]}%
+ goto file{\the\filename.pdf} name{#1@}%
+ \else
+ \startlink attr{/Border [0 0 0]}%
+ goto name{#1@}%
+ \fi
+ \linkcolor
+ \fi
+ %
+ \ifdim \wd1 > 0pt
+ \putwordsection{} ``\printednodename'' \putwordin{} \cite{\printedmanual}%
+ \else
+ % _ (for example) has to be the character _ for the purposes of the
+ % control sequence corresponding to the node, but it has to expand
+ % into the usual \leavevmode...\vrule stuff for purposes of
+ % printing. So we \turnoffactive for the \refx-snt, back on for the
+ % printing, back off for the \refx-pg.
+ {\normalturnoffactive
+ % Only output a following space if the -snt ref is nonempty; for
+ % @unnumbered and @anchor, it won't be.
+ \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
+ \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
+ }%
+ % [mynode],
+ [\printednodename],\space
+ % page 3
+ \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
+ \fi
+ \endlink
+\endgroup}
+
+% \dosetq is the interface for calls from other macros
+
+% Use \normalturnoffactive so that punctuation chars such as underscore
+% and backslash work in node names. (\turnoffactive doesn't do \.)
+\def\dosetq#1#2{%
+ {\let\folio=0%
+ \normalturnoffactive
+ \edef\next{\write\auxfile{\internalsetq{#1}{#2}}}%
+ \iflinks
+ \next
+ \fi
+ }%
+}
+
+% \internalsetq {foo}{page} expands into
+% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...}
+% When the aux file is read, ' is the escape character
+
+\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}}
+
+% Things to be expanded by \internalsetq
+
+\def\Ypagenumber{\folio}
+
+\def\Ytitle{\thissection}
+
+\def\Ynothing{}
+
+\def\Ysectionnumberandtype{%
+\ifnum\secno=0 \putwordChapter\xreftie\the\chapno %
+\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno %
+\else \ifnum \subsubsecno=0 %
+\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno %
+\else %
+\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno %
+\fi \fi \fi }
+
+\def\Yappendixletterandtype{%
+\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}%
+\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno %
+\else \ifnum \subsubsecno=0 %
+\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno %
+\else %
+\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno %
+\fi \fi \fi }
+
+\gdef\xreftie{'tie}
+
+% Use TeX 3.0's \inputlineno to get the line number, for better error
+% messages, but if we're using an old version of TeX, don't do anything.
+%
+\ifx\inputlineno\thisisundefined
+ \let\linenumber = \empty % Non-3.0.
+\else
+ \def\linenumber{\the\inputlineno:\space}
+\fi
+
+% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.
+% If its value is nonempty, SUFFIX is output afterward.
+
+\def\refx#1#2{%
+ \expandafter\ifx\csname X#1\endcsname\relax
+ % If not defined, say something at least.
+ \angleleft un\-de\-fined\angleright
+ \iflinks
+ \ifhavexrefs
+ \message{\linenumber Undefined cross reference `#1'.}%
+ \else
+ \ifwarnedxrefs\else
+ \global\warnedxrefstrue
+ \message{Cross reference values unknown; you must run TeX again.}%
+ \fi
+ \fi
+ \fi
+ \else
+ % It's defined, so just use it.
+ \csname X#1\endcsname
+ \fi
+ #2% Output the suffix in any case.
+}
+
+% This is the macro invoked by entries in the aux file.
+%
+\def\xrdef#1{\begingroup
+ % Reenable \ as an escape while reading the second argument.
+ \catcode`\\ = 0
+ \afterassignment\endgroup
+ \expandafter\gdef\csname X#1\endcsname
+}
+
+% Read the last existing aux file, if any. No error if none exists.
+\def\readauxfile{\begingroup
+ \catcode`\^^@=\other
+ \catcode`\^^A=\other
+ \catcode`\^^B=\other
+ \catcode`\^^C=\other
+ \catcode`\^^D=\other
+ \catcode`\^^E=\other
+ \catcode`\^^F=\other
+ \catcode`\^^G=\other
+ \catcode`\^^H=\other
+ \catcode`\^^K=\other
+ \catcode`\^^L=\other
+ \catcode`\^^N=\other
+ \catcode`\^^P=\other
+ \catcode`\^^Q=\other
+ \catcode`\^^R=\other
+ \catcode`\^^S=\other
+ \catcode`\^^T=\other
+ \catcode`\^^U=\other
+ \catcode`\^^V=\other
+ \catcode`\^^W=\other
+ \catcode`\^^X=\other
+ \catcode`\^^Z=\other
+ \catcode`\^^[=\other
+ \catcode`\^^\=\other
+ \catcode`\^^]=\other
+ \catcode`\^^^=\other
+ \catcode`\^^_=\other
+ \catcode`\@=\other
+ \catcode`\^=\other
+ % It was suggested to define this as 7, which would allow ^^e4 etc.
+ % in xref tags, i.e., node names. But since ^^e4 notation isn't
+ % supported in the main text, it doesn't seem desirable. Furthermore,
+ % that is not enough: for node names that actually contain a ^
+ % character, we would end up writing a line like this: 'xrdef {'hat
+ % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first
+ % argument, and \hat is not an expandable control sequence. It could
+ % all be worked out, but why? Either we support ^^ or we don't.
+ %
+ % The other change necessary for this was to define \auxhat:
+ % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter
+ % and then to call \auxhat in \setq.
+ %
+ \catcode`\~=\other
+ \catcode`\[=\other
+ \catcode`\]=\other
+ \catcode`\"=\other
+ \catcode`\_=\other
+ \catcode`\|=\other
+ \catcode`\<=\other
+ \catcode`\>=\other
+ \catcode`\$=\other
+ \catcode`\#=\other
+ \catcode`\&=\other
+ \catcode`+=\other % avoid \+ for paranoia even though we've turned it off
+ % Make the characters 128-255 be printing characters
+ {%
+ \count 1=128
+ \def\loop{%
+ \catcode\count 1=\other
+ \advance\count 1 by 1
+ \ifnum \count 1<256 \loop \fi
+ }%
+ }%
+ % The aux file uses ' as the escape (for now).
+ % Turn off \ as an escape so we do not lose on
+ % entries which were dumped with control sequences in their names.
+ % For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^
+ % Reference to such entries still does not work the way one would wish,
+ % but at least they do not bomb out when the aux file is read in.
+ \catcode`\{=1
+ \catcode`\}=2
+ \catcode`\%=\other
+ \catcode`\'=0
+ \catcode`\\=\other
+ %
+ \openin 1 \jobname.aux
+ \ifeof 1 \else
+ \closein 1
+ \input \jobname.aux
+ \global\havexrefstrue
+ \global\warnedobstrue
+ \fi
+ % Open the new aux file. TeX will close it automatically at exit.
+ \openout\auxfile=\jobname.aux
+\endgroup}
+
+
+% Footnotes.
+
+\newcount \footnoteno
+
+% The trailing space in the following definition for supereject is
+% vital for proper filling; pages come out unaligned when you do a
+% pagealignmacro call if that space before the closing brace is
+% removed. (Generally, numeric constants should always be followed by a
+% space to prevent strange expansion errors.)
+\def\supereject{\par\penalty -20000\footnoteno =0 }
+
+% @footnotestyle is meaningful for info output only.
+\let\footnotestyle=\comment
+
+\let\ptexfootnote=\footnote
+
+{\catcode `\@=11
+%
+% Auto-number footnotes. Otherwise like plain.
+\gdef\footnote{%
+ \global\advance\footnoteno by \@ne
+ \edef\thisfootno{$^{\the\footnoteno}$}%
+ %
+ % In case the footnote comes at the end of a sentence, preserve the
+ % extra spacing after we do the footnote number.
+ \let\@sf\empty
+ \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi
+ %
+ % Remove inadvertent blank space before typesetting the footnote number.
+ \unskip
+ \thisfootno\@sf
+ \footnotezzz
+}%
+
+% Don't bother with the trickery in plain.tex to not require the
+% footnote text as a parameter. Our footnotes don't need to be so general.
+%
+% Oh yes, they do; otherwise, @ifset and anything else that uses
+% \parseargline fail inside footnotes because the tokens are fixed when
+% the footnote is read. --karl, 16nov96.
+%
+\long\gdef\footnotezzz{\insert\footins\bgroup
+ % We want to typeset this text as a normal paragraph, even if the
+ % footnote reference occurs in (for example) a display environment.
+ % So reset some parameters.
+ \interlinepenalty\interfootnotelinepenalty
+ \splittopskip\ht\strutbox % top baseline for broken footnotes
+ \splitmaxdepth\dp\strutbox
+ \floatingpenalty\@MM
+ \leftskip\z@skip
+ \rightskip\z@skip
+ \spaceskip\z@skip
+ \xspaceskip\z@skip
+ \parindent\defaultparindent
+ %
+ \smallfonts \rm
+ %
+ % Hang the footnote text off the number.
+ \hang
+ \textindent{\thisfootno}%
+ %
+ % Don't crash into the line above the footnote text. Since this
+ % expands into a box, it must come within the paragraph, lest it
+ % provide a place where TeX can split the footnote.
+ \footstrut
+ \futurelet\next\fo@t
+}
+\def\fo@t{\ifcat\bgroup\noexpand\next \let\next\f@@t
+ \else\let\next\f@t\fi \next}
+\def\f@@t{\bgroup\aftergroup\@foot\let\next}
+\def\f@t#1{#1\@foot}
+\def\@foot{\strut\par\egroup}
+
+}%end \catcode `\@=11
+
+% Set the baselineskip to #1, and the lineskip and strut size
+% correspondingly. There is no deep meaning behind these magic numbers
+% used as factors; they just match (closely enough) what Knuth defined.
+%
+\def\lineskipfactor{.08333}
+\def\strutheightpercent{.70833}
+\def\strutdepthpercent {.29167}
+%
+\def\setleading#1{%
+ \normalbaselineskip = #1\relax
+ \normallineskip = \lineskipfactor\normalbaselineskip
+ \normalbaselines
+ \setbox\strutbox =\hbox{%
+ \vrule width0pt height\strutheightpercent\baselineskip
+ depth \strutdepthpercent \baselineskip
+ }%
+}
+
+% @| inserts a changebar to the left of the current line. It should
+% surround any changed text. This approach does *not* work if the
+% change spans more than two lines of output. To handle that, we would
+% have adopt a much more difficult approach (putting marks into the main
+% vertical list for the beginning and end of each change).
+%
+\def\|{%
+ % \vadjust can only be used in horizontal mode.
+ \leavevmode
+ %
+ % Append this vertical mode material after the current line in the output.
+ \vadjust{%
+ % We want to insert a rule with the height and depth of the current
+ % leading; that is exactly what \strutbox is supposed to record.
+ \vskip-\baselineskip
+ %
+ % \vadjust-items are inserted at the left edge of the type. So
+ % the \llap here moves out into the left-hand margin.
+ \llap{%
+ %
+ % For a thicker or thinner bar, change the `1pt'.
+ \vrule height\baselineskip width1pt
+ %
+ % This is the space between the bar and the text.
+ \hskip 12pt
+ }%
+ }%
+}
+
+% For a final copy, take out the rectangles
+% that mark overfull boxes (in case you have decided
+% that the text looks ok even though it passes the margin).
+%
+\def\finalout{\overfullrule=0pt}
+
+% @image. We use the macros from epsf.tex to support this.
+% If epsf.tex is not installed and @image is used, we complain.
+%
+% Check for and read epsf.tex up front. If we read it only at @image
+% time, we might be inside a group, and then its definitions would get
+% undone and the next image would fail.
+\openin 1 = epsf.tex
+\ifeof 1 \else
+ \closein 1
+ % Do not bother showing banner with post-v2.7 epsf.tex (available in
+ % doc/epsf.tex until it shows up on ctan).
+ \def\epsfannounce{\toks0 = }%
+ \input epsf.tex
+\fi
+%
+% We will only complain once about lack of epsf.tex.
+\newif\ifwarnednoepsf
+\newhelp\noepsfhelp{epsf.tex must be installed for images to
+ work. It is also included in the Texinfo distribution, or you can get
+ it from ftp://tug.org/tex/epsf.tex.}
+%
+\def\image#1{%
+ \ifx\epsfbox\undefined
+ \ifwarnednoepsf \else
+ \errhelp = \noepsfhelp
+ \errmessage{epsf.tex not found, images will be ignored}%
+ \global\warnednoepsftrue
+ \fi
+ \else
+ \imagexxx #1,,,\finish
+ \fi
+}
+%
+% Arguments to @image:
+% #1 is (mandatory) image filename; we tack on .eps extension.
+% #2 is (optional) width, #3 is (optional) height.
+% #4 is just the usual extra ignored arg for parsing this stuff.
+\def\imagexxx#1,#2,#3,#4\finish{%
+ \ifpdf
+ \centerline{\dopdfimage{#1}{#2}{#3}}%
+ \else
+ % \epsfbox itself resets \epsf?size at each figure.
+ \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
+ \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
+ \begingroup
+ \catcode`\^^M = 5 % in case we're inside an example
+ % If the image is by itself, center it.
+ \ifvmode
+ \nobreak\bigskip
+ % Usually we'll have text after the image which will insert
+ % \parskip glue, so insert it here too to equalize the space
+ % above and below.
+ \nobreak\vskip\parskip
+ \nobreak
+ \centerline{\epsfbox{#1.eps}}%
+ \bigbreak
+ \else
+ % In the middle of a paragraph, no extra space.
+ \epsfbox{#1.eps}%
+ \fi
+ \endgroup
+ \fi
+}
+
+
+\message{localization,}
+% and i18n.
+
+% @documentlanguage is usually given very early, just after
+% @setfilename. If done too late, it may not override everything
+% properly. Single argument is the language abbreviation.
+% It would be nice if we could set up a hyphenation file here.
+%
+\def\documentlanguage{\parsearg\dodocumentlanguage}
+\def\dodocumentlanguage#1{%
+ \tex % read txi-??.tex file in plain TeX.
+ % Read the file if it exists.
+ \openin 1 txi-#1.tex
+ \ifeof1
+ \errhelp = \nolanghelp
+ \errmessage{Cannot read language file txi-#1.tex}%
+ \let\temp = \relax
+ \else
+ \def\temp{\input txi-#1.tex }%
+ \fi
+ \temp
+ \endgroup
+}
+\newhelp\nolanghelp{The given language definition file cannot be found or
+is empty. Maybe you need to install it? In the current directory
+should work if nowhere else does.}
+
+
+% @documentencoding should change something in TeX eventually, most
+% likely, but for now just recognize it.
+\let\documentencoding = \comment
+
+
+% Page size parameters.
+%
+\newdimen\defaultparindent \defaultparindent = 15pt
+
+\chapheadingskip = 15pt plus 4pt minus 2pt
+\secheadingskip = 12pt plus 3pt minus 2pt
+\subsecheadingskip = 9pt plus 2pt minus 2pt
+
+% Prevent underfull vbox error messages.
+\vbadness = 10000
+
+% Don't be so finicky about underfull hboxes, either.
+\hbadness = 2000
+
+% Following George Bush, just get rid of widows and orphans.
+\widowpenalty=10000
+\clubpenalty=10000
+
+% Use TeX 3.0's \emergencystretch to help line breaking, but if we're
+% using an old version of TeX, don't do anything. We want the amount of
+% stretch added to depend on the line length, hence the dependence on
+% \hsize. We call this whenever the paper size is set.
+%
+\def\setemergencystretch{%
+ \ifx\emergencystretch\thisisundefined
+ % Allow us to assign to \emergencystretch anyway.
+ \def\emergencystretch{\dimen0}%
+ \else
+ \emergencystretch = .15\hsize
+ \fi
+}
+
+% Parameters in order: 1) textheight; 2) textwidth; 3) voffset;
+% 4) hoffset; 5) binding offset; 6) topskip. Then whoever calls us can
+% set \parskip and call \setleading for \baselineskip.
+%
+\def\internalpagesizes#1#2#3#4#5#6{%
+ \voffset = #3\relax
+ \topskip = #6\relax
+ \splittopskip = \topskip
+ %
+ \vsize = #1\relax
+ \advance\vsize by \topskip
+ \outervsize = \vsize
+ \advance\outervsize by 2\topandbottommargin
+ \pageheight = \vsize
+ %
+ \hsize = #2\relax
+ \outerhsize = \hsize
+ \advance\outerhsize by 0.5in
+ \pagewidth = \hsize
+ %
+ \normaloffset = #4\relax
+ \bindingoffset = #5\relax
+ %
+ \parindent = \defaultparindent
+ \setemergencystretch
+}
+
+% @letterpaper (the default).
+\def\letterpaper{{\globaldefs = 1
+ \parskip = 3pt plus 2pt minus 1pt
+ \setleading{13.2pt}%
+ %
+ % If page is nothing but text, make it come out even.
+ \internalpagesizes{46\baselineskip}{6in}{\voffset}{.25in}{\bindingoffset}{36pt}%
+}}
+
+% Use @smallbook to reset parameters for 7x9.5 (or so) format.
+\def\smallbook{{\globaldefs = 1
+ \parskip = 2pt plus 1pt
+ \setleading{12pt}%
+ %
+ \internalpagesizes{7.5in}{5.in}{\voffset}{.25in}{\bindingoffset}{16pt}%
+ %
+ \lispnarrowing = 0.3in
+ \tolerance = 700
+ \hfuzz = 1pt
+ \contentsrightmargin = 0pt
+ \deftypemargin = 0pt
+ \defbodyindent = .5cm
+ %
+ \let\smalldisplay = \smalldisplayx
+ \let\smallexample = \smalllispx
+ \let\smallformat = \smallformatx
+ \let\smalllisp = \smalllispx
+}}
+
+% Use @afourpaper to print on European A4 paper.
+\def\afourpaper{{\globaldefs = 1
+ \setleading{12pt}%
+ \parskip = 3pt plus 2pt minus 1pt
+ %
+ \internalpagesizes{53\baselineskip}{160mm}{\voffset}{4mm}{\bindingoffset}{44pt}%
+ %
+ \tolerance = 700
+ \hfuzz = 1pt
+}}
+
+% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin
+% 29mm, hence bottom margin 28mm, nominal side margin 3cm.
+\def\afourlatex{{\globaldefs = 1
+ \setleading{13.6pt}%
+ %
+ \afourpaper
+ \internalpagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm}%
+ %
+ \globaldefs = 0
+}}
+
+% Use @afourwide to print on European A4 paper in wide format.
+\def\afourwide{%
+ \afourpaper
+ \internalpagesizes{6.5in}{9.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}%
+ %
+ \globaldefs = 0
+}
+
+% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
+% Perhaps we should allow setting the margins, \topskip, \parskip,
+% and/or leading, also. Or perhaps we should compute them somehow.
+%
+\def\pagesizes{\parsearg\pagesizesxxx}
+\def\pagesizesxxx#1{\pagesizesyyy #1,,\finish}
+\def\pagesizesyyy#1,#2,#3\finish{{%
+ \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi
+ \globaldefs = 1
+ %
+ \parskip = 3pt plus 2pt minus 1pt
+ \setleading{13.2pt}%
+ %
+ \internalpagesizes{#1}{\hsize}{\voffset}{\normaloffset}{\bindingoffset}{44pt}%
+}}
+
+% Set default to letter.
+%
+\letterpaper
+
+
+\message{and turning on texinfo input format.}
+
+% Define macros to output various characters with catcode for normal text.
+\catcode`\"=\other
+\catcode`\~=\other
+\catcode`\^=\other
+\catcode`\_=\other
+\catcode`\|=\other
+\catcode`\<=\other
+\catcode`\>=\other
+\catcode`\+=\other
+\catcode`\$=\other
+\def\normaldoublequote{"}
+\def\normaltilde{~}
+\def\normalcaret{^}
+\def\normalunderscore{_}
+\def\normalverticalbar{|}
+\def\normalless{<}
+\def\normalgreater{>}
+\def\normalplus{+}
+\def\normaldollar{$}
+
+% This macro is used to make a character print one way in ttfont
+% where it can probably just be output, and another way in other fonts,
+% where something hairier probably needs to be done.
+%
+% #1 is what to print if we are indeed using \tt; #2 is what to print
+% otherwise. Since all the Computer Modern typewriter fonts have zero
+% interword stretch (and shrink), and it is reasonable to expect all
+% typewriter fonts to have this, we can check that font parameter.
+%
+\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}
+
+% Same as above, but check for italic font. Actually this also catches
+% non-italic slanted fonts since it is impossible to distinguish them from
+% italic fonts. But since this is only used by $ and it uses \sl anyway
+% this is not a problem.
+\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}
+
+% Turn off all special characters except @
+% (and those which the user can use as if they were ordinary).
+% Most of these we simply print from the \tt font, but for some, we can
+% use math or other variants that look better in normal text.
+
+\catcode`\"=\active
+\def\activedoublequote{{\tt\char34}}
+\let"=\activedoublequote
+\catcode`\~=\active
+\def~{{\tt\char126}}
+\chardef\hat=`\^
+\catcode`\^=\active
+\def^{{\tt \hat}}
+
+\catcode`\_=\active
+\def_{\ifusingtt\normalunderscore\_}
+% Subroutine for the previous macro.
+\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}}
+
+\catcode`\|=\active
+\def|{{\tt\char124}}
+\chardef \less=`\<
+\catcode`\<=\active
+\def<{{\tt \less}}
+\chardef \gtr=`\>
+\catcode`\>=\active
+\def>{{\tt \gtr}}
+\catcode`\+=\active
+\def+{{\tt \char 43}}
+\catcode`\$=\active
+\def${\ifusingit{{\sl\$}}\normaldollar}
+%\catcode 27=\active
+%\def^^[{$\diamondsuit$}
+
+% Set up an active definition for =, but don't enable it most of the time.
+{\catcode`\==\active
+\global\def={{\tt \char 61}}}
+
+\catcode`+=\active
+\catcode`\_=\active
+
+% If a .fmt file is being used, characters that might appear in a file
+% name cannot be active until we have parsed the command line.
+% So turn them off again, and have \everyjob (or @setfilename) turn them on.
+% \otherifyactive is called near the end of this file.
+\def\otherifyactive{\catcode`+=\other \catcode`\_=\other}
+
+\catcode`\@=0
+
+% \rawbackslashxx output one backslash character in current font
+\global\chardef\rawbackslashxx=`\\
+%{\catcode`\\=\other
+%@gdef@rawbackslashxx{\}}
+
+% \rawbackslash redefines \ as input to do \rawbackslashxx.
+{\catcode`\\=\active
+@gdef@rawbackslash{@let\=@rawbackslashxx }}
+
+% \normalbackslash outputs one backslash in fixed width font.
+\def\normalbackslash{{\tt\rawbackslashxx}}
+
+% \catcode 17=0 % Define control-q
+\catcode`\\=\active
+
+% Used sometimes to turn off (effectively) the active characters
+% even after parsing them.
+@def@turnoffactive{@let"=@normaldoublequote
+@let\=@realbackslash
+@let~=@normaltilde
+@let^=@normalcaret
+@let_=@normalunderscore
+@let|=@normalverticalbar
+@let<=@normalless
+@let>=@normalgreater
+@let+=@normalplus
+@let$=@normaldollar}
+
+@def@normalturnoffactive{@let"=@normaldoublequote
+@let\=@normalbackslash
+@let~=@normaltilde
+@let^=@normalcaret
+@let_=@normalunderscore
+@let|=@normalverticalbar
+@let<=@normalless
+@let>=@normalgreater
+@let+=@normalplus
+@let$=@normaldollar}
+
+% Make _ and + \other characters, temporarily.
+% This is canceled by @fixbackslash.
+@otherifyactive
+
+% If a .fmt file is being used, we don't want the `\input texinfo' to show up.
+% That is what \eatinput is for; after that, the `\' should revert to printing
+% a backslash.
+%
+@gdef@eatinput input texinfo{@fixbackslash}
+@global@let\ = @eatinput
+
+% On the other hand, perhaps the file did not have a `\input texinfo'. Then
+% the first `\{ in the file would cause an error. This macro tries to fix
+% that, assuming it is called before the first `\' could plausibly occur.
+% Also back turn on active characters that might appear in the input
+% file name, in case not using a pre-dumped format.
+%
+@gdef@fixbackslash{%
+ @ifx\@eatinput @let\ = @normalbackslash @fi
+ @catcode`+=@active
+ @catcode`@_=@active
+}
+
+% Say @foo, not \foo, in error messages.
+@escapechar = `@@
+
+% These look ok in all fonts, so just make them not special.
+@catcode`@& = @other
+@catcode`@# = @other
+@catcode`@% = @other
+
+@c Set initial fonts.
+@textfonts
+@rm
+
+
+@c Local variables:
+@c eval: (add-hook 'write-file-hooks 'time-stamp)
+@c page-delimiter: "^\\\\message"
+@c time-stamp-start: "def\\\\texinfoversion{"
+@c time-stamp-format: "%:y-%02m-%02d.%02H"
+@c time-stamp-end: "}"
+@c End:
projects / thirdparty / autoconf.git / commitdiff
