-This is ../info/standards.info, produced by makeinfo version 4.0 from
+This is ../info/standards.info, produced by makeinfo version 4.6 from
standards.texi.
START-INFO-DIR-ENTRY
translation approved by the Free Software Foundation.
\1f
-Indirect:
-standards.info-1: 980
-standards.info-2: 50916
-standards.info-3: 100599
-standards.info-4: 150168
+File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
+
+Version
+*******
+
+Last updated February 21, 2001.
+
+* 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::
+
+\1f
+File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
+
+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
+<bug-standards@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 `standards.texi' or `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 February
+21, 2001.
+
+ 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 `/pub/gnu/standards/'.
+The GNU Coding Standards are available there in several different
+formats: `standards.text', `standards.texi', `standards.info', and
+`standards.dvi'. The GNU Coding Standards are also available on the
+GNU World Wide Web server: `http://www.gnu.org/prep/standards_toc.html'.
+
+\1f
+File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
+
+Keeping Free Software Free
+**************************
+
+This node 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
+
+\1f
+File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
+
+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.
+
+\1f
+File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
+
+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. _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.
+
+\1f
+File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
+
+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.
+
+\1f
+File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
+
+General Program Design
+**********************
+
+This node discusses some of the issues you should take into account
+when designing your program.
+
+* Menu:
+
+* Source Language:: Which languges to use.
+* Compatibility:: Compatibility with other implementations
+* Using Extensions:: Using non-standard features
+* Standard C:: Using Standard C features
+
+\1f
+File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
+
+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 C, rather than the comparable
+alternatives.
+
+ But there are two exceptions to that conclusion:
+
+ * 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.
+
+ * 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.
+
+ 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). `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.
+
+\1f
+File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
+
+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 Standard C if Standard C specifies their behavior, and
+upward compatible with POSIX if POSIX specifies their behavior.
+
+ When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+ Standard C and POSIX prohibit many kinds of extensions. Feel free
+to make the extensions anyway, and include a `--ansi', `--posix', or
+`--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 POSIX if the
+environment variable `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,
+`vi' is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free `vi' clone, so we offer it.)
+
+ Additional useful features are welcome regardless of whether there
+is any precedent for them.
+
+\1f
+File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
+
+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" `INLINE' and
+define that as a macro to expand into either `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.
+
+\1f
+File: standards.info, Node: Standard C, Prev: Using Extensions, Up: Design Advice
+
+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 Standard C.
+
+ 1999 Standard C is not widespread yet, so please do not require its
+features in programs. It is ok to use its features if they are present.
+
+ 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,
+
+ int
+ foo (int x, int y)
+ ...
+
+write the definition in pre-standard style like this,
+
+ int
+ foo (x, y)
+ int x, y;
+ ...
+
+and use a separate declaration to specify the argument prototype:
+
+ int foo (int, int);
+
+ 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 `int'.
+If you think of an argument as being of a type narrower than `int',
+declare it as `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
+`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
+some machines; but you cannot use `int' instead, because `dev_t' is
+wider than `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
+`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:
+
+ /* Declare the prototype for a general external function. */
+ #if defined (__STDC__) || defined (WINDOWSNT)
+ #define P_(proto) proto
+ #else
+ #define P_(proto) ()
+ #endif
+
+\1f
+File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
+
+Program Behavior for All Programs
+*********************************
+
+This node 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
+* File Usage:: Which files to use, and where
+
+\1f
+File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
+
+Writing Robust Programs
+=======================
+
+Avoid arbitrary limits on the length or number of _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 _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 `perror' or
+equivalent) in _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 `malloc' or `realloc' to see if it returned
+zero. Check `realloc' even if you are making the block smaller; in a
+system that rounds block sizes to a power of 2, `realloc' may get a
+different block if you ask for less space.
+
+ In Unix, `realloc' can destroy the storage block if it returns zero.
+GNU `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 `malloc'.
+
+ You must expect `free' to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling `free'.
+
+ If `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 `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.
+
+ 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 `readdir' or some other high-level interface.
+These are supported compatibly by GNU.
+
+ The preferred signal handling facilities are the BSD variant of
+`signal', and the POSIX `sigaction' function; the alternative USG
+`signal' interface is an inferior design.
+
+ Nowadays, using the POSIX signal functions may be the easiest way to
+make a program portable. If you use `signal', then on GNU/Linux
+systems running GNU libc version 1, you should include `bsd/signal.h'
+instead of `signal.h', so as to get BSD behavior. It is up to you
+whether to support systems where `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.
+_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 `TMPDIR' environment
+variable; if that variable is defined, use the specified directory
+instead of `/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:
+
+ fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+
+or by using the `mkstemps' function from libiberty.
+
+ In bash, use `set -C' to avoid this problem.
+
+\1f
+File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
+
+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 `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 `_'. The `_' should be followed by
+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.
+
+\1f
+File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
+
+Formatting Error Messages
+=========================
+
+Error messages from compilers should look like this:
+
+ SOURCE-FILE-NAME:LINENO: MESSAGE
+
+If you want to mention the column number, use this format:
+
+ SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+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:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
+
+when there is an appropriate source file, or like this:
+
+ PROGRAM: MESSAGE
+
+when there is no relevant source file.
+
+ If you want to mention the column number, use this format:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+ 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 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.
+
+\1f
+File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
+
+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 `ls' or `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 `dir' program much like
+`ls' except that its default output format is always multi-column
+format.
+
+\1f
+File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
+
+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.
+
+\1f
+File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
+
+Standards for Command Line Interfaces
+=====================================
+
+It is a good idea to follow the POSIX guidelines for the command-line
+options of a program. The easiest way to do this is to use `getopt' to
+parse them. Note that the GNU version of `getopt' will normally permit
+options anywhere among the arguments unless the special argument `--'
+is used. This is not what 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
+`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 `--verbose'. To achieve this uniformity, look at the
+table of common long-option names when you choose the option names for
+your program (*note 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 `-o' or `--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: `--version' and
+`--help'.
+
+`--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:
+
+ GNU Emacs 19.30
+
+ The program's name should be a constant string; _don't_ compute it
+ from `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 `PATH'.
+
+ If the program is a subsidiary part of a larger package, mention
+ the package name in parentheses, like this:
+
+ emacsserver (GNU Emacs) 19.30
+
+ 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 *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:
+
+ 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.
+
+ 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.
+
+`--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 `--help' option's output there should be a line
+ that says where to mail bug reports. It should have this format:
+
+ Report bugs to MAILING-ADDRESS.
+
+\1f
+File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
+
+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 <bug-standards@gnu.org> a list of them, with their
+meanings, so we can update the table.
+
+`after-date'
+ `-N' in `tar'.
+
+`all'
+ `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
+
+`all-text'
+ `-a' in `diff'.
+
+`almost-all'
+ `-A' in `ls'.
+
+`append'
+ `-a' in `etags', `tee', `time'; `-r' in `tar'.
+
+`archive'
+ `-a' in `cp'.
+
+`archive-name'
+ `-n' in `shar'.
+
+`arglength'
+ `-l' in `m4'.
+
+`ascii'
+ `-a' in `diff'.
+
+`assign'
+ `-v' in `gawk'.
+
+`assume-new'
+ `-W' in Make.
+
+`assume-old'
+ `-o' in Make.
+
+`auto-check'
+ `-a' in `recode'.
+
+`auto-pager'
+ `-a' in `wdiff'.
+
+`auto-reference'
+ `-A' in `ptx'.
+
+`avoid-wraps'
+ `-n' in `wdiff'.
+
+`background'
+ For server programs, run in the background.
+
+`backward-search'
+ `-B' in `ctags'.
+
+`basename'
+ `-f' in `shar'.
+
+`batch'
+ Used in GDB.
+
+`baud'
+ Used in GDB.
+
+`before'
+ `-b' in `tac'.
+
+`binary'
+ `-b' in `cpio' and `diff'.
+
+`bits-per-code'
+ `-b' in `shar'.
+
+`block-size'
+ Used in `cpio' and `tar'.
+
+`blocks'
+ `-b' in `head' and `tail'.
+
+`break-file'
+ `-b' in `ptx'.
+
+`brief'
+ Used in various programs to make output shorter.
+
+`bytes'
+ `-c' in `head', `split', and `tail'.
+
+`c++'
+ `-C' in `etags'.
+
+`catenate'
+ `-A' in `tar'.
+
+`cd'
+ Used in various programs to specify the directory to use.
+
+`changes'
+ `-c' in `chgrp' and `chown'.
+
+`classify'
+ `-F' in `ls'.
+
+`colons'
+ `-c' in `recode'.
+
+`command'
+ `-c' in `su'; `-x' in GDB.
+
+`compare'
+ `-d' in `tar'.
+
+`compat'
+ Used in `gawk'.
+
+`compress'
+ `-Z' in `tar' and `shar'.
+
+`concatenate'
+ `-A' in `tar'.
+
+`confirmation'
+ `-w' in `tar'.
+
+`context'
+ Used in `diff'.
+
+`copyleft'
+ `-W copyleft' in `gawk'.
+
+`copyright'
+ `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
+
+`core'
+ Used in GDB.
+
+`count'
+ `-q' in `who'.
+
+`count-links'
+ `-l' in `du'.
+
+`create'
+ Used in `tar' and `cpio'.
+
+`cut-mark'
+ `-c' in `shar'.
+
+`cxref'
+ `-x' in `ctags'.
+
+`date'
+ `-d' in `touch'.
+
+`debug'
+ `-d' in Make and `m4'; `-t' in Bison.
+
+`define'
+ `-D' in `m4'.
+
+`defines'
+ `-d' in Bison and `ctags'.
+
+`delete'
+ `-D' in `tar'.
+
+`dereference'
+ `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
+
+`dereference-args'
+ `-D' in `du'.
+
+`device'
+ Specify an I/O device (special file name).
+
+`diacritics'
+ `-d' in `recode'.
+
+`dictionary-order'
+ `-d' in `look'.
+
+`diff'
+ `-d' in `tar'.
+
+`digits'
+ `-n' in `csplit'.
+
+`directory'
+ Specify the directory to use, in various programs. In `ls', it
+ means to show directories themselves rather than their contents.
+ In `rm' and `ln', it means to not treat links to directories
+ specially.
+
+`discard-all'
+ `-x' in `strip'.
+
+`discard-locals'
+ `-X' in `strip'.
+
+`dry-run'
+ `-n' in Make.
+
+`ed'
+ `-e' in `diff'.
+
+`elide-empty-files'
+ `-z' in `csplit'.
+
+`end-delete'
+ `-x' in `wdiff'.
+
+`end-insert'
+ `-z' in `wdiff'.
+
+`entire-new-file'
+ `-N' in `diff'.
+
+`environment-overrides'
+ `-e' in Make.
+
+`eof'
+ `-e' in `xargs'.
+
+`epoch'
+ Used in GDB.
+
+`error-limit'
+ Used in `makeinfo'.
+
+`error-output'
+ `-o' in `m4'.
+
+`escape'
+ `-b' in `ls'.
+
+`exclude-from'
+ `-X' in `tar'.
+
+`exec'
+ Used in GDB.
+
+`exit'
+ `-x' in `xargs'.
+
+`exit-0'
+ `-e' in `unshar'.
+
+`expand-tabs'
+ `-t' in `diff'.
+
+`expression'
+ `-e' in `sed'.
+
+`extern-only'
+ `-g' in `nm'.
+
+`extract'
+ `-i' in `cpio'; `-x' in `tar'.
+
+`faces'
+ `-f' in `finger'.
+
+`fast'
+ `-f' in `su'.
+
+`fatal-warnings'
+ `-E' in `m4'.
+
+`file'
+ `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
+ in `touch'.
+
+`field-separator'
+ `-F' in `gawk'.
+
+`file-prefix'
+ `-b' in Bison.
+
+`file-type'
+ `-F' in `ls'.
+
+`files-from'
+ `-T' in `tar'.
+
+`fill-column'
+ Used in `makeinfo'.
+
+`flag-truncation'
+ `-F' in `ptx'.
+
+`fixed-output-files'
+ `-y' in Bison.
+
+`follow'
+ `-f' in `tail'.
+
+`footnote-style'
+ Used in `makeinfo'.
+
+`force'
+ `-f' in `cp', `ln', `mv', and `rm'.
+
+`force-prefix'
+ `-F' in `shar'.
+
+`foreground'
+ For server programs, run in the foreground; in other words, don't
+ do anything special to run the server in the background.
+
+`format'
+ Used in `ls', `time', and `ptx'.
+
+`freeze-state'
+ `-F' in `m4'.
+
+`fullname'
+ Used in GDB.
+
+`gap-size'
+ `-g' in `ptx'.
+
+`get'
+ `-x' in `tar'.
+
+`graphic'
+ `-i' in `ul'.
+
+`graphics'
+ `-g' in `recode'.
+
+`group'
+ `-g' in `install'.
+
+`gzip'
+ `-z' in `tar' and `shar'.
+
+`hashsize'
+ `-H' in `m4'.
+
+`header'
+ `-h' in `objdump' and `recode'
+
+`heading'
+ `-H' in `who'.
+
+`help'
+ Used to ask for brief usage information.
+
+`here-delimiter'
+ `-d' in `shar'.
+
+`hide-control-chars'
+ `-q' in `ls'.
+
+`html'
+ In `makeinfo', output HTML.
+
+`idle'
+ `-u' in `who'.
+
+`ifdef'
+ `-D' in `diff'.
+
+`ignore'
+ `-I' in `ls'; `-x' in `recode'.
+
+`ignore-all-space'
+ `-w' in `diff'.
+
+`ignore-backups'
+ `-B' in `ls'.
+
+`ignore-blank-lines'
+ `-B' in `diff'.
+
+`ignore-case'
+ `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
+
+`ignore-errors'
+ `-i' in Make.
+
+`ignore-file'
+ `-i' in `ptx'.
+
+`ignore-indentation'
+ `-I' in `etags'.
+
+`ignore-init-file'
+ `-f' in Oleo.
+
+`ignore-interrupts'
+ `-i' in `tee'.
+
+`ignore-matching-lines'
+ `-I' in `diff'.
+
+`ignore-space-change'
+ `-b' in `diff'.
+
+`ignore-zeros'
+ `-i' in `tar'.
+
+`include'
+ `-i' in `etags'; `-I' in `m4'.
+
+`include-dir'
+ `-I' in Make.
+
+`incremental'
+ `-G' in `tar'.
+
+`info'
+ `-i', `-l', and `-m' in Finger.
+
+`init-file'
+ In some programs, specify the name of the file to read as the
+ user's init file.
+
+`initial'
+ `-i' in `expand'.
+
+`initial-tab'
+ `-T' in `diff'.
+
+`inode'
+ `-i' in `ls'.
+
+`interactive'
+ `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
+ `-w' in `tar'.
+
+`intermix-type'
+ `-p' in `shar'.
+
+`iso-8601'
+ Used in `date'
+
+`jobs'
+ `-j' in Make.
+
+`just-print'
+ `-n' in Make.
+
+`keep-going'
+ `-k' in Make.
+
+`keep-files'
+ `-k' in `csplit'.
+
+`kilobytes'
+ `-k' in `du' and `ls'.
+
+`language'
+ `-l' in `etags'.
+
+`less-mode'
+ `-l' in `wdiff'.
+
+`level-for-gzip'
+ `-g' in `shar'.
+
+`line-bytes'
+ `-C' in `split'.
+
+`lines'
+ Used in `split', `head', and `tail'.
+
+`link'
+ `-l' in `cpio'.
+
+`lint'
+`lint-old'
+ Used in `gawk'.
+
+`list'
+ `-t' in `cpio'; `-l' in `recode'.
+
+`list'
+ `-t' in `tar'.
+
+`literal'
+ `-N' in `ls'.
+
+`load-average'
+ `-l' in Make.
+
+`login'
+ Used in `su'.
+
+`machine'
+ No listing of which programs already use this; someone should
+ check to see if any actually do, and tell <gnu@gnu.org>.
+
+`macro-name'
+ `-M' in `ptx'.
+
+`mail'
+ `-m' in `hello' and `uname'.
+
+`make-directories'
+ `-d' in `cpio'.
+
+`makefile'
+ `-f' in Make.
+
+`mapped'
+ Used in GDB.
+
+`max-args'
+ `-n' in `xargs'.
+
+`max-chars'
+ `-n' in `xargs'.
+
+`max-lines'
+ `-l' in `xargs'.
+
+`max-load'
+ `-l' in Make.
+
+`max-procs'
+ `-P' in `xargs'.
+
+`mesg'
+ `-T' in `who'.
+
+`message'
+ `-T' in `who'.
+
+`minimal'
+ `-d' in `diff'.
+
+`mixed-uuencode'
+ `-M' in `shar'.
+
+`mode'
+ `-m' in `install', `mkdir', and `mkfifo'.
+
+`modification-time'
+ `-m' in `tar'.
+
+`multi-volume'
+ `-M' in `tar'.
+
+`name-prefix'
+ `-a' in Bison.
+
+`nesting-limit'
+ `-L' in `m4'.
+
+`net-headers'
+ `-a' in `shar'.
+
+`new-file'
+ `-W' in Make.
+
+`no-builtin-rules'
+ `-r' in Make.
+
+`no-character-count'
+ `-w' in `shar'.
+
+`no-check-existing'
+ `-x' in `shar'.
+
+`no-common'
+ `-3' in `wdiff'.
+
+`no-create'
+ `-c' in `touch'.
+
+`no-defines'
+ `-D' in `etags'.
+
+`no-deleted'
+ `-1' in `wdiff'.
+
+`no-dereference'
+ `-d' in `cp'.
+
+`no-inserted'
+ `-2' in `wdiff'.
+
+`no-keep-going'
+ `-S' in Make.
+
+`no-lines'
+ `-l' in Bison.
+
+`no-piping'
+ `-P' in `shar'.
+
+`no-prof'
+ `-e' in `gprof'.
+
+`no-regex'
+ `-R' in `etags'.
+
+`no-sort'
+ `-p' in `nm'.
+
+`no-split'
+ Used in `makeinfo'.
+
+`no-static'
+ `-a' in `gprof'.
+
+`no-time'
+ `-E' in `gprof'.
+
+`no-timestamp'
+ `-m' in `shar'.
+
+`no-validate'
+ Used in `makeinfo'.
+
+`no-wait'
+ Used in `emacsclient'.
+
+`no-warn'
+ Used in various programs to inhibit warnings.
+
+`node'
+ `-n' in `info'.
+
+`nodename'
+ `-n' in `uname'.
+
+`nonmatching'
+ `-f' in `cpio'.
+
+`nstuff'
+ `-n' in `objdump'.
+
+`null'
+ `-0' in `xargs'.
+
+`number'
+ `-n' in `cat'.
+
+`number-nonblank'
+ `-b' in `cat'.
+
+`numeric-sort'
+ `-n' in `nm'.
+
+`numeric-uid-gid'
+ `-n' in `cpio' and `ls'.
+
+`nx'
+ Used in GDB.
+
+`old-archive'
+ `-o' in `tar'.
+
+`old-file'
+ `-o' in Make.
+
+`one-file-system'
+ `-l' in `tar', `cp', and `du'.
+
+`only-file'
+ `-o' in `ptx'.
+
+`only-prof'
+ `-f' in `gprof'.
+
+`only-time'
+ `-F' in `gprof'.
+
+`options'
+ `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
+
+`output'
+ In various programs, specify the output file name.
+
+`output-prefix'
+ `-o' in `shar'.
+
+`override'
+ `-o' in `rm'.
+
+`overwrite'
+ `-c' in `unshar'.
+
+`owner'
+ `-o' in `install'.
+
+`paginate'
+ `-l' in `diff'.
+
+`paragraph-indent'
+ Used in `makeinfo'.
+
+`parents'
+ `-p' in `mkdir' and `rmdir'.
+
+`pass-all'
+ `-p' in `ul'.
+
+`pass-through'
+ `-p' in `cpio'.
+
+`port'
+ `-P' in `finger'.
+
+`portability'
+ `-c' in `cpio' and `tar'.
+
+`posix'
+ Used in `gawk'.
+
+`prefix-builtins'
+ `-P' in `m4'.
+
+`prefix'
+ `-f' in `csplit'.
+
+`preserve'
+ Used in `tar' and `cp'.
+
+`preserve-environment'
+ `-p' in `su'.
+
+`preserve-modification-time'
+ `-m' in `cpio'.
+
+`preserve-order'
+ `-s' in `tar'.
+
+`preserve-permissions'
+ `-p' in `tar'.
+
+`print'
+ `-l' in `diff'.
+
+`print-chars'
+ `-L' in `cmp'.
+
+`print-data-base'
+ `-p' in Make.
+
+`print-directory'
+ `-w' in Make.
+
+`print-file-name'
+ `-o' in `nm'.
+
+`print-symdefs'
+ `-s' in `nm'.
+
+`printer'
+ `-p' in `wdiff'.
+
+`prompt'
+ `-p' in `ed'.
+
+`proxy'
+ Specify an HTTP proxy.
+
+`query-user'
+ `-X' in `shar'.
+
+`question'
+ `-q' in Make.
+
+`quiet'
+ Used in many programs to inhibit the usual output. *Note:* every
+ program accepting `--quiet' should accept `--silent' as a synonym.
+
+`quiet-unshar'
+ `-Q' in `shar'
+
+`quote-name'
+ `-Q' in `ls'.
+
+`rcs'
+ `-n' in `diff'.
+
+`re-interval'
+ Used in `gawk'.
+
+`read-full-blocks'
+ `-B' in `tar'.
+
+`readnow'
+ Used in GDB.
+
+`recon'
+ `-n' in Make.
+
+`record-number'
+ `-R' in `tar'.
+
+`recursive'
+ Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
+
+`reference-limit'
+ Used in `makeinfo'.
+
+`references'
+ `-r' in `ptx'.
+
+`regex'
+ `-r' in `tac' and `etags'.
+
+`release'
+ `-r' in `uname'.
+
+`reload-state'
+ `-R' in `m4'.
+
+`relocation'
+ `-r' in `objdump'.
+
+`rename'
+ `-r' in `cpio'.
+
+`replace'
+ `-i' in `xargs'.
+
+`report-identical-files'
+ `-s' in `diff'.
+
+`reset-access-time'
+ `-a' in `cpio'.
+
+`reverse'
+ `-r' in `ls' and `nm'.
+
+`reversed-ed'
+ `-f' in `diff'.
+
+`right-side-defs'
+ `-R' in `ptx'.
+
+`same-order'
+ `-s' in `tar'.
+
+`same-permissions'
+ `-p' in `tar'.
+
+`save'
+ `-g' in `stty'.
+
+`se'
+ Used in GDB.
+
+`sentence-regexp'
+ `-S' in `ptx'.
+
+`separate-dirs'
+ `-S' in `du'.
+
+`separator'
+ `-s' in `tac'.
+
+`sequence'
+ Used by `recode' to chose files or pipes for sequencing passes.
+
+`shell'
+ `-s' in `su'.
+
+`show-all'
+ `-A' in `cat'.
+
+`show-c-function'
+ `-p' in `diff'.
+
+`show-ends'
+ `-E' in `cat'.
+
+`show-function-line'
+ `-F' in `diff'.
+
+`show-tabs'
+ `-T' in `cat'.
+
+`silent'
+ Used in many programs to inhibit the usual output. *Note:* every
+ program accepting `--silent' should accept `--quiet' as a synonym.
+
+`size'
+ `-s' in `ls'.
+
+`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.
+
+`sort'
+ Used in `ls'.
+
+`source'
+ `-W source' in `gawk'.
+
+`sparse'
+ `-S' in `tar'.
+
+`speed-large-files'
+ `-H' in `diff'.
+
+`split-at'
+ `-E' in `unshar'.
+
+`split-size-limit'
+ `-L' in `shar'.
+
+`squeeze-blank'
+ `-s' in `cat'.
+
+`start-delete'
+ `-w' in `wdiff'.
+
+`start-insert'
+ `-y' in `wdiff'.
+
+`starting-file'
+ Used in `tar' and `diff' to specify which file within a directory
+ to start processing with.
+
+`statistics'
+ `-s' in `wdiff'.
+
+`stdin-file-list'
+ `-S' in `shar'.
+
+`stop'
+ `-S' in Make.
+
+`strict'
+ `-s' in `recode'.
+
+`strip'
+ `-s' in `install'.
+
+`strip-all'
+ `-s' in `strip'.
+
+`strip-debug'
+ `-S' in `strip'.
+
+`submitter'
+ `-s' in `shar'.
+
+`suffix'
+ `-S' in `cp', `ln', `mv'.
+
+`suffix-format'
+ `-b' in `csplit'.
+
+`sum'
+ `-s' in `gprof'.
+
+`summarize'
+ `-s' in `du'.
+
+`symbolic'
+ `-s' in `ln'.
+
+`symbols'
+ Used in GDB and `objdump'.
+
+`synclines'
+ `-s' in `m4'.
+
+`sysname'
+ `-s' in `uname'.
+
+`tabs'
+ `-t' in `expand' and `unexpand'.
+
+`tabsize'
+ `-T' in `ls'.
+
+`terminal'
+ `-T' in `tput' and `ul'. `-t' in `wdiff'.
+
+`text'
+ `-a' in `diff'.
+
+`text-files'
+ `-T' in `shar'.
+
+`time'
+ Used in `ls' and `touch'.
+
+`timeout'
+ Specify how long to wait before giving up on some operation.
+
+`to-stdout'
+ `-O' in `tar'.
+
+`total'
+ `-c' in `du'.
+
+`touch'
+ `-t' in Make, `ranlib', and `recode'.
+
+`trace'
+ `-t' in `m4'.
+
+`traditional'
+ `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
+ and `ptx'.
+
+`tty'
+ Used in GDB.
+
+`typedefs'
+ `-t' in `ctags'.
+
+`typedefs-and-c++'
+ `-T' in `ctags'.
+
+`typeset-mode'
+ `-t' in `ptx'.
+
+`uncompress'
+ `-z' in `tar'.
+
+`unconditional'
+ `-u' in `cpio'.
+
+`undefine'
+ `-U' in `m4'.
+
+`undefined-only'
+ `-u' in `nm'.
+
+`update'
+ `-u' in `cp', `ctags', `mv', `tar'.
+
+`usage'
+ Used in `gawk'; same as `--help'.
+
+`uuencode'
+ `-B' in `shar'.
+
+`vanilla-operation'
+ `-V' in `shar'.
+
+`verbose'
+ Print more information about progress. Many programs support this.
+
+`verify'
+ `-W' in `tar'.
+
+`version'
+ Print the version number.
+
+`version-control'
+ `-V' in `cp', `ln', `mv'.
+
+`vgrind'
+ `-v' in `ctags'.
+
+`volume'
+ `-V' in `tar'.
+
+`what-if'
+ `-W' in Make.
+
+`whole-size-limit'
+ `-l' in `shar'.
+
+`width'
+ `-w' in `ls' and `ptx'.
+
+`word-regexp'
+ `-W' in `ptx'.
+
+`writable'
+ `-T' in `who'.
+
+`zeros'
+ `-z' in `gprof'.
+
+\1f
+File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
+
+Memory Usage
+============
+
+If a program 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 `cat' or `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 `malloc' returns zero.
+
+\1f
+File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
+
+File Usage
+==========
+
+Programs should be prepared to operate when `/usr' and `/etc' are
+read-only file systems. Thus, if the program manages log files, lock
+files, backup files, score files, or any other files which are modified
+for internal purposes, these files should not be stored in `/usr' or
+`/etc'.
+
+ There are two exceptions. `/etc' is used to store system
+configuration information; it is reasonable for a program to modify
+files in `/etc' when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+\1f
+File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
+
+Making The Best Use of C
+************************
+
+This node 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 `mmap'.
+
+\1f
+File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
+
+Formatting Your 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:
+
+ static char *
+ concat (s1, s2) /* Name starts in column zero here */
+ char *s1, *s2;
+ { /* Open brace in column zero here */
+ ...
+ }
+
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+ static char *
+ concat (char *s1, char *s2)
+ {
+ ...
+ }
+
+ In Standard C, if the arguments don't fit nicely on one line, split
+it like this:
+
+ int
+ lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+ ...
+
+ The rest of this section gives our recommendations for other aspects
+of C formatting style, which is also the default style of the `indent'
+program in version 1.2 and newer. It corresponds to the options
+
+ -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+ -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+
+ We don't think of these recommendations 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:
+
+ if (x < foo (y, z))
+ haha = bar[4] + 5;
+ else
+ {
+ while (z)
+ {
+ haha += foo (z, z);
+ z--;
+ }
+ return ++x + bar ();
+ }
+
+ 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:
+
+ if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+
+ Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+ mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+
+ Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+ mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+
+ Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+ 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;
+
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+ 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);
+
+ Format do-while statements like this:
+
+ do
+ {
+ a = foo (a);
+ }
+ while (a > 0);
+
+ 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.
+
+\1f
+File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
+
+Commenting Your Work
+====================
+
+Every program should start with a comment saying briefly what it is for.
+Example: `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 `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 ...").
+
+ 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:
+
+ /* Nonzero means truncate lines in the display;
+ zero means continue them. */
+ int truncate_lines;
+
+ Every `#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, _including its
+sense_. `#else' should have a comment describing the condition _and
+sense_ of the code that follows. For example:
+
+ #ifdef foo
+ ...
+ #else /* not foo */
+ ...
+ #endif /* not foo */
+ #ifdef foo
+ ...
+ #endif /* foo */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+ #ifndef foo
+ ...
+ #else /* foo */
+ ...
+ #endif /* foo */
+ #ifndef foo
+ ...
+ #endif /* not foo */
+
+\1f
+File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
+
+Clean Use of C Constructs
+=========================
+
+Please explicitly declare the types of all objects. For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return `int' rather than omitting the `int'.
+
+ Some programmers like to use the GCC `-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 `-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 `extern' declarations inside
+functions.
+
+ It used to be common practice to use the same local variables (with
+names like `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.
+
+ Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead of
+this:
+
+ int foo,
+ bar;
+
+write either this:
+
+ int foo, bar;
+
+or this:
+
+ int foo;
+ int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+ When you have an `if'-`else' statement nested in another `if'
+statement, always put braces around the `if'-`else'. Thus, never write
+like this:
+
+ if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+
+always like this:
+
+ if (foo)
+ {
+ if (bar)
+ win ();
+ else
+ lose ();
+ }
+
+ If you have an `if' statement nested inside of an `else' statement,
+either write `else if' on one line, like this,
+
+ if (foo)
+ ...
+ else if (bar)
+ ...
+
+with its `then'-part indented like the preceding `then'-part, or write
+the nested `if' within braces like this:
+
+ if (foo)
+ ...
+ else
+ {
+ if (bar)
+ ...
+ }
+
+ 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 `if'-conditions. For example, don't
+write this:
+
+ if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+
+instead, write this:
+
+ foo = (char *) malloc (sizeof *foo);
+ if (foo == 0)
+ fatal ("virtual memory exhausted");
+
+ Don't make the program ugly to placate `lint'. Please don't insert
+any casts to `void'. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+\1f
+File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
+
+Naming 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 `enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+ For example, you should use names like `ignore_space_change_flag';
+don't use names like `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,
+
+ /* Ignore changes in horizontal whitespace (-b). */
+ int ignore_space_change_flag;
+
+ When you want to define names with constant integer values, use
+`enum' rather than `#define'. GDB knows about enumeration constants.
+
+ You might want to make sure that none of the file names would
+conflict the files were loaded onto an MS-DOS file system which
+shortens the names. You can use the program `doschk' to test for this.
+
+ Some GNU programs were designed to limit themselves to file names of
+14 characters or less, to avoid file name conflicts if they are read
+into older System V systems. Please preserve this feature in the
+existing GNU programs that have it, but there is no need to do this in
+new GNU programs. `doschk' also reports file names longer than 14
+characters.
+
+\1f
+File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
+
+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 CPU. So
+the kinds of portability that are absolutely necessary are quite
+limited. But it is important to support Linux-based GNU systems, since
+they are the form of GNU that is popular.
+
+ Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to. Supporting a variety of Unix-like systems is desirable, although
+not paramount. It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+ 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 (`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" `_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 _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.
+
+\1f
+File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
+
+Portability between CPUs
+========================
+
+Even GNU systems will differ because of differences among 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
+`int' will be less than 32 bits. We don't support 16-bit machines in
+GNU.
+
+ Similarly, don't make any effort to cater to the possibility that
+`long' will be smaller than predefined types like `size_t'. For
+example, the following code is ok:
+
+ printf ("size = %lu\n", (unsigned long) sizeof array);
+ printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+
+ 1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64. We will
+leave it to those who want to port GNU programs to that environment to
+figure out how to do it.
+
+ Predefined file-size types like `off_t' are an exception: they are
+longer than `long' on many platforms, so code like the above won't work
+with them. One way to print an `off_t' value portably is to print its
+digits yourself, one by one.
+
+ Don't assume that the address of an `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:
+
+ int c;
+ ...
+ while ((c = getchar()) != EOF)
+ write(file_descriptor, &c, 1);
+
+ 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 Standard C
+prototypes, 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 `printf' and friends:
+
+ error (s, a1, a2, a3)
+ char *s;
+ char *a1, *a2, *a3;
+ {
+ fprintf (stderr, "error: ");
+ fprintf (stderr, s, a1, a2, a3);
+ }
+
+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 _not_ to use a prototype for such
+functions.
+
+ If you have decided to use Standard C, then you can instead define
+`error' using `stdarg.h', and pass the arguments along to `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 `malloc' starts far away
+from zero.
+
+\1f
+File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
+
+Calling System Functions
+========================
+
+C implementations differ substantially. 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.
+
+ * Don't use the return value of `sprintf'. It returns the number of
+ characters written on some systems, but not on all systems.
+
+ * Be aware that `vfprintf' is not always available.
+
+ * `main' should be declared to return type `int'. It should
+ terminate either by calling `exit' or by returning the integer
+ status code; make sure it cannot ever return an undefined value.
+
+ * 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.
+
+ * 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.
+
+ * In particular, don't unconditionally declare `malloc' or `realloc'.
+
+ Most GNU programs use those functions just once, in functions
+ conventionally named `xmalloc' and `xrealloc'. These functions
+ call `malloc' and `realloc', respectively, and check the results.
+
+ Because `xmalloc' and `xrealloc' are defined in your program, you
+ can declare them in other files without any risk of type conflict.
+
+ On most systems, `int' is the same length as a pointer; thus, the
+ calls to `malloc' and `realloc' work fine. For the few
+ exceptional systems (mostly 64-bit machines), you can use
+ *conditionalized* declarations of `malloc' and `realloc'--or put
+ these declarations in configuration files specific to those
+ systems.
+
+ * The string functions require special treatment. Some Unix systems
+ have a header file `string.h'; others have `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.
+
+ * 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:
+
+ strcpy strncpy strcat strncat
+ strlen strcmp strncmp
+ strchr strrchr
+
+ 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 `int', and perhaps in other cases. It
+ is trivial to avoid using their values, so do that.
+
+ The compare functions and `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 *conditionally* on a few
+ systems.
+
+ The search functions must be declared to return `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 `index' and `rindex'; other systems use the names `strchr'
+ and `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 `strchr' and `strrchr'
+ for new programs, since those are the standard names.) Declare
+ both of those names as functions returning `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
+ `strchr' and `strrchr' throughout:
+
+ #ifndef HAVE_STRCHR
+ #define strchr index
+ #endif
+ #ifndef HAVE_STRRCHR
+ #define strrchr rindex
+ #endif
+
+ char *strchr ();
+ char *strrchr ();
+
+ Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
+defined in systems where the corresponding functions exist. One way to
+get them properly defined is to use Autoconf.
+
+\1f
+File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C
+
+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 `gettext' macro
+around each string that might need translation--like this:
+
+ printf (gettext ("Processing file `%s'..."));
+
+This permits GNU gettext to replace the string `"Processing file
+`%s'..."' with a translated version.
+
+ Once a program uses gettext, please make a point of writing calls to
+`gettext' when you add new strings that call for translation.
+
+ Using GNU gettext in a package involves specifying a "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, `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:
+
+ printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
+
+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,
+
+ printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
+
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way:
+
+ printf ((nfiles != 1 ? "%d files processed"
+ : "%d file processed"),
+ nfiles);
+
+This way, you can apply gettext to each of the two strings
+independently:
+
+ printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+
+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:
+
+ printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+
+Adding `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 `gettext'
+calls does the job straightfowardly if the code starts out like this:
+
+ printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
+
+\1f
+File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C
+
+Mmap
+====
+
+Don't assume that `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 `mmap' is to try it on the specific file for
+which you want to use it--and if `mmap' doesn't work, fall back on
+doing the job in another way using `read' and `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 `mmap', but
+some do not. It is important to make programs handle all these kinds
+of files.
+
+\1f
+File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
+
+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.
+* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
+* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
+* Manual Credits:: Giving credit to documentation contributors.
+* Printed Manuals:: Mentioning the printed 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.
+
+\1f
+File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
+
+GNU Manuals
+===========
+
+The preferred document format for the GNU system is the Texinfo
+formatting language. Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners. Texinfo
+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 `info' or the Emacs
+Info subsystem (`C-h i').
+
+ Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo. It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+ 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 _topic_. For example,
+instead of a manual for `diff' and a manual for `diff3', we have one
+manual for "comparison of files" which covers both of those programs,
+as well as `cmp'. By documenting these programs together, we can make
+the whole subject clearer.
+
+ The manual which discusses a program should certainly 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, _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.
+
+ To serve as a reference, a manual should have an Index that list all
+the functions, variables, options, and important concepts that are part
+of the program. One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+*Note Making Index Entries: (texinfo)Index Entries, and see *Note
+Defining the Entries of an Index: (texinfo)Indexing Commands.
+
+ 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, some 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 _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 activities punishable by law.
+
+\1f
+File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
+
+Doc Strings and Manuals
+=======================
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable. You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them--but you must not do it. That
+approach is a fundamental mistake. The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+ A documentation string needs to stand alone--when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+ The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection. Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables. The previous descriptions of functions and variables in the
+section will also have given information about the topic. A description
+written to stand alone would repeat some of that information; this
+redundance looks bad. Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+ The only good way to use documentation strings in writing a good
+manual is to use them as a source of information for writing good text.
+
+\1f
+File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
+
+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
+`PROGRAM Invocation' or `Invoking 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 `@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.
+
+ The `--usage' feature of the Info reader looks for such a node or
+menu item in order to find the relevant text, so it is essential for
+every Texinfo file to have one.
+
+ If one manual describes several programs, it should have such a node
+for each program described in the manual.
+
+\1f
+File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
+
+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.
+
+ See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
+of how to employ the GFDL.
+
+ Note that it is not obligatory to include a copy of the GNU GPL or
+GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
+can be a good idea to include the program's license in a large manual;
+in a short manual, whose size would be increased considerably by
+including the program's license, it is probably better not to include
+it.
+
+\1f
+File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
+
+Manual Credits
+==============
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual. If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+\1f
+File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
+
+Printed Manuals
+===============
+
+The FSF publishes some GNU manuals in printed form. To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it--for instance, with a link to the page
+<http://www.gnu.org/order/order.html>. This should not be included in
+the printed manual, though, because there it is redundant.
+
+ It is also useful to explain in the on-line forms of the manual how
+the user can print out the manual from the sources.
+
+\1f
+File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
+
+The NEWS File
+=============
+
+In addition to its manual, the package should have a file named `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 `NEWS' file gets very long, move some of the older items into
+a file named `ONEWS' and put a note at the end referring the user to
+that file.
+
+\1f
+File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
+
+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::
+
+\1f
+File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
+
+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 `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 `ChangeLog' file using `rcs2log'; in Emacs, the
+command `C-x v a' (`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 `ChangeLog' is with the Emacs
+command `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.
+
+\1f
+File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
+
+Style of Change Logs
+--------------------
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when, followed by
+descriptions of specific changes. (These examples are drawn from Emacs
+and GCC.)
+
+ 1998-08-17 Richard Stallman <rms@gnu.org>
+
+ * 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.
+
+ 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 `* register.el ({insert,jump-to}-register)'; this is
+not a good idea, since searching for `jump-to-register' or
+`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
+`)', rather than `,', and opening the continuation with `(' as in this
+example:
+
+ * keyboard.c (menu_bar_items, tool_bar_items)
+ (Fexecute_extended_command): Deal with `keymap' property.
+
+\1f
+File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
+
+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 to use the new
+calling sequence, 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"--like this:
+
+ * keyboard.c (Fcommand_execute): New arg SPECIAL.
+ All callers changed.
+
+ 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.
+
+\1f
+File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
+
+Conditional Changes
+-------------------
+
+C programs often contain compile-time `#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:
+
+ * xterm.c [SOLARIS2]: Include string.h.
+
+ Here is an entry describing a new definition which is entirely
+conditional. This new definition for the macro `FRAME_WINDOW_P' is
+used only when `HAVE_X_WINDOWS' is defined:
+
+ * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+
+ Here is an entry for a change within the function `init_display',
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
+
+ * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+
+ Here is an entry for a change that takes affect only when a certain
+macro is _not_ defined:
+
+ (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+
+\1f
+File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
+
+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 `sh-while-getopts' that deals
+with `sh' commands:
+
+ * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+ user-specified option string is empty.
+
+\1f
+File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
+
+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.
+
+\1f
+File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
+
+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.
+
+\1f
+File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
+
+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
+
+\1f
+File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
+
+How Configuration Should Work
+=============================
+
+Each GNU distribution should come with a shell script named
+`configure'. This script is given arguments which describe the kind of
+machine and system you want to compile the program for.
+
+ The `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
+`config.h' to the proper configuration file for the chosen system. If
+you use this technique, the distribution should _not_ contain a file
+named `config.h'. This is so that people won't be able to build the
+program without configuring it first.
+
+ Another thing that `configure' can do is to edit the Makefile. If
+you do this, the distribution should _not_ contain a file named
+`Makefile'. Instead, it should include a 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 `configure' does write the `Makefile', then `Makefile' should
+have a target named `Makefile' which causes `configure' to be rerun,
+setting up the same configuration that was set up last time. The files
+that `configure' reads should be listed as dependencies of `Makefile'.
+
+ All the files which are output from the `configure' script should
+have comments at the beginning explaining that they were generated
+automatically using `configure'. This is so that users won't think of
+trying to edit them by hand.
+
+ The `configure' script should write a file named `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 `configure' script should accept an option of the form
+`--srcdir=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 `--srcdir', then `configure' should
+check both `.' and `..' 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 `--srcdir' is by editing a
+definition of `VPATH' into the Makefile. Some rules may need to refer
+explicitly to the specified source directory. To make this possible,
+`configure' can add to the Makefile a variable named `srcdir' whose
+value is precisely the specified directory.
+
+ The `configure' script should also take an argument which specifies
+the type of system to build the program for. This argument should look
+like this:
+
+ CPU-COMPANY-SYSTEM
+
+ For example, a Sun 3 might be `m68k-sun-sunos4.1'.
+
+ The `configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
+would be a valid alias. For many programs, `vax-dec-ultrix' would be
+an alias for `vax-dec-bsd', simply because the differences between
+Ultrix and BSD are rarely noticeable, but a few programs might need to
+distinguish them.
+
+ There is a shell script called `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:
+
+`--enable-FEATURE[=PARAMETER]'
+ Configure the package to build and install an optional user-level
+ facility called FEATURE. This allows users to choose which
+ optional features to include. Giving an optional PARAMETER of
+ `no' should omit FEATURE, if it is built by default.
+
+ No `--enable' option should *ever* cause one feature to replace
+ another. No `--enable' option should ever substitute one useful
+ behavior for another useful behavior. The only proper use for
+ `--enable' is for questions of whether to build part of the program
+ or exclude it.
+
+`--with-PACKAGE'
+ The package PACKAGE will be installed, so configure this package
+ to work with PACKAGE.
+
+ Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
+ `gnu-libc', `gdb', `x', and `x-toolkit'.
+
+ Do not use a `--with' option to specify the file name to use to
+ find certain files. That is outside the scope of what `--with'
+ options are for.
+
+ All `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
+`--with-' or `--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 `--with-' and `--enable-' are
+narrow: they *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 `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.
+
+ To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
+for the host type. So the command would look like this:
+
+ ./configure HOSTTYPE --target=TARGETTYPE
+
+ Programs for which cross-operation is not meaningful need not accept
+the `--target' option, because configuring an entire operating system
+for cross-operation is not a meaningful operation.
+
+ Bootstrapping a cross-compiler requires compiling it on a machine
+other than the host it will run on. Compilation packages accept a
+configuration option `--build=BUILDTYPE' for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using `config.guess'), so
+this option is probably not necessary. The host and target types
+normally default from the build type, so in bootstrapping a
+cross-compiler you must specify them both explicitly.
+
+ Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your `configure' script can simply
+ignore most of its arguments.
+
+\1f
+File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
+
+Makefile Conventions
+====================
+
+This node describes conventions for writing the Makefiles for GNU
+programs. Using Automake will help you write a Makefile that follows
+these conventions.
+
+* Menu:
+
+* Makefile Basics:: General Conventions for Makefiles
+* Utilities in Makefiles:: Utilities in Makefiles
+* Command Variables:: Variables for Specifying Commands
+* Directory Variables:: Variables for Installation Directories
+* Standard Targets:: Standard Targets for Users
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
+
+\1f
+File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
+
+General Conventions for Makefiles
+---------------------------------
+
+Every Makefile should contain this line:
+
+ SHELL = /bin/sh
+
+to avoid trouble on systems where the `SHELL' variable might be
+inherited from the environment. (This is never a problem with GNU
+`make'.)
+
+ Different `make' programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior. So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+ .SUFFIXES:
+ .SUFFIXES: .c .o
+
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+ Don't assume that `.' is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses `./' if the program is built as
+part of the make or `$(srcdir)/' if the file is an unchanging part of
+the source code. Without one of these prefixes, the current search
+path is used.
+
+ The distinction between `./' (the "build directory") and
+`$(srcdir)/' (the "source directory") is important because users can
+build in a separate directory using the `--srcdir' option to
+`configure'. A rule of the form:
+
+ foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+
+will fail when the build directory is not the source directory, because
+`foo.man' and `sedscript' are in the source directory.
+
+ When using GNU `make', relying on `VPATH' to find the source file
+will work in the case where there is a single dependency file, since
+the `make' automatic variable `$<' will represent the source file
+wherever it is. (Many versions of `make' set `$<' only in implicit
+rules.) A Makefile target like
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow `VPATH' to work correctly. When the target has
+multiple dependencies, using an explicit `$(srcdir)' is the easiest way
+to make the rule work well. For example, the target above for `foo.1'
+is best written as:
+
+ foo.1 : foo.man sedscript
+ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+ GNU distributions usually contain some files which are not source
+files--for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
+
+ However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+ Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel `make'.
+
+\1f
+File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
+
+Utilities in Makefiles
+----------------------
+
+Write the Makefile commands (and any shell scripts, such as
+`configure') to run in `sh', not in `csh'. Don't use any special
+features of `ksh' or `bash'.
+
+ The `configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+ cat cmp cp diff echo egrep expr false grep install-info
+ ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+ The compression program `gzip' can be used in the `dist' rule.
+
+ Stick to the generally supported options for these programs. For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+ It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+ The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via `make' variables
+so that the user can substitute alternatives. Here are some of the
+programs we mean:
+
+ ar bison cc flex install ld ldconfig lex
+ make makeinfo ranlib texi2dvi yacc
+
+ Use the following `make' variables to run those programs:
+
+ $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+ $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+ When you use `ranlib' or `ldconfig', you should make sure nothing
+bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
+
+ If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+ Additional utilities that can be used via Make variables are:
+
+ chgrp chmod chown mknod
+
+ It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+\1f
+File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
+
+Variables for Specifying Commands
+---------------------------------
+
+Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+ In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named `BISON' whose default
+value is set with `BISON = bison', and refer to it with `$(BISON)'
+whenever you need to use Bison.
+
+ File management utilities such as `ln', `rm', `mv', and so on, need
+not be referred to through variables in this way, since users don't
+need to replace them with other programs.
+
+ Each program-name variable should come with an options variable that
+is used to supply options to the program. Append `FLAGS' to the
+program-name variable name to get the options variable name--for
+example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
+`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
+but we keep them because they are standard.) Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+ If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in `CFLAGS'. Users
+expect to be able to specify `CFLAGS' freely themselves. Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+ CFLAGS = -g
+ ALL_CFLAGS = -I. $(CFLAGS)
+ .c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+ Do include the `-g' option in `CFLAGS', because that is not
+_required_ for proper compilation. You can consider it a default that
+is only recommended. If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+ Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+ `CFLAGS' should be used in every invocation of the C compiler, both
+those which do compilation and those which do linking.
+
+ Every Makefile should define the variable `INSTALL', which is the
+basic command for installing a file into the system.
+
+ Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
+`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
+644'.) Then it should use those variables as the commands for actual
+installation, for executables and nonexecutables respectively. Use
+these variables as follows:
+
+ $(INSTALL_PROGRAM) foo $(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+ Optionally, you may prepend the value of `DESTDIR' to the target
+filename. Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later. Do not
+set the value of `DESTDIR' in your Makefile, and do not include it in
+any installed files. With support for `DESTDIR', the above examples
+become:
+
+ $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
+
+\1f
+File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
+
+Variables for Installation Directories
+--------------------------------------
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place. The standard names for these
+variables are described below. They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
+
+ These two variables set the root for the installation. All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+`prefix'
+ A prefix used in constructing the default values of the variables
+ listed below. The default value of `prefix' should be
+ `/usr/local'. When building the complete GNU system, the prefix
+ will be empty and `/usr' will be a symbolic link to `/'. (If you
+ are using Autoconf, write it as `@prefix@'.)
+
+ Running `make install' with a different value of `prefix' from the
+ one used to build the program should _not_ recompile the program.
+
+`exec_prefix'
+ A prefix used in constructing the default values of some of the
+ variables listed below. The default value of `exec_prefix' should
+ be `$(prefix)'. (If you are using Autoconf, write it as
+ `@exec_prefix@'.)
+
+ Generally, `$(exec_prefix)' is used for directories that contain
+ machine-specific files (such as executables and subroutine
+ libraries), while `$(prefix)' is used directly for other
+ directories.
+
+ Running `make install' with a different value of `exec_prefix'
+ from the one used to build the program should _not_ recompile the
+ program.
+
+ Executable programs are installed in one of the following
+directories.
+
+`bindir'
+ The directory for installing executable programs that users can
+ run. This should normally be `/usr/local/bin', but write it as
+ `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
+ `@bindir@'.)
+
+`sbindir'
+ The directory for installing executable programs that can be run
+ from the shell, but are only generally useful to system
+ administrators. This should normally be `/usr/local/sbin', but
+ write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
+ write it as `@sbindir@'.)
+
+`libexecdir'
+ The directory for installing executable programs to be run by other
+ programs rather than by users. This directory should normally be
+ `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+ (If you are using Autoconf, write it as `@libexecdir@'.)
+
+ Data files used by the program during its execution are divided into
+categories in two ways.
+
+ * Some files are normally modified by programs; others are never
+ normally modified (though users may edit some of these).
+
+ * Some files are architecture-independent and can be shared by all
+ machines at a site; some are architecture-dependent and can be
+ shared only by machines of the same kind and operating system;
+ others may never be shared between two machines.
+
+ This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+ Therefore, here are the variables Makefiles should use to specify
+directories:
+
+`datadir'
+ The directory for installing read-only architecture independent
+ data files. This should normally be `/usr/local/share', but write
+ it as `$(prefix)/share'. (If you are using Autoconf, write it as
+ `@datadir@'.) As a special exception, see `$(infodir)' and
+ `$(includedir)' below.
+
+`sysconfdir'
+ The directory for installing read-only data files that pertain to a
+ single machine-that is to say, files for configuring a host.
+ Mailer and network configuration files, `/etc/passwd', and so
+ forth belong here. All the files in this directory should be
+ ordinary ASCII text files. This directory should normally be
+ `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
+ using Autoconf, write it as `@sysconfdir@'.)
+
+ Do not install executables here in this directory (they probably
+ belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
+ files that are modified in the normal course of their use (programs
+ whose purpose is to change the configuration of the system
+ excluded). Those probably belong in `$(localstatedir)'.
+
+`sharedstatedir'
+ The directory for installing architecture-independent data files
+ which the programs modify while they run. This should normally be
+ `/usr/local/com', but write it as `$(prefix)/com'. (If you are
+ using Autoconf, write it as `@sharedstatedir@'.)
+
+`localstatedir'
+ The directory for installing data files which the programs modify
+ while they run, and that pertain to one specific machine. Users
+ should never need to modify files in this directory to configure
+ the package's operation; put such configuration information in
+ separate files that go in `$(datadir)' or `$(sysconfdir)'.
+ `$(localstatedir)' should normally be `/usr/local/var', but write
+ it as `$(prefix)/var'. (If you are using Autoconf, write it as
+ `@localstatedir@'.)
+
+`libdir'
+ The directory for object files and libraries of object code. Do
+ not install executables here, they probably ought to go in
+ `$(libexecdir)' instead. The value of `libdir' should normally be
+ `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
+ are using Autoconf, write it as `@libdir@'.)
+
+`infodir'
+ The directory for installing the Info files for this package. By
+ default, it should be `/usr/local/info', but it should be written
+ as `$(prefix)/info'. (If you are using Autoconf, write it as
+ `@infodir@'.)
+
+`lispdir'
+ The directory for installing any Emacs Lisp files in this package.
+ By default, it should be `/usr/local/share/emacs/site-lisp', but
+ it should be written as `$(prefix)/share/emacs/site-lisp'.
+
+ If you are using Autoconf, write the default as `@lispdir@'. In
+ order to make `@lispdir@' work, you need the following lines in
+ your `configure.in' file:
+
+ lispdir='${datadir}/emacs/site-lisp'
+ AC_SUBST(lispdir)
+
+`includedir'
+ The directory for installing header files to be included by user
+ programs with the C `#include' preprocessor directive. This
+ should normally be `/usr/local/include', but write it as
+ `$(prefix)/include'. (If you are using Autoconf, write it as
+ `@includedir@'.)
+
+ Most compilers other than GCC do not look for header files in
+ directory `/usr/local/include'. So installing the header files
+ this way is only useful with GCC. Sometimes this is not a problem
+ because some libraries are only really intended to work with GCC.
+ But some libraries are intended to work with other compilers.
+ They should install their header files in two places, one
+ specified by `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+ The directory for installing `#include' header files for use with
+ compilers other than GCC. This should normally be `/usr/include'.
+ (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+ The Makefile commands should check whether the value of
+ `oldincludedir' is empty. If it is, they should not try to use
+ it; they should cancel the second installation of the header files.
+
+ A package should not replace an existing header in this directory
+ unless the header came from the same package. Thus, if your Foo
+ package provides a header file `foo.h', then it should install the
+ header file in the `oldincludedir' directory if either (1) there
+ is no `foo.h' there or (2) the `foo.h' that exists came from the
+ Foo package.
+
+ To tell whether `foo.h' came from the Foo package, put a magic
+ string in the file--part of a comment--and `grep' for that string.
+
+ Unix-style man pages are installed in one of the following:
+
+`mandir'
+ The top-level directory for installing the man pages (if any) for
+ this package. It will normally be `/usr/local/man', but you should
+ write it as `$(prefix)/man'. (If you are using Autoconf, write it
+ as `@mandir@'.)
+
+`man1dir'
+ The directory for installing section 1 man pages. Write it as
+ `$(mandir)/man1'.
+
+`man2dir'
+ The directory for installing section 2 man pages. Write it as
+ `$(mandir)/man2'
+
+`...'
+ *Don't make the primary documentation for any GNU software be a
+ man page. Write a manual in Texinfo instead. Man pages are just
+ for the sake of people running GNU software on Unix, which is a
+ secondary application only.*
+
+`manext'
+ The file name extension for the installed man page. This should
+ contain a period followed by the appropriate digit; it should
+ normally be `.1'.
+
+`man1ext'
+ The file name extension for installed section 1 man pages.
+
+`man2ext'
+ The file name extension for installed section 2 man pages.
+
+`...'
+ Use these names instead of `manext' if the package needs to
+ install man pages in more than one section of the manual.
+
+ And finally, you should set the following variable:
+
+`srcdir'
+ The directory for the sources being compiled. The value of this
+ variable is normally inserted by the `configure' shell script.
+ (If you are using Autconf, use `srcdir = @srcdir@'.)
+
+ For example:
+
+ # Common prefix for installation directories.
+ # NOTE: This directory must exist when you start the install.
+ prefix = /usr/local
+ exec_prefix = $(prefix)
+ # Where to put the executable for the command `gcc'.
+ bindir = $(exec_prefix)/bin
+ # Where to put the directories used by the compiler.
+ libexecdir = $(exec_prefix)/libexec
+ # Where to put the Info files.
+ infodir = $(prefix)/info
+
+ If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the `install' rule to create these subdirectories.
+
+ Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above. The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+\1f
+File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
+
+Standard Targets for Users
+--------------------------
+
+All GNU programs should have the following targets in their Makefiles:
+
+`all'
+ Compile the entire program. This should be the default target.
+ This target need not rebuild any documentation files; Info files
+ should normally be included in the distribution, and DVI files
+ should be made only when explicitly asked for.
+
+ By default, the Make rules should compile and link with `-g', so
+ that executable programs have debugging symbols. Users who don't
+ mind being helpless can strip the executables later if they wish.
+
+`install'
+ Compile the program and copy the executables, libraries, and so on
+ to the file names where they should reside for actual use. If
+ there is a simple test to verify that a program is properly
+ installed, this target should run that test.
+
+ Do not strip executables when installing them. Devil-may-care
+ users can use the `install-strip' target to do that.
+
+ If possible, write the `install' target rule so that it does not
+ modify anything in the directory where the program was built,
+ provided `make all' has just been done. This is convenient for
+ building the program under one user name and installing it under
+ another.
+
+ The commands should create all the directories in which files are
+ to be installed, if they don't already exist. This includes the
+ directories specified as the values of the variables `prefix' and
+ `exec_prefix', as well as all subdirectories that are needed. One
+ way to do this is by means of an `installdirs' target as described
+ below.
+
+ Use `-' before any command for installing a man page, so that
+ `make' will ignore any errors. This is in case there are systems
+ that don't have the Unix man page documentation system installed.
+
+ The way to install Info files is to copy them into `$(infodir)'
+ with `$(INSTALL_DATA)' (*note Command Variables::), and then run
+ the `install-info' program if it is present. `install-info' is a
+ program that edits the Info `dir' file to add or update the menu
+ entry for the given Info file; it is part of the Texinfo package.
+ Here is a sample rule to install an Info file:
+
+ $(DESTDIR)$(infodir)/foo.info: foo.info
+ $(POST_INSTALL)
+ # There may be a newer info file in . than in srcdir.
+ -if test -f foo.info; then d=.; \
+ else d=$(srcdir); fi; \
+ $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
+ # Run install-info only if it exists.
+ # Use `if' instead of just prepending `-' to the
+ # line so we notice real errors from install-info.
+ # We use `$(SHELL) -c' because some shells do not
+ # fail gracefully when there is an unknown command.
+ if $(SHELL) -c 'install-info --version' \
+ >/dev/null 2>&1; then \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/foo.info; \
+ else true; fi
+
+ When writing the `install' target, you must classify all the
+ commands into three categories: normal ones, "pre-installation"
+ commands and "post-installation" commands. *Note Install Command
+ Categories::.
+
+`uninstall'
+ Delete all the installed files--the copies that the `install'
+ target creates.
+
+ This rule should not modify the directories where compilation is
+ done, only the directories where files are installed.
+
+ The uninstallation commands are divided into three categories,
+ just like the installation commands. *Note Install Command
+ Categories::.
+
+`install-strip'
+ Like `install', but strip the executable files while installing
+ them. In simple cases, this target can use the `install' target in
+ a simple way:
+
+ install-strip:
+ $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+ install
+
+ But if the package installs scripts as well as real executables,
+ the `install-strip' target can't just refer to the `install'
+ target; it has to strip the executables but not the scripts.
+
+ `install-strip' should not strip the executables in the build
+ directory which are being copied for installation. It should only
+ strip the copies that are installed.
+
+ Normally we do not recommend stripping an executable unless you
+ are sure the program has no bugs. However, it can be reasonable
+ to install a stripped executable for actual execution while saving
+ the unstripped executable elsewhere in case there is a bug.
+
+`clean'
+ Delete all files from the current directory that are normally
+ created by building the program. Don't delete the files that
+ record the configuration. Also preserve files that could be made
+ by building, but normally aren't because the distribution comes
+ with them.
+
+ Delete `.dvi' files here if they are not part of the distribution.
+
+`distclean'
+ Delete all files from the current directory that are created by
+ configuring or building the program. If you have unpacked the
+ source and built the program without creating any other files,
+ `make distclean' should leave only the files that were in the
+ distribution.
+
+`mostlyclean'
+ Like `clean', but may refrain from deleting a few files that people
+ normally don't want to recompile. For example, the `mostlyclean'
+ target for GCC does not delete `libgcc.a', because recompiling it
+ is rarely necessary and takes a lot of time.
+
+`maintainer-clean'
+ Delete almost everything from the current directory that can be
+ reconstructed with this Makefile. This typically includes
+ everything deleted by `distclean', plus more: C source files
+ produced by Bison, tags tables, Info files, and so on.
+
+ The reason we say "almost everything" is that running the command
+ `make maintainer-clean' should not delete `configure' even if
+ `configure' can be remade using a rule in the Makefile. More
+ generally, `make maintainer-clean' should not delete anything that
+ needs to exist in order to run `configure' and then begin to build
+ the program. This is the only exception; `maintainer-clean' should
+ delete everything else that can be rebuilt.
+
+ The `maintainer-clean' target is intended to be used by a
+ maintainer of the package, not by ordinary users. You may need
+ special tools to reconstruct some of the files that `make
+ maintainer-clean' deletes. Since these files are normally
+ included in the distribution, we don't take care to make them easy
+ to reconstruct. If you find you need to unpack the full
+ distribution again, don't blame us.
+
+ To help make users aware of this, the commands for the special
+ `maintainer-clean' target should start with these two:
+
+ @echo 'This command is intended for maintainers to use; it'
+ @echo 'deletes files that may need special tools to rebuild.'
+
+`TAGS'
+ Update a tags table for this program.
+
+`info'
+ Generate any Info files needed. The best way to write the rules
+ is as follows:
+
+ info: foo.info
+
+ foo.info: foo.texi chap1.texi chap2.texi
+ $(MAKEINFO) $(srcdir)/foo.texi
+
+ You must define the variable `MAKEINFO' in the Makefile. It should
+ run the `makeinfo' program, which is part of the Texinfo
+ distribution.
+
+ Normally a GNU distribution comes with Info files, and that means
+ the Info files are present in the source directory. Therefore,
+ the Make rule for an info file should update it in the source
+ directory. When users build the package, ordinarily Make will not
+ update the Info files because they will already be up to date.
+
+`dvi'
+ Generate DVI files for all Texinfo documentation. For example:
+
+ dvi: foo.dvi
+
+ foo.dvi: foo.texi chap1.texi chap2.texi
+ $(TEXI2DVI) $(srcdir)/foo.texi
+
+ You must define the variable `TEXI2DVI' in the Makefile. It should
+ run the program `texi2dvi', which is part of the Texinfo
+ distribution.(1) Alternatively, write just the dependencies, and
+ allow GNU `make' to provide the command.
+
+`dist'
+ Create a distribution tar file for this program. The tar file
+ should be set up so that the file names in the tar file start with
+ a subdirectory name which is the name of the package it is a
+ distribution for. This name can include the version number.
+
+ For example, the distribution tar file of GCC version 1.40 unpacks
+ into a subdirectory named `gcc-1.40'.
+
+ The easiest way to do this is to create a subdirectory
+ appropriately named, use `ln' or `cp' to install the proper files
+ in it, and then `tar' that subdirectory.
+
+ Compress the tar file with `gzip'. For example, the actual
+ distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
+
+ The `dist' target should explicitly depend on all non-source files
+ that are in the distribution, to make sure they are up to date in
+ the distribution. *Note Making Releases: Releases.
+
+`check'
+ Perform self-tests (if any). The user must build the program
+ before running the tests, but need not install the program; you
+ should write the self-tests so that they work when the program is
+ built but not installed.
+
+ The following targets are suggested as conventional names, for
+programs in which they are useful.
+
+`installcheck'
+ Perform installation tests (if any). The user must build and
+ install the program before running the tests. You should not
+ assume that `$(bindir)' is in the search path.
+
+`installdirs'
+ It's useful to add a target named `installdirs' to create the
+ directories where files are installed, and their parent
+ directories. There is a script called `mkinstalldirs' which is
+ convenient for this; you can find it in the Texinfo package. You
+ can use a rule like this:
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+ $(libdir) $(infodir) \
+ $(mandir)
+
+ or, if you wish to support `DESTDIR',
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs \
+ $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+ $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+ $(DESTDIR)$(mandir)
+
+ This rule should not modify the directories where compilation is
+ done. It should do nothing but create installation directories.
+
+ ---------- Footnotes ----------
+
+ (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
+not distributed with Texinfo.
+
+\1f
+File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
+
+Install Command Categories
+--------------------------
+
+When writing the `install' target, you must classify all the commands
+into three categories: normal ones, "pre-installation" commands and
+"post-installation" commands.
+
+ Normal commands move files into their proper places, and set their
+modes. They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+ Pre-installation and post-installation commands may alter other
+files; in particular, they can edit global configuration files or data
+bases.
+
+ Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+ The most common use for a post-installation command is to run
+`install-info'. This cannot be done with a normal command, since it
+alters a file (the Info directory) which does not come entirely and
+solely from the package being installed. It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+ Most programs don't need any pre-installation commands, but we have
+the feature just in case it is needed.
+
+ To classify the commands in the `install' rule into these three
+categories, insert "category lines" among them. A category line
+specifies the category for the commands that follow.
+
+ A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end. There are three
+variables you can use, one for each category; the variable name
+specifies the category. Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+_should not_ define them in the makefile).
+
+ Here are the three possible category lines, each with a comment that
+explains what it means:
+
+ $(PRE_INSTALL) # Pre-install commands follow.
+ $(POST_INSTALL) # Post-install commands follow.
+ $(NORMAL_INSTALL) # Normal commands follow.
+
+ If you don't use a category line at the beginning of the `install'
+rule, all the commands are classified as normal until the first category
+line. If you don't use any category lines, all the commands are
+classified as normal.
+
+ These are the category lines for `uninstall':
+
+ $(PRE_UNINSTALL) # Pre-uninstall commands follow.
+ $(POST_UNINSTALL) # Post-uninstall commands follow.
+ $(NORMAL_UNINSTALL) # Normal commands follow.
+
+ Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+ If the `install' or `uninstall' target has any dependencies which
+act as subroutines of installation, then you should start _each_
+dependency's commands with a category line, and start the main target's
+commands with a category line also. This way, you can ensure that each
+command is placed in the right category regardless of which of the
+dependencies actually run.
+
+ Pre-installation and post-installation commands should not run any
+programs except for these:
+
+ [ basename bash cat chgrp chmod chown cmp cp dd diff echo
+ egrep expand expr false fgrep find getopt grep gunzip gzip
+ hostname install install-info kill ldconfig ln ls md5sum
+ mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+ test touch true uname xargs yes
+
+ The reason for distinguishing the commands in this way is for the
+sake of making binary packages. Typically a binary package contains
+all the executables and other files that need to be installed, and has
+its own method of installing them--so it does not need to run the normal
+installation commands. But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+ Programs to build binary packages work by extracting the
+pre-installation and post-installation commands. Here is one way of
+extracting the pre-installation commands:
+
+ make -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+
+where the file `pre-install.awk' could contain this:
+
+ $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
+ on {print $0}
+ $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
+
+ The resulting file of pre-installation commands is executed as a
+shell script as part of installing the binary package.
+
+\1f
+File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
+
+Making Releases
+===============
+
+Package the distribution of `Foo version 69.96' up in a gzipped tar
+file with the name `foo-69.96.tar.gz'. It should unpack into a
+subdirectory named `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 "source
+files" and "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 `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 `README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+ The `README' file should refer to the file `INSTALL', which should
+contain an explanation of the installation procedure.
+
+ The `README' file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+`COPYING'. If the GNU LGPL is used, it should be in a file called
+`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, `lex', TeX, and `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 *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 `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 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, `foobarhacker.c'
+and `foobarhacker.o' are not ambiguous; they are truncated to
+`foobarha.c' and `foobarha.o', which are distinct.
+
+ Include in your distribution a copy of the `texinfo.tex' you used to
+test print any `*.texinfo' or `*.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.
+
+\1f
+File: standards.info, Node: References, Next: Index, Prev: Managing Releases, Up: Top
+
+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.
+
+\1f
+File: standards.info, Node: Index, Prev: References, Up: Top
+
+Index
+*****
+
+* Menu:
+
+* #endif, commenting: Comments.
+* --help option: Command-Line Interfaces.
+* --version option: Command-Line Interfaces.
+* -Wall compiler option: Syntactic Conventions.
+* accepting contributions: Contributions.
+* address for bug reports: Command-Line Interfaces.
+* ANSI C standard: Standard C.
+* arbitrary limits on data: Semantics.
+* autoconf: System Portability.
+* avoiding proprietary code: Reading Non-Free Code.
+* behavior, dependent on program's name: User Interfaces.
+* binary packages: Install Command Categories.
+* bindir: Directory Variables.
+* braces, in C source: Formatting.
+* bug reports: Command-Line Interfaces.
+* canonical name of a program: Command-Line Interfaces.
+* casting pointers to integers: CPU Portability.
+* change logs: Change Logs.
+* change logs, conditional changes: Conditional Changes.
+* change logs, style: Style of Change Logs.
+* command-line arguments, decoding: Semantics.
+* command-line interface: Command-Line Interfaces.
+* commenting: Comments.
+* compatibility with C and POSIX standards: Compatibility.
+* compiler warnings: Syntactic Conventions.
+* conditional changes, and change logs: Conditional Changes.
+* conditionals, comments for: Comments.
+* configure: Configuration.
+* control-L: Formatting.
+* conventions for makefiles: Makefile Conventions.
+* corba: Graphical Interfaces.
+* credits for manuals: Manual Credits.
+* data types, and portability: CPU Portability.
+* declaration for system functions: System Functions.
+* documentation: Documentation.
+* doschk: Names.
+* downloading this manual: Preface.
+* error messages: Semantics.
+* error messages, formatting: Errors.
+* exec_prefix: Directory Variables.
+* expressions, splitting: Formatting.
+* file usage: File Usage.
+* file-name limitations: Names.
+* formatting error messages: Errors.
+* formatting source code: Formatting.
+* formfeed: Formatting.
+* function argument, declaring: Syntactic Conventions.
+* function prototypes: Standard C.
+* getopt: Command-Line Interfaces.
+* gettext: Internationalization.
+* gnome: Graphical Interfaces.
+* graphical user interface: Graphical Interfaces.
+* gtk: Graphical Interfaces.
+* GUILE: Source Language.
+* implicit int: Syntactic Conventions.
+* impossible conditions: Semantics.
+* internationalization: Internationalization.
+* legal aspects: Legal Issues.
+* legal papers: Contributions.
+* libexecdir: Directory Variables.
+* libraries: Libraries.
+* library functions, and portability: System Functions.
+* license for manuals: License for Manuals.
+* lint: Syntactic Conventions.
+* long option names: Option Table.
+* long-named options: Command-Line Interfaces.
+* makefile, conventions for: Makefile Conventions.
+* malloc return value: Semantics.
+* man pages: Man Pages.
+* manual structure: Manual Structure Details.
+* memory allocation failure: Semantics.
+* memory usage: Memory Usage.
+* message text, and internationalization: Internationalization.
+* mmap: Mmap.
+* multiple variables in a line: Syntactic Conventions.
+* names of variables and functions: Names.
+* NEWS file: NEWS File.
+* non-POSIX systems, and portability: System Portability.
+* non-standard extensions: Using Extensions.
+* NUL characters: Semantics.
+* open brace: Formatting.
+* optional features, configure-time: Configuration.
+* options for compatibility: Compatibility.
+* output device and program's behavior: User Interfaces.
+* packaging: Releases.
+* portability, and data types: CPU Portability.
+* portability, and library functions: System Functions.
+* portability, between system types: System Portability.
+* POSIX compatibility: Compatibility.
+* POSIXLY_CORRECT, environment variable: Compatibility.
+* post-installation commands: Install Command Categories.
+* pre-installation commands: Install Command Categories.
+* prefix: Directory Variables.
+* program configuration: Configuration.
+* program design: Design Advice.
+* program name and its behavior: User Interfaces.
+* program's canonical name: Command-Line Interfaces.
+* programming languges: Source Language.
+* proprietary programs: Reading Non-Free Code.
+* README file: Releases.
+* references to non-free material: References.
+* releasing: Managing Releases.
+* sbindir: Directory Variables.
+* signal handling: Semantics.
+* spaces before open-paren: Formatting.
+* standard command-line options: Command-Line Interfaces.
+* standards for makefiles: Makefile Conventions.
+* string library functions: System Functions.
+* syntactic conventions: Syntactic Conventions.
+* table of long options: Option Table.
+* temporary files: Semantics.
+* temporary variables: Syntactic Conventions.
+* texinfo.tex, in a distribution: Releases.
+* TMPDIR environment variable: Semantics.
+* trademarks: Trademarks.
+* where to obtain standards.texi: Preface.
+
+
\1f
Tag Table:
-(Indirect)
Node: Top\7f980
-Node: Preface\7f1585
-Node: Legal Issues\7f3105
-Node: Reading Non-Free Code\7f3568
-Node: Contributions\7f5291
-Node: Trademarks\7f7440
-Node: Design Advice\7f8498
-Node: Source Language\7f9004
-Node: Compatibility\7f11011
-Node: Using Extensions\7f12634
-Node: Standard C\7f14205
-Node: Program Behavior\7f16571
-Node: Semantics\7f17489
-Node: Libraries\7f22177
-Node: Errors\7f23417
-Node: User Interfaces\7f25193
-Node: Graphical Interfaces\7f26793
-Node: Command-Line Interfaces\7f27823
-Node: Option Table\7f33308
-Node: Memory Usage\7f48312
-Node: File Usage\7f49332
-Node: Writing C\7f50075
-Node: Formatting\7f50916
-Node: Comments\7f54974
-Node: Syntactic Conventions\7f58272
-Node: Names\7f61679
-Node: System Portability\7f63867
-Node: CPU Portability\7f66247
-Node: System Functions\7f69498
-Node: Internationalization\7f74700
-Node: Mmap\7f77848
-Node: Documentation\7f78553
-Node: GNU Manuals\7f79657
-Node: Doc Strings and Manuals\7f84709
-Node: Manual Structure Details\7f86257
-Node: License for Manuals\7f87670
-Node: Manual Credits\7f88639
-Node: Printed Manuals\7f89027
-Node: NEWS File\7f89708
-Node: Change Logs\7f90380
-Node: Change Log Concepts\7f91129
-Node: Style of Change Logs\7f92984
-Node: Simple Changes\7f95030
-Node: Conditional Changes\7f96265
-Node: Indicating the Part Changed\7f97678
-Node: Man Pages\7f98196
-Node: Reading other Manuals\7f99815
-Node: Managing Releases\7f100599
-Node: Configuration\7f101354
-Node: Makefile Conventions\7f108254
-Node: Makefile Basics\7f109013
-Node: Utilities in Makefiles\7f112178
-Node: Command Variables\7f114314
-Node: Directory Variables\7f117882
-Node: Standard Targets\7f128767
-Ref: Standard Targets-Footnote-1\7f140018
-Node: Install Command Categories\7f140118
-Node: Releases\7f144691
-Node: References\7f148774
-Node: Index\7f150168
+Node: Preface\7f1582
+Node: Legal Issues\7f3099
+Node: Reading Non-Free Code\7f3559
+Node: Contributions\7f5279
+Node: Trademarks\7f7425
+Node: Design Advice\7f8480
+Node: Source Language\7f8983
+Node: Compatibility\7f10987
+Node: Using Extensions\7f12607
+Node: Standard C\7f14175
+Node: Program Behavior\7f16538
+Node: Semantics\7f17453
+Node: Libraries\7f22138
+Node: Errors\7f23375
+Node: User Interfaces\7f25148
+Node: Graphical Interfaces\7f26745
+Node: Command-Line Interfaces\7f27772
+Node: Option Table\7f33254
+Node: Memory Usage\7f48255
+Node: File Usage\7f49272
+Node: Writing C\7f50012
+Node: Formatting\7f50850
+Node: Comments\7f54905
+Node: Syntactic Conventions\7f58199
+Node: Names\7f61603
+Node: System Portability\7f63788
+Node: CPU Portability\7f66165
+Node: System Functions\7f69413
+Node: Internationalization\7f74612
+Node: Mmap\7f77757
+Node: Documentation\7f78459
+Node: GNU Manuals\7f79560
+Node: Doc Strings and Manuals\7f84609
+Node: Manual Structure Details\7f86154
+Node: License for Manuals\7f87564
+Node: Manual Credits\7f88530
+Node: Printed Manuals\7f88915
+Node: NEWS File\7f89593
+Node: Change Logs\7f90263
+Node: Change Log Concepts\7f91009
+Node: Style of Change Logs\7f92861
+Node: Simple Changes\7f94904
+Node: Conditional Changes\7f96136
+Node: Indicating the Part Changed\7f97546
+Node: Man Pages\7f98061
+Node: Reading other Manuals\7f99677
+Node: Managing Releases\7f100458
+Node: Configuration\7f101210
+Node: Makefile Conventions\7f108107
+Node: Makefile Basics\7f108863
+Node: Utilities in Makefiles\7f112025
+Node: Command Variables\7f114158
+Node: Directory Variables\7f117723
+Node: Standard Targets\7f128605
+Ref: Standard Targets-Footnote-1\7f139853
+Node: Install Command Categories\7f139953
+Node: Releases\7f144523
+Node: References\7f148603
+Node: Index\7f149994
\1f
End Tag Table
projects / chise / xemacs-chise.git.1 / blobdiff