xemacs-beta: man/standards.texi comparison

comparison man/standards.texi @ 428:3ecd8885ac67 r21-2-22

Import from CVS: tag r21-2-22

author	cvs
date	Mon, 13 Aug 2007 11:28:15 +0200
parents
children	0784d089fdc9

comparison

equal deleted inserted replaced

-:0a0253eac470
+:3ecd8885ac67
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/standards.info
+@settitle GNU Coding Standards
+@c This date is automagically updated when you save this file:
+@set lastupdate June 24, 1999
+@c %**end of header
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@c @setchapternewpage odd
+@setchapternewpage off
+@c This is used by a cross ref in make-stds.texi
+@set CODESTD  1
+@iftex
+@set CHAPTER chapter
+@end iftex
+@ifinfo
+@set CHAPTER node
+@end ifinfo
+@ifinfo
+GNU Coding Standards
+Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+@titlepage
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end titlepage
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top Version
+Last updated @value{lastupdate}.
+@end ifinfo
+@menu
+* Preface::                 About the GNU Coding Standards
+* Legal Issues::            Keeping Free Software Free
+* Design Advice::           General Program Design
+* Program Behavior::        Program Behavior for All Programs
+* Writing C::               Making The Best Use of C
+* Documentation::           Documenting Programs
+* Managing Releases::       The Release Process
+* References::              References to Non-Free Software or Documentation
+@end menu
+@node Preface
+@chapter About the GNU Coding Standards
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers.  Their purpose is to make the GNU system clean,
+consistent, and easy to install.  This document can also be read as a
+guide to writing portable, robust and reliable programs.  It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language.  The rules often
+state reasons for writing in a certain way.
+Corrections or suggestions for this document should be sent to
+@email{gnu@@gnu.org}.  If you make a suggestion, please include a
+suggested new wording for it; our time is limited.  We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+@node Legal Issues
+@chapter Keeping Free Software Free
+This @value{CHAPTER} discusses how you can make sure that GNU software
+remains unencumbered.
+@menu
+* Reading Non-Free Code::       Referring to Proprietary Programs
+* Contributions::               Accepting Contributions
+@end menu
+@node Reading Non-Free Code
+@section Referring to Proprietary Programs
+Don't in any circumstances refer to Unix source code for or during
+your work on GNU!  (Or to any other proprietary programs.)
+If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different.  You could keep the entire input file in core and scan it
+there instead of using stdio.  Use a smarter algorithm discovered more
+recently than the Unix program.  Eliminate use of temporary files.  Do
+it in one pass instead of two (we did this in the assembler).
+Or, on the contrary, emphasize simplicity instead of speed.  For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+Or go for generality.  For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead.  Make sure your program handles NULs and
+other funny characters in the input files.  Add a programming language
+for extensibility and write part of the program in that language.
+Or turn some parts of the program into independently usable libraries.
+Or use a simple garbage collector instead of tracking precisely when
+to free memory, or use a new GNU facility such as obstacks.
+@node Contributions
+@section Accepting Contributions
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it---just as we asked you to
+sign papers initially.  @emph{Each} person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers.  Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+This applies both before you release the program and afterward.  If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+This also applies to comments and documentation files.  For copyright
+law, comments and code are just text.  Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+We know it is frustrating to ask for legal papers; it's frustrating for
+us as well.  But if you don't wait, you are going out on a limb---for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes.  Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use.  For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+The very worst thing is if you forget to tell us about the other
+contributor.  We could be very embarrassed in court some day as a
+result.
+We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+@node Design Advice
+@chapter General Program Design
+This @value{CHAPTER} discusses some of the issues you should take into
+account when designing your program.
+@menu
+* Compatibility::               Compatibility with other implementations
+* Using Extensions::            Using non-standard features
+* ANSI C::                      Using ANSI C features
+* Source Language::             Using languages other than C
+@end menu
+@node Compatibility
+@section Compatibility with Other Implementations
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with @sc{ansi} C if @sc{ansi} C specifies their behavior, and
+upward compatible with @sc{posix} if @sc{posix} specifies their
+behavior.
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+@sc{ansi} C and @sc{posix} prohibit many kinds of extensions.  Feel free
+to make the extensions anyway, and include a @samp{--ansi},
+@samp{--posix}, or @samp{--compatible} option to turn them off.
+However, if the extension has a significant chance of breaking any real
+programs or scripts, then it is not really upward compatible.  Try to
+redesign its interface.
+Many GNU programs suppress extensions that conflict with @sc{posix} if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value).  Please make your program recognize this
+variable if appropriate.
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better.  (For example,
+@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible
+feature as well.  (There is a free @code{vi} clone, so we offer it.)
+Additional useful features not in Berkeley Unix are welcome.
+@node Using Extensions
+@section Using Non-standard Features
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities.  Whether to use these
+extensions in implementing your program is a difficult question.
+On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program
+unless the other GNU tools are available.  This might cause the
+program to work on fewer kinds of machines.
+With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a ``keyword'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems.  Such programs would
+be broken by use of GNU extensions.
+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 no good.
+@node ANSI C
+@section @sc{ansi} C and pre-@sc{ansi} C
+Do not ever use the ``trigraph'' feature of @sc{ansi} C.
+@sc{ansi} C is widespread enough now that it is ok to write new programs
+that use @sc{ansi} C features (and therefore will not work in
+non-@sc{ansi} compilers).  And if a program is already written in
+@sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
+compilers.
+If you don't know non-@sc{ansi} C, there's no need to learn it; just
+write in @sc{ansi} C.
+However, it is easy to support non-@sc{ansi} compilers in most programs,
+so you might still consider doing so when you write a program.  And if a
+program you are maintaining has such support, you should try to keep it
+working.
+To support pre-@sc{ansi} C, instead of writing function definitions in
+@sc{ansi} prototype form,
+@example
+int
+foo (int x, int y)
+@dots{}
+@end example
+@noindent
+write the definition in pre-@sc{ansi} style like this,
+@example
+int
+foo (x, y)
+int x, y;
+@dots{}
+@end example
+@noindent
+and use a separate declaration to specify the argument prototype:
+@example
+int foo (int, int);
+@end example
+You need such a declaration anyway, in a header file, to get the benefit
+of @sc{ansi} C 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-@sc{ansi} style.
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+There are a few special cases where this technique is hard to use.  For
+example, if a function argument needs to hold the system type
+@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+@code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines.  There
+is no type you can safely use on all machines in a non-@sc{ansi}
+definition.  The only way to support non-@sc{ansi} C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly.  This may not be worth the trouble.
+@node Source Language
+@section Using Languages Other Than C
+Using a language other than C 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 C++ compiler
+in order to compile your program.  Thus, it is better if you write in C.
+But there are three situations when there is no disadvantage in using
+some other language:
+@itemize @bullet
+@item
+It is okay to use another language if your program contains an
+interpreter for that language.
+For example, if your program links with GUILE, it is ok to write part of
+the program in Scheme or another language supported by GUILE.
+@item
+It is okay to use another language in a tool specifically intended for
+use with that language.
+This is okay because the only people who want to build the tool will be
+those who have installed the other language anyway.
+@item
+If an application is of interest to a narrow community, then perhaps
+it's not important if the application is inconvenient to install.
+@end itemize
+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.
+@node Program Behavior
+@chapter Program Behavior for All Programs
+This @value{CHAPTER} describes how to write 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 for command line interfaces
+* Option Table::                Table of long options.
+* Memory Usage::                When and how to care about memory needs
+@end menu
+@node Semantics
+@section Writing Robust Programs
+Avoid arbitrary limits on the length or number of @emph{any} data
+structure, including file names, lines, files, and symbols, by allocating
+all data structures dynamically.  In most Unix utilities, ``long lines
+are silently truncated''.  This is not acceptable in a GNU utility.
+Utilities reading files should not drop NUL characters, or any other
+nonprinting characters @emph{including those with codes above 0177}.
+The only sensible exceptions would be utilities specifically intended
+for interface to certain types of terminals or printers
+that can't handle those characters.
+Whenever possible, try to make programs work properly with
+sequences of bytes that represent multibyte characters, using encodings
+such as UTF-8 and others.
+Check every system call for an error return, unless you know you wish to
+ignore errors.  Include the system error text (from @code{perror} or
+equivalent) in @emph{every} error message resulting from a failing
+system call, as well as the name of the file if any and the name of the
+utility.  Just ``cannot open foo.c'' or ``stat failed'' is not
+sufficient.
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero.  Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+@code{realloc} may get a different block if you ask for less space.
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero.  GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged.  Feel free to assume the bug is fixed.  If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+You must expect @code{free} to alter the contents of the block that was
+freed.  Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error.  In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.  This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+When static storage is to be written in during program execution, use
+explicit C code to initialize it.  Reserve C initialized declarations
+for data that will not be changed.
+@c ADR: why?
+Try to avoid low-level interfaces to obscure Unix data structures (such
+as file directories, utmp, or the layout of kernel memory), since these
+are less likely to work compatibly.  If you need to find all the files
+in a directory, use @code{readdir} or some other high-level interface.
+These are supported compatibly by GNU.
+The preferred signal handling facilities are the BSD variant of
+@code{signal}, and the @sc{posix} @code{sigaction} function; the
+alternative USG @code{signal} interface is an inferior design.
+Nowadays, using the @sc{posix} signal functions may be the easiest way
+to make a program portable.  If you use @code{signal}, then on GNU/Linux
+systems running GNU libc version 1, you should include
+@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
+behavior.  It is up to you whether to support systems where
+@code{signal} has only the USG behavior, or give up on them.
+In error checks that detect ``impossible'' conditions, just abort.
+There is usually no point in printing any message.  These checks
+indicate the existence of bugs.  Whoever wants to fix the bugs will have
+to read the source code and run a debugger.  So explain the problem with
+comments in the source.  The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+Do not use a count of errors as the exit status for a program.
+@emph{That does not work}, because exit status values are limited to 8
+bits (0 through 255).  A single run of the program might have 256
+errors; if you try to return 256 as the exit status, the parent process
+will see 0 as the status, and it will appear that the program succeeded.
+If you make temporary files, check the @code{TMPDIR} environment
+variable; if that variable is defined, use the specified directory
+instead of @file{/tmp}.
+@node Libraries
+@section Library Behavior
+Try to make library functions reentrant.  If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of @code{malloc} itself.
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix.  In addition, there should only be one of these in any given
+library member.  This usually means putting each one in a separate
+source file.
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}.  They should also contain
+the chosen name prefix for the library, to prevent collisions with
+other libraries.  These can go in the same files with user entry
+points if you like.
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+@node Errors
+@section Formatting Error Messages
+Error messages from compilers should look like this:
+@example
+@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+@noindent
+If you want to mention the column number, use this format:
+@example
+@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+@noindent
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line.  (Both
+of these conventions are chosen for compatibility.)  Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+Error messages from other noninteractive programs should look like this:
+@example
+@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+@noindent
+when there is an appropriate source file, or like this:
+@example
+@var{program}: @var{message}
+@end example
+@noindent
+when there is no relevant source file.
+If you want to mention the column number, use this format:
+@example
+@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message.  The place to indicate which program is running is in the
+prompt or with the screen layout.  (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or file name.  Also, it should not end
+with a period.
+Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter.  But they should not
+end with a period.
+@node User Interfaces
+@section Standards for Command Line Interfaces
+Please don't make the behavior of a utility depend on the name used
+to invoke it.  It is useful sometimes to make a link to a utility
+with a different name, and that should not change what it does.
+Instead, use a run time option or a compilation switch or both
+to select among the alternate behaviors.
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with.  Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then.  (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+Compatibility requires certain programs to depend on the type of output
+device.  It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect.  In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type.  For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+It is a good idea to follow the @sc{posix} guidelines for the
+command-line options of a program.  The easiest way to do this is to use
+@code{getopt} to parse them.  Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used.  This is not what @sc{posix}
+specifies; it is a GNU extension.
+Please define long-named options that are equivalent to the
+single-letter Unix-style options.  We hope to make GNU more user
+friendly this way.  This is easy to do with the GNU function
+@code{getopt_long}.
+One of the advantages of long-named options is that they can be
+consistent from program to program.  For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}.  To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program (@pxref{Option Table}).
+It is usually a good idea for file names given as ordinary arguments to
+be input files only; any output files would be specified using options
+(preferably @samp{-o} or @samp{--output}).  Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it.  This will lead to more consistency
+among GNU utilities, and fewer idiosyncracies for users to remember.
+All programs should support two standard options: @samp{--version}
+and @samp{--help}.
+@table @code
+@item --version
+This option should direct the program to print information about its name,
+version, origin and legal status, all on standard output, and then exit
+successfully.  Other options and arguments should be ignored once this
+is seen, and the program should not perform its normal function.
+The first line is meant to be easy for a program to parse; the version
+number proper starts after the last space.  In addition, it contains
+the canonical name for this program, in this format:
+@example
+GNU Emacs 19.30
+@end example
+@noindent
+The program's name should be a constant string; @emph{don't} compute it
+from @code{argv[0]}.  The idea is to state the standard or canonical
+name for the program, not its file name.  There are other ways to find
+out the precise file name where a command is found in @code{PATH}.
+If the program is a subsidiary part of a larger package, mention the
+package name in parentheses, like this:
+@example
+emacsserver (GNU Emacs) 19.30
+@end example
+@noindent
+If the package has a version number which is different from this
+program's version number, you can mention the package version number
+just before the close-parenthesis.
+If you @strong{need} to mention the version numbers of libraries which
+are distributed separately from the package which contains this program,
+you can do so by printing an additional line of version info for each
+library you want to mention.  Use the same format for these lines as for
+the first line.
+Please do not mention all of the libraries that the program uses ``just
+for completeness''---that would produce a lot of unhelpful clutter.
+Please mention library version numbers only if you find in practice that
+they are very important to you in debugging.
+The following line, after the version number line or lines, should be a
+copyright notice.  If more than one copyright notice is called for, put
+each on a separate line.
+Next should follow a brief statement that the program is free software,
+and that users are free to copy and change it on certain conditions.  If
+the program is covered by the GNU GPL, say so here.  Also mention that
+there is no warranty, to the extent permitted by law.
+It is ok to finish the output with a list of the major authors of the
+program, as a way of giving credit.
+Here's an example of output that follows these rules:
+@smallexample
+GNU Emacs 19.34.5
+Copyright (C) 1996 Free Software Foundation, Inc.
+GNU Emacs comes with NO WARRANTY,
+to the extent permitted by law.
+You may redistribute copies of GNU Emacs
+under the terms of the GNU General Public License.
+For more information about these matters,
+see the files named COPYING.
+@end smallexample
+You should adapt this to your program, of course, filling in the proper
+year, copyright holder, name of program, and the references to
+distribution terms, and changing the rest of the wording as necessary.
+This copyright notice only needs to mention the most recent year in
+which changes were made---there's no need to list the years for previous
+versions' changes.  You don't have to mention the name of the program in
+these notices, if that is inconvenient, since it appeared in the first
+line.
+@item --help
+This option should output brief documentation for how to invoke the
+program, on standard output, then exit successfully.  Other options and
+arguments should be ignored once this is seen, and the program should
+not perform its normal function.
+Near the end of the @samp{--help} option's output there should be a line
+that says where to mail bug reports.  It should have this format:
+@example
+Report bugs to @var{mailing-address}.
+@end example
+@end table
+@node Option Table
+@section Table of Long Options
+Here is a table of long options used by GNU programs.  It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with.  If you use names not already in the table,
+please send @email{gnu@@gnu.org} a list of them, with their
+meanings, so we can update the table.
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period.   --friedman
+@table @samp
+@item after-date
+@samp{-N} in @code{tar}.
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+@item all-text
+@samp{-a} in @code{diff}.
+@item almost-all
+@samp{-A} in @code{ls}.
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+@item archive
+@samp{-a} in @code{cp}.
+@item archive-name
+@samp{-n} in @code{shar}.
+@item arglength
+@samp{-l} in @code{m4}.
+@item ascii
+@samp{-a} in @code{diff}.
+@item assign
+@samp{-v} in @code{gawk}.
+@item assume-new
+@samp{-W} in Make.
+@item assume-old
+@samp{-o} in Make.
+@item auto-check
+@samp{-a} in @code{recode}.
+@item auto-pager
+@samp{-a} in @code{wdiff}.
+@item auto-reference
+@samp{-A} in @code{ptx}.
+@item avoid-wraps
+@samp{-n} in @code{wdiff}.
+@item background
+For server programs, run in the background.
+@item backward-search
+@samp{-B} in @code{ctags}.
+@item basename
+@samp{-f} in @code{shar}.
+@item batch
+Used in GDB.
+@item baud
+Used in GDB.
+@item before
+@samp{-b} in @code{tac}.
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+@item bits-per-code
+@samp{-b} in @code{shar}.
+@item block-size
+Used in @code{cpio} and @code{tar}.
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+@item break-file
+@samp{-b} in @code{ptx}.
+@item brief
+Used in various programs to make output shorter.
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+@item c@t{++}
+@samp{-C} in @code{etags}.
+@item catenate
+@samp{-A} in @code{tar}.
+@item cd
+Used in various programs to specify the directory to use.
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+@item classify
+@samp{-F} in @code{ls}.
+@item colons
+@samp{-c} in @code{recode}.
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+@item compare
+@samp{-d} in @code{tar}.
+@item compat
+Used in @code{gawk}.
+@item compress
+@samp{-Z} in @code{tar} and @code{shar}.
+@item concatenate
+@samp{-A} in @code{tar}.
+@item confirmation
+@samp{-w} in @code{tar}.
+@item context
+Used in @code{diff}.
+@item copyleft
+@samp{-W copyleft} in @code{gawk}.
+@item copyright
+@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
+@samp{-W copyright} in @code{gawk}.
+@item core
+Used in GDB.
+@item count
+@samp{-q} in @code{who}.
+@item count-links
+@samp{-l} in @code{du}.
+@item create
+Used in @code{tar} and @code{cpio}.
+@item cut-mark
+@samp{-c} in @code{shar}.
+@item cxref
+@samp{-x} in @code{ctags}.
+@item date
+@samp{-d} in @code{touch}.
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+@item define
+@samp{-D} in @code{m4}.
+@item defines
+@samp{-d} in Bison and @code{ctags}.
+@item delete
+@samp{-D} in @code{tar}.
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+@item dereference-args
+@samp{-D} in @code{du}.
+@item device
+Specify an I/O device (special file name).
+@item diacritics
+@samp{-d} in @code{recode}.
+@item dictionary-order
+@samp{-d} in @code{look}.
+@item diff
+@samp{-d} in @code{tar}.
+@item digits
+@samp{-n} in @code{csplit}.
+@item directory
+Specify the directory to use, in various programs.  In @code{ls}, it
+means to show directories themselves rather than their contents.  In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+@item discard-all
+@samp{-x} in @code{strip}.
+@item discard-locals
+@samp{-X} in @code{strip}.
+@item dry-run
+@samp{-n} in Make.
+@item ed
+@samp{-e} in @code{diff}.
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+@item end-delete
+@samp{-x} in @code{wdiff}.
+@item end-insert
+@samp{-z} in @code{wdiff}.
+@item entire-new-file
+@samp{-N} in @code{diff}.
+@item environment-overrides
+@samp{-e} in Make.
+@item eof
+@samp{-e} in @code{xargs}.
+@item epoch
+Used in GDB.
+@item error-limit
+Used in @code{makeinfo}.
+@item error-output
+@samp{-o} in @code{m4}.
+@item escape
+@samp{-b} in @code{ls}.
+@item exclude-from
+@samp{-X} in @code{tar}.
+@item exec
+Used in GDB.
+@item exit
+@samp{-x} in @code{xargs}.
+@item exit-0
+@samp{-e} in @code{unshar}.
+@item expand-tabs
+@samp{-t} in @code{diff}.
+@item expression
+@samp{-e} in @code{sed}.
+@item extern-only
+@samp{-g} in @code{nm}.
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+@item faces
+@samp{-f} in @code{finger}.
+@item fast
+@samp{-f} in @code{su}.
+@item fatal-warnings
+@samp{-E} in @code{m4}.
+@item file
+@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+@item field-separator
+@samp{-F} in @code{gawk}.
+@item file-prefix
+@samp{-b} in Bison.
+@item file-type
+@samp{-F} in @code{ls}.
+@item files-from
+@samp{-T} in @code{tar}.
+@item fill-column
+Used in @code{makeinfo}.
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+@item fixed-output-files
+@samp{-y} in Bison.
+@item follow
+@samp{-f} in @code{tail}.
+@item footnote-style
+Used in @code{makeinfo}.
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+@item force-prefix
+@samp{-F} in @code{shar}.
+@item foreground
+For server programs, run in the foreground;
+in other words, don't do anything special to run the server
+in the background.
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+@item freeze-state
+@samp{-F} in @code{m4}.
+@item fullname
+Used in GDB.
+@item gap-size
+@samp{-g} in @code{ptx}.
+@item get
+@samp{-x} in @code{tar}.
+@item graphic
+@samp{-i} in @code{ul}.
+@item graphics
+@samp{-g} in @code{recode}.
+@item group
+@samp{-g} in @code{install}.
+@item gzip
+@samp{-z} in @code{tar} and @code{shar}.
+@item hashsize
+@samp{-H} in @code{m4}.
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+@item heading
+@samp{-H} in @code{who}.
+@item help
+Used to ask for brief usage information.
+@item here-delimiter
+@samp{-d} in @code{shar}.
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+@item idle
+@samp{-u} in @code{who}.
+@item ifdef
+@samp{-D} in @code{diff}.
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+@item ignore-backups
+@samp{-B} in @code{ls}.
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff} and @code{wdiff}.
+@item ignore-errors
+@samp{-i} in Make.
+@item ignore-file
+@samp{-i} in @code{ptx}.
+@item ignore-indentation
+@samp{-I} in @code{etags}.
+@item ignore-init-file
+@samp{-f} in Oleo.
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+@item include-dir
+@samp{-I} in Make.
+@item incremental
+@samp{-G} in @code{tar}.
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+@item initial
+@samp{-i} in @code{expand}.
+@item initial-tab
+@samp{-T} in @code{diff}.
+@item inode
+@samp{-i} in @code{ls}.
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+@item intermix-type
+@samp{-p} in @code{shar}.
+@item jobs
+@samp{-j} in Make.
+@item just-print
+@samp{-n} in Make.
+@item keep-going
+@samp{-k} in Make.
+@item keep-files
+@samp{-k} in @code{csplit}.
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+@item language
+@samp{-l} in @code{etags}.
+@item less-mode
+@samp{-l} in @code{wdiff}.
+@item level-for-gzip
+@samp{-g} in @code{shar}.
+@item line-bytes
+@samp{-C} in @code{split}.
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+@item link
+@samp{-l} in @code{cpio}.
+@item lint
+@itemx lint-old
+Used in @code{gawk}.
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+@item list
+@samp{-t} in @code{tar}.
+@item literal
+@samp{-N} in @code{ls}.
+@item load-average
+@samp{-l} in Make.
+@item login
+Used in @code{su}.
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do, and tell @email{gnu@@gnu.org}.
+@item macro-name
+@samp{-M} in @code{ptx}.
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+@item make-directories
+@samp{-d} in @code{cpio}.
+@item makefile
+@samp{-f} in Make.
+@item mapped
+Used in GDB.
+@item max-args
+@samp{-n} in @code{xargs}.
+@item max-chars
+@samp{-n} in @code{xargs}.
+@item max-lines
+@samp{-l} in @code{xargs}.
+@item max-load
+@samp{-l} in Make.
+@item max-procs
+@samp{-P} in @code{xargs}.
+@item mesg
+@samp{-T} in @code{who}.
+@item message
+@samp{-T} in @code{who}.
+@item minimal
+@samp{-d} in @code{diff}.
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+@item modification-time
+@samp{-m} in @code{tar}.
+@item multi-volume
+@samp{-M} in @code{tar}.
+@item name-prefix
+@samp{-a} in Bison.
+@item nesting-limit
+@samp{-L} in @code{m4}.
+@item net-headers
+@samp{-a} in @code{shar}.
+@item new-file
+@samp{-W} in Make.
+@item no-builtin-rules
+@samp{-r} in Make.
+@item no-character-count
+@samp{-w} in @code{shar}.
+@item no-check-existing
+@samp{-x} in @code{shar}.
+@item no-common
+@samp{-3} in @code{wdiff}.
+@item no-create
+@samp{-c} in @code{touch}.
+@item no-defines
+@samp{-D} in @code{etags}.
+@item no-deleted
+@samp{-1} in @code{wdiff}.
+@item no-dereference
+@samp{-d} in @code{cp}.
+@item no-inserted
+@samp{-2} in @code{wdiff}.
+@item no-keep-going
+@samp{-S} in Make.
+@item no-lines
+@samp{-l} in Bison.
+@item no-piping
+@samp{-P} in @code{shar}.
+@item no-prof
+@samp{-e} in @code{gprof}.
+@item no-regex
+@samp{-R} in @code{etags}.
+@item no-sort
+@samp{-p} in @code{nm}.
+@item no-split
+Used in @code{makeinfo}.
+@item no-static
+@samp{-a} in @code{gprof}.
+@item no-time
+@samp{-E} in @code{gprof}.
+@item no-timestamp
+@samp{-m} in @code{shar}.
+@item no-validate
+Used in @code{makeinfo}.
+@item no-wait
+Used in @code{emacsclient}.
+@item no-warn
+Used in various programs to inhibit warnings.
+@item node
+@samp{-n} in @code{info}.
+@item nodename
+@samp{-n} in @code{uname}.
+@item nonmatching
+@samp{-f} in @code{cpio}.
+@item nstuff
+@samp{-n} in @code{objdump}.
+@item null
+@samp{-0} in @code{xargs}.
+@item number
+@samp{-n} in @code{cat}.
+@item number-nonblank
+@samp{-b} in @code{cat}.
+@item numeric-sort
+@samp{-n} in @code{nm}.
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+@item nx
+Used in GDB.
+@item old-archive
+@samp{-o} in @code{tar}.
+@item old-file
+@samp{-o} in Make.
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+@item only-file
+@samp{-o} in @code{ptx}.
+@item only-prof
+@samp{-f} in @code{gprof}.
+@item only-time
+@samp{-F} in @code{gprof}.
+@item options
+@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
+@code{fdmountd}, and @code{fdumount}.
+@item output
+In various programs, specify the output file name.
+@item output-prefix
+@samp{-o} in @code{shar}.
+@item override
+@samp{-o} in @code{rm}.
+@item overwrite
+@samp{-c} in @code{unshar}.
+@item owner
+@samp{-o} in @code{install}.
+@item paginate
+@samp{-l} in @code{diff}.
+@item paragraph-indent
+Used in @code{makeinfo}.
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+@item pass-all
+@samp{-p} in @code{ul}.
+@item pass-through
+@samp{-p} in @code{cpio}.
+@item port
+@samp{-P} in @code{finger}.
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+@item posix
+Used in @code{gawk}.
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+@item prefix
+@samp{-f} in @code{csplit}.
+@item preserve
+Used in @code{tar} and @code{cp}.
+@item preserve-environment
+@samp{-p} in @code{su}.
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+@item preserve-order
+@samp{-s} in @code{tar}.
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+@item print
+@samp{-l} in @code{diff}.
+@item print-chars
+@samp{-L} in @code{cmp}.
+@item print-data-base
+@samp{-p} in Make.
+@item print-directory
+@samp{-w} in Make.
+@item print-file-name
+@samp{-o} in @code{nm}.
+@item print-symdefs
+@samp{-s} in @code{nm}.
+@item printer
+@samp{-p} in @code{wdiff}.
+@item prompt
+@samp{-p} in @code{ed}.
+@item proxy
+Specify an HTTP proxy.
+@item query-user
+@samp{-X} in @code{shar}.
+@item question
+@samp{-q} in Make.
+@item quiet
+Used in many programs to inhibit the usual output.  @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+@item quiet-unshar
+@samp{-Q} in @code{shar}
+@item quote-name
+@samp{-Q} in @code{ls}.
+@item rcs
+@samp{-n} in @code{diff}.
+@item re-interval
+Used in @code{gawk}.
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+@item readnow
+Used in GDB.
+@item recon
+@samp{-n} in Make.
+@item record-number
+@samp{-R} in @code{tar}.
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+@item reference-limit
+Used in @code{makeinfo}.
+@item references
+@samp{-r} in @code{ptx}.
+@item regex
+@samp{-r} in @code{tac} and @code{etags}.
+@item release
+@samp{-r} in @code{uname}.
+@item reload-state
+@samp{-R} in @code{m4}.
+@item relocation
+@samp{-r} in @code{objdump}.
+@item rename
+@samp{-r} in @code{cpio}.
+@item replace
+@samp{-i} in @code{xargs}.
+@item report-identical-files
+@samp{-s} in @code{diff}.
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+@item reversed-ed
+@samp{-f} in @code{diff}.
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+@item same-order
+@samp{-s} in @code{tar}.
+@item same-permissions
+@samp{-p} in @code{tar}.
+@item save
+@samp{-g} in @code{stty}.
+@item se
+Used in GDB.
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+@item separate-dirs
+@samp{-S} in @code{du}.
+@item separator
+@samp{-s} in @code{tac}.
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+@item shell
+@samp{-s} in @code{su}.
+@item show-all
+@samp{-A} in @code{cat}.
+@item show-c-function
+@samp{-p} in @code{diff}.
+@item show-ends
+@samp{-E} in @code{cat}.
+@item show-function-line
+@samp{-F} in @code{diff}.
+@item show-tabs
+@samp{-T} in @code{cat}.
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+@item size
+@samp{-s} in @code{ls}.
+@item socket
+Specify a file descriptor for a network server to use for its socket,
+instead of opening and binding a new socket.  This provides a way to
+run, in a nonpriveledged process, a server that normally needs a
+reserved port number.
+@item sort
+Used in @code{ls}.
+@item source
+@samp{-W source} in @code{gawk}.
+@item sparse
+@samp{-S} in @code{tar}.
+@item speed-large-files
+@samp{-H} in @code{diff}.
+@item split-at
+@samp{-E} in @code{unshar}.
+@item split-size-limit
+@samp{-L} in @code{shar}.
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+@item start-delete
+@samp{-w} in @code{wdiff}.
+@item start-insert
+@samp{-y} in @code{wdiff}.
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+@item statistics
+@samp{-s} in @code{wdiff}.
+@item stdin-file-list
+@samp{-S} in @code{shar}.
+@item stop
+@samp{-S} in Make.
+@item strict
+@samp{-s} in @code{recode}.
+@item strip
+@samp{-s} in @code{install}.
+@item strip-all
+@samp{-s} in @code{strip}.
+@item strip-debug
+@samp{-S} in @code{strip}.
+@item submitter
+@samp{-s} in @code{shar}.
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+@item suffix-format
+@samp{-b} in @code{csplit}.
+@item sum
+@samp{-s} in @code{gprof}.
+@item summarize
+@samp{-s} in @code{du}.
+@item symbolic
+@samp{-s} in @code{ln}.
+@item symbols
+Used in GDB and @code{objdump}.
+@item synclines
+@samp{-s} in @code{m4}.
+@item sysname
+@samp{-s} in @code{uname}.
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+@item tabsize
+@samp{-T} in @code{ls}.
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+@samp{-t} in @code{wdiff}.
+@item text
+@samp{-a} in @code{diff}.
+@item text-files
+@samp{-T} in @code{shar}.
+@item time
+Used in @code{ls} and @code{touch}.
+@item timeout
+Specify how long to wait before giving up on some operation.
+@item to-stdout
+@samp{-O} in @code{tar}.
+@item total
+@samp{-c} in @code{du}.
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+@item trace
+@samp{-t} in @code{m4}.
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-W traditional} in @code{gawk};
+@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
+@item tty
+Used in GDB.
+@item typedefs
+@samp{-t} in @code{ctags}.
+@item typedefs-and-c++
+@samp{-T} in @code{ctags}.
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+@item uncompress
+@samp{-z} in @code{tar}.
+@item unconditional
+@samp{-u} in @code{cpio}.
+@item undefine
+@samp{-U} in @code{m4}.
+@item undefined-only
+@samp{-u} in @code{nm}.
+@item update
+@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
+@item usage
+Used in @code{gawk}; same as @samp{--help}.
+@item uuencode
+@samp{-B} in @code{shar}.
+@item vanilla-operation
+@samp{-V} in @code{shar}.
+@item verbose
+Print more information about progress.  Many programs support this.
+@item verify
+@samp{-W} in @code{tar}.
+@item version
+Print the version number.
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+@item vgrind
+@samp{-v} in @code{ctags}.
+@item volume
+@samp{-V} in @code{tar}.
+@item what-if
+@samp{-W} in Make.
+@item whole-size-limit
+@samp{-l} in @code{shar}.
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+@item word-regexp
+@samp{-W} in @code{ptx}.
+@item writable
+@samp{-T} in @code{who}.
+@item zeros
+@samp{-z} in @code{gprof}.
+@end table
+@node Memory Usage
+@section Memory Usage
+If it typically uses just a few meg of memory, don't bother making any
+effort to reduce memory usage.  For example, if it is impractical for
+other reasons to operate on files more than a few meg long, it is
+reasonable to read entire input files into core to operate on them.
+However, for programs such as @code{cat} or @code{tail}, that can
+usefully operate on very large files, it is important to avoid using a
+technique that would artificially limit the size of files it can handle.
+If a program works by lines and could be applied to arbitrary
+user-supplied input files, it should keep only a line in memory, because
+this is not very hard and users will want to be able to operate on input
+files that are bigger than will fit in core all at once.
+If your program creates complicated data structures, just make them in
+core and give a fatal error if @code{malloc} returns zero.
+@node Writing C
+@chapter Making The Best Use of C
+This @value{CHAPTER} provides advice on how best to use the C language
+when writing GNU software.
+@menu
+* Formatting::                  Formatting Your Source Code
+* Comments::                    Commenting Your Work
+* Syntactic Conventions::       Clean Use of C Constructs
+* Names::                       Naming Variables and Functions
+* System Portability::          Portability between different operating systems
+* CPU Portability::             Supporting the range of CPU types
+* System Functions::            Portability and ``standard'' library functions
+* Internationalization::        Techniques for internationalization
+* Mmap::                        How you can safely use @code{mmap}.
+@end menu
+@node Formatting
+@section Formatting Your Source Code
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero.  Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+It is also important for function definitions to start the name of the
+function in column zero.  This helps people to search for function
+definitions, and may also help certain tools recognize them.  Thus,
+the proper format is this:
+@example
+static char *
+concat (s1, s2)        /* Name starts in column zero here */
+char *s1, *s2;
+@{                     /* Open brace in column zero here */
+@dots{}
+@}
+@end example
+@noindent
+or, if you want to use @sc{ansi} C, format the definition like this:
+@example
+static char *
+concat (char *s1, char *s2)
+@{
+@dots{}
+@}
+@end example
+In @sc{ansi} C, if the arguments don't fit nicely on one line,
+split it like this:
+@example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+double a_double, float a_float)
+@dots{}
+@end example
+For the body of the function, we prefer code formatted like this:
+@example
+if (x < foo (y, z))
+haha = bar[4] + 5;
+else
+@{
+while (z)
+@{
+haha += foo (z, z);
+z--;
+@}
+return ++x + bar ();
+@}
+@end example
+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:
+@example
+if (foo_this_is_long && bar > win (x, y, z)
+&& remaining_condition)
+@end example
+Try to avoid having two operators of different precedence at the same
+level of indentation.  For example, don't write this:
+@example
+mode = (inmode[j] == VOIDmode
+|| GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+? outmode[j] : inmode[j]);
+@end example
+Instead, use extra parentheses so that the indentation shows the nesting:
+@example
+mode = ((inmode[j] == VOIDmode
+|| (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+? outmode[j] : inmode[j]);
+@end example
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+but Emacs would mess it up:
+@example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
++ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+@end example
+But adding a set of parentheses solves the problem:
+@example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
++ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+@end example
+Format do-while statements like this:
+@example
+do
+@{
+a = foo (a);
+@}
+while (a > 0);
+@end example
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function).  It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page.  The formfeeds should appear alone on lines by themselves.
+@node Comments
+@section Commenting Your Work
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}.
+Please write the comments in a GNU program in English, because English
+is the one language that nearly all programmers in all countries can
+read.  If you do not write English well, please write comments in
+English as well as you can, then ask other people to help rewrite them.
+If you can't write comments in English, please find someone to work with
+you and translate your comments into English.
+Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for.  It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion.  If there is anything nonstandard about
+its use (such as an argument of type @code{char *} which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+Also explain the significance of the return value, if there is one.
+Please put two spaces after the end of a sentence in your comments, so
+that the Emacs sentence commands will work.  Also, please write
+complete sentences and capitalize the first word.  If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier.  If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., ``The identifier lower-case is @dots{}'').
+The comment on a function is much clearer if you use the argument
+names to speak about the argument values.  The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself.  Thus, ``the inode
+number NODE_NUM'' rather than ``an inode''.
+There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the function
+itself would be off the bottom of the screen.
+There should be a comment on each static variable as well, like this:
+@example
+/* Nonzero means truncate lines in the display;
+zero means continue them.  */
+int truncate_lines;
+@end example
+Every @samp{#endif} should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested.  The comment should
+state the condition of the conditional that is ending, @emph{including
+its sense}.  @samp{#else} should have a comment describing the condition
+@emph{and sense} of the code that follows.  For example:
+@example
+@group
+#ifdef foo
+@dots{}
+#else /* not foo */
+@dots{}
+#endif /* not foo */
+@end group
+@group
+#ifdef foo
+@dots{}
+#endif /* foo */
+@end group
+@end example
+@noindent
+but, by contrast, write the comments this way for a @samp{#ifndef}:
+@example
+@group
+#ifndef foo
+@dots{}
+#else /* foo */
+@dots{}
+#endif /* foo */
+@end group
+@group
+#ifndef foo
+@dots{}
+#endif /* not foo */
+@end group
+@end example
+@node Syntactic Conventions
+@section Clean Use of C Constructs
+Please explicitly declare all arguments to functions.
+Don't omit them just because they are @code{int}s.
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file.  Don't put @code{extern} declarations inside
+functions.
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function.  Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful.  This not only makes programs easier to understand, it also
+facilitates optimization by good compilers.  You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses.  This makes the program even cleaner.
+Don't use local variables or parameters that shadow global identifiers.
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead.  For example, instead
+of this:
+@example
+@group
+int    foo,
+bar;
+@end group
+@end example
+@noindent
+write either this:
+@example
+int foo, bar;
+@end example
+@noindent
+or this:
+@example
+int foo;
+int bar;
+@end example
+@noindent
+(If they are global variables, each should have a comment preceding it
+anyway.)
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
+@example
+if (foo)
+if (bar)
+win ();
+else
+lose ();
+@end example
+@noindent
+always like this:
+@example
+if (foo)
+@{
+if (bar)
+win ();
+else
+lose ();
+@}
+@end example
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
+@example
+if (foo)
+@dots{}
+else if (bar)
+@dots{}
+@end example
+@noindent
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
+@example
+if (foo)
+@dots{}
+else
+@{
+if (bar)
+@dots{}
+@}
+@end example
+Don't declare both a structure tag and variables or typedefs in the
+same declaration.  Instead, declare the structure tag separately
+and then use it to declare the variables or typedefs.
+Try to avoid assignments inside @code{if}-conditions.  For example,
+don't write this:
+@example
+if ((foo = (char *) malloc (sizeof *foo)) == 0)
+fatal ("virtual memory exhausted");
+@end example
+@noindent
+instead, write this:
+@example
+foo = (char *) malloc (sizeof *foo);
+if (foo == 0)
+fatal ("virtual memory exhausted");
+@end example
+Don't make the program ugly to placate @code{lint}.  Please don't insert any
+casts to @code{void}.  Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+@node Names
+@section Naming Variables and Functions
+The names of global variables and functions in a program serve as
+comments of a sort.  So don't choose terse names---instead, look for
+names that give useful information about the meaning of the variable or
+function.  In a GNU program, names should be English, like other
+comments.
+Local variable names can be shorter, because they are used only within
+one context, where (presumably) comments explain their purpose.
+Try to limit your use of abbreviations in symbol names.  It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them.  Stick to lower case; reserve
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
+For example, you should use names like @code{ignore_space_change_flag};
+don't use names like @code{iCantReadThis}.
+Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter.  A comment should state both the exact meaning of
+the option and its letter.  For example,
+@example
+@group
+/* Ignore changes in horizontal whitespace (-b).  */
+int ignore_space_change_flag;
+@end group
+@end example
+When you want to define names with constant integer values, use
+@code{enum} rather than @samp{#define}.  GDB knows about enumeration
+constants.
+Use file names of 14 characters or less, to avoid creating gratuitous
+problems on older System V systems.  You can use the program
+@code{doschk} to test for this.  @code{doschk} also tests for potential
+name conflicts if the files were loaded onto an MS-DOS file
+system---something you may or may not care about.
+@node System Portability
+@section Portability between System Types
+In the Unix world, ``portability'' refers to porting to different Unix
+versions.  For a GNU program, this kind of portability is desirable, but
+not paramount.
+The primary purpose of GNU software is to run on top of the GNU kernel,
+compiled with the GNU C compiler, on various types of @sc{cpu}.  The
+amount and kinds of variation among GNU systems on different @sc{cpu}s
+will be comparable to the variation among Linux-based GNU systems or
+among BSD systems today.  So the kinds of portability that are absolutely
+necessary are quite limited.
+But many users do run GNU software on non-GNU Unix or Unix-like systems.
+So supporting a variety of Unix-like systems is desirable, although not
+paramount.
+The easiest way to achieve portability to most Unix-like systems is to
+use Autoconf.  It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+Avoid using the format of semi-internal data bases (e.g., directories)
+when there is a higher-level alternative (@code{readdir}).
+As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work.  When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+@node CPU Portability
+@section Portability between @sc{cpu}s
+Even GNU systems will differ because of differences among @sc{cpu}
+types---for example, difference in byte ordering and alignment
+requirements.  It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+@code{int} will be less than 32 bits.  We don't support 16-bit machines
+in GNU.
+Don't assume that the address of an @code{int} object is also the
+address of its least-significant byte.  This is false on big-endian
+machines.  Thus, don't make the following mistake:
+@example
+int c;
+@dots{}
+while ((c = getchar()) != EOF)
+write(file_descriptor, &c, 1);
+@end example
+When calling functions, you need not worry about the difference between
+pointers of various types, or between pointers and integers.  On most
+machines, there's no difference anyway.  As for the few machines where
+there is a difference, all of them support @sc{ansi} C, so you can use
+prototypes (conditionalized to be active only in @sc{ansi} C) to make
+the code work on those systems.
+In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system.  For example, many GNU programs have error-reporting functions
+that pass their arguments along to @code{printf} and friends:
+@example
+error (s, a1, a2, a3)
+char *s;
+char *a1, *a2, *a3;
+@{
+fprintf (stderr, "error: ");
+fprintf (stderr, s, a1, a2, a3);
+@}
+@end example
+@noindent
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument, and it is much simpler than any
+``correct'' alternative.  Be sure @emph{not} to use a prototype for such
+functions.
+However, avoid casting pointers to integers unless you really need to.
+Outside of special situations, 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---it is ok to
+do it, but you'll have to make explicit provisions to handle different
+word sizes.
+@node System Functions
+@section Calling System Functions
+C implementations differ substantially.  @sc{ansi} C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-@sc{ansi} compilers.  This chapter gives
+recommendations for how to use the more or less standard C library
+functions to avoid unnecessary loss of portability.
+@itemize @bullet
+@item
+Don't use the value of @code{sprintf}.  It returns the number of
+characters written on some systems, but not on all systems.
+@item
+@code{main} should be declared to return type @code{int}.  It should
+terminate either by calling @code{exit} or by returning the integer
+status code; make sure it cannot ever return an undefined value.
+@item
+Don't declare system functions explicitly.
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions.  If the headers don't declare a function, let it
+remain undeclared.
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens; thus, the disadvantage is only
+theoretical.  By contrast, actual declarations have frequently caused
+actual conflicts.
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not an @sc{ansi} prototype.  The more you
+specify about the function, the more likely a conflict.
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}.  These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine.  For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+@item
+The string functions require special treatment.  Some Unix systems have
+a header file @file{string.h}; others have @file{strings.h}.  Neither
+file name is portable.  There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+That causes less of a problem than you might think.  The newer @sc{ansi}
+string functions should be avoided anyway because many systems still
+don't support them.  The string functions you can use are these:
+@example
+strcpy   strncpy   strcat   strncat
+strlen   strcmp    strncmp
+strchr   strrchr
+@end example
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values.  Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases.  It is trivial to
+avoid using their values, so do that.
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+The search functions must be declared to return @code{char *}.  Luckily,
+there is no variation in the data type they return.  But there is
+variation in their names.  Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}.  Some systems support both pairs of
+names, but neither pair works on all systems.
+You should pick a single pair of names and use it throughout your
+program.  (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr} for new programs, since those are the standard @sc{ansi}
+names.)  Declare both of those names as functions returning @code{char
+*}.  On systems which don't support those names, define them as macros
+in terms of the other pair.  For example, here is what to put at the
+beginning of your file (or in a header) if you want to use the names
+@code{strchr} and @code{strrchr} throughout:
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+@node Internationalization
+@section Internationalization
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages.  You should use this
+library in every program.  Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+Using GNU gettext involves putting a call to the @code{gettext} macro
+around each string that might need translation---like this:
+@example
+printf (gettext ("Processing file `%s'..."));
+@end example
+@noindent
+This permits GNU gettext to replace the string @code{"Processing file
+`%s'..."} with a translated version.
+Once a program uses gettext, please make a point of writing calls to
+@code{gettext} when you add new strings that call for translation.
+Using GNU gettext in a package involves specifying a @dfn{text domain
+name} for the package.  The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package---for example, @samp{fileutils} for the GNU file utilities.
+To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences.  When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+Here is an example of what not to do:
+@example
+printf ("%d file%s processed", nfiles,
+nfiles != 1 ? "s" : "");
+@end example
+@noindent
+The problem with that example is that it assumes that plurals are made
+by adding `s'.  If you apply gettext to the format string, like this,
+@example
+printf (gettext ("%d file%s processed"), nfiles,
+nfiles != 1 ? "s" : "");
+@end example
+@noindent
+the message can use different words, but it will still be forced to use
+`s' for the plural.  Here is a better way:
+@example
+printf ((nfiles != 1 ? "%d files processed"
+: "%d file processed"),
+nfiles);
+@end example
+@noindent
+This way, you can apply gettext to each of the two strings
+independently:
+@example
+printf ((nfiles != 1 ? gettext ("%d files processed")
+: gettext ("%d file processed")),
+nfiles);
+@end example
+@noindent
+This can be any method of forming the plural of the word for ``file'', and
+also handles languages that require agreement in the word for
+``processed''.
+A similar problem appears at the level of sentence structure with this
+code:
+@example
+printf ("#  Implicit rule search has%s been done.\n",
+f->tried_implicit ? "" : " not");
+@end example
+@noindent
+Adding @code{gettext} calls to this code cannot give correct results for
+all languages, because negation in some languages requires adding words
+at more than one place in the sentence.  By contrast, adding
+@code{gettext} calls does the job straightfowardly if the code starts
+out like this:
+@example
+printf (f->tried_implicit
+? "#  Implicit rule search has been done.\n",
+: "#  Implicit rule search has not been done.\n");
+@end example
+@node Mmap
+@section Mmap
+Don't assume that @code{mmap} either works on all files or fails
+for all files.  It may work on some files and fail on others.
+The proper way to use @code{mmap} is to try it on the specific file for
+which you want to use it---and if @code{mmap} doesn't work, fall back on
+doing the job in another way using @code{read} and @code{write}.
+The reason this precaution is needed is that the GNU kernel (the HURD)
+provides a user-extensible file system, in which there can be many
+different kinds of ``ordinary files.''  Many of them support
+@code{mmap}, but some do not.  It is important to make programs handle
+all these kinds of files.
+@node Documentation
+@chapter Documenting Programs
+@menu
+* GNU Manuals::                 Writing proper manuals.
+* Manual Structure Details::    Specific structure conventions.
+* License for Manuals::         Writing the distribution terms for a manual.
+* NEWS File::                   NEWS files supplement manuals.
+* Change Logs::                 Recording Changes
+* Man Pages::                   Man pages are secondary.
+* Reading other Manuals::       How far you can go in learning
+from other manuals.
+@end menu
+@node GNU Manuals
+@section GNU Manuals
+The preferred way to document part of the GNU system is to write a
+manual in the Texinfo formatting language.  This makes it possible to
+produce a good quality formatted book, using @TeX{}, and to generate an
+Info file.  It is also possible to generate HTML output from Texinfo
+source.  See the Texinfo manual, either the hardcopy, or the on-line
+version available through @code{info} or the Emacs Info subsystem
+(@kbd{C-h i}).
+Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know.  But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it.  Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented---but
+often they are different.  Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual.  That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+Instead, each manual should cover a coherent @emph{topic}.  For example,
+instead of a manual for @code{diff} and a manual for @code{diff3}, we
+have one manual for ``comparison of files'' which covers both of those
+programs, as well as @code{cmp}.  By documenting these programs
+together, we can make the whole subject clearer.
+The manual which discusses a program should document all of the
+program's command-line options and all of its commands.  It should give
+examples of their use.  But don't organize the manual as a list of
+features.  Instead, organize it logically, by subtopics.  Address the
+questions that a user will ask when thinking about the job that the
+program does.
+In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside).  A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
+That is not as hard as it first sounds.  Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense.  Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs.  The watchword is, @emph{at each point, address
+the most fundamental and important issue raised by the preceding text.}
+If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject.  These provide
+the framework for a beginner to understand the rest of the manual.  The
+Bison manual provides a good example of how to do this.
+Don't use Unix man pages as a model for how to write GNU documentation;
+most of them are terse, badly structured, and give inadequate
+explanation of the underlying concepts.  (There are, of course
+exceptions.)  Also Unix man pages use a particular format which is
+different from what we use in GNU manuals.
+Please include an email address in the manual for where to report
+bugs @emph{in the manual}.
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead.  We use the term
+``path'' only for search paths, which are lists of directory names.
+Please do not use the term ``illegal'' to refer to erroneous input to a
+computer program.  Please use ``invalid'' for this, and reserve the term
+``illegal'' for violations of law.
+@node Manual Structure Details
+@section Manual Structure Details
+The title page of the manual should state the version of the programs or
+packages documented in the manual.  The Top node of the manual should
+also contain this information.  If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+Each program documented in the manual should have a node named
+@samp{@var{program} Invocation} or @samp{Invoking @var{program}}.  This
+node (together with its subnodes, if any) should describe the program's
+command line arguments and how to run it (the sort of information people
+would look in a man page for).  Start with an @samp{@@example}
+containing a template for all the options and arguments that the program
+uses.
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns.  This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+If one manual describes several programs, it should have such a node for
+each program described.
+@node License for Manuals
+@section License for Manuals
+If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
+contains chapters that make political or personal statements, please
+copy the distribution terms of the GNU Emacs Manual, and adapt it by
+modifying appropriately the list of special chapters that may not be
+modified or deleted.
+If the manual does not contain any such chapters, then imitate the
+simpler distribution terms of the Texinfo manual.
+@node NEWS File
+@section The NEWS File
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning.  In each new release, add items to the front of the file and
+identify the version they pertain to.  Don't discard old items; leave
+them in the file after the newer items.  This way, a user upgrading from
+any previous version can see what is new.
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+@node Change Logs
+@section Change Logs
+Keep a change log to describe all the changes made to program source
+files.  The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+@menu
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+@end menu
+@node Change Log Concepts
+@subsection Change Log Concepts
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it.  What they want from a change log is a
+clear explanation of how the earlier version differed.
+The change log file is normally called @file{ChangeLog} and covers an
+entire directory.  Each directory can have its own change log, or a
+directory can use the change log of its parent directory--it's up to
+you.
+Another alternative is to record change log information with a version
+control system such as RCS or CVS.  This can be converted automatically
+to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
+@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
+There's no need to describe the full purpose of the changes or how they
+work together.  If you think that a change calls for explanation, you're
+probably right.  Please do explain it---but please put the explanation
+in comments in the code, where people will see it whenever they see the
+code.  For example, ``New function'' is enough for the change log when
+you add a function, because there should be a comment before the
+function definition to explain what it does.
+However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+The easiest way to add an entry to @file{ChangeLog} is with the Emacs
+command @kbd{M-x add-change-log-entry}.  An entry should have an
+asterisk, the name of the changed file, and then in parentheses the name
+of the changed functions, variables or whatever, followed by a colon.
+Then describe the changes you made to that function or variable.
+@node Style of Change Logs
+@subsection Style of Change Logs
+Here are some examples of change log entries:
+@example
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+* sort.el (sort-subr): Return nil.
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+@end example
+It's important to name the changed function or variable in full.  Don't
+abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+For example, some people are tempted to abbreviate groups of function
+names by writing @samp{* register.el (@{insert,jump-to@}-register)};
+this is not a good idea, since searching for @code{jump-to-register} or
+@code{insert-register} would not find that entry.
+Separate unrelated change log entries with blank lines.  When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them.  Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+@node Simple Changes
+@subsection Simple Changes
+Certain simple kinds of changes don't need much detail in the change
+log.
+When you change the calling sequence of a function in a simple fashion,
+and you change all the callers of the function, there is no need to make
+individual entries for all the callers that you changed.  Just write in
+the entry for the function being called, ``All callers changed.''
+@example
+* keyboard.c (Fcommand_execute): New arg SPECIAL.
+All callers changed.
+@end example
+When you change just comments or doc strings, it is enough to write an
+entry for the file, without mentioning the functions.  Just ``Doc
+fixes'' is enough for the change log.
+There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix.  Documentation does not consist of parts that must interact in a
+precisely engineered fashion.  To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+@node Conditional Changes
+@subsection Conditional Changes
+C programs often contain compile-time @code{#if} conditionals.  Many
+changes are conditional; sometimes you add a new definition which is
+entirely contained in a conditional.  It is very useful to indicate in
+the change log the conditions for which the change applies.
+Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+Here is a simple example, describing a change which is conditional but
+does not have a function or entity name associated with it:
+@example
+* xterm.c [SOLARIS2]: Include string.h.
+@end example
+Here is an entry describing a new definition which is entirely
+conditional.  This new definition for the macro @code{FRAME_WINDOW_P} is
+used only when @code{HAVE_X_WINDOWS} is defined:
+@example
+* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+@end example
+Here is an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+@example
+* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+@end example
+Here is an entry for a change that takes affect only when
+a certain macro is @emph{not} defined:
+@example
+(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+@end example
+@node Man Pages
+@section Man Pages
+In the GNU project, man pages are secondary.  It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed.  The time
+you spend on the man page is time taken away from more useful work.
+For a simple program which changes little, updating the man page may be
+a small job.  Then there is little reason not to include a man page, if
+you have one.
+For a large program that changes a great deal, updating a man page may
+be a substantial burden.  If a user offers to donate a man page, you may
+find this gift costly to accept.  It may be better to refuse the man
+page unless the same person agrees to take full responsibility for
+maintaining it---so that you can wash your hands of it entirely.  If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating.  If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative.  The note should say how to access the Texinfo
+documentation.
+@node Reading other Manuals
+@section Reading other Manuals
+There may be non-free books or documentation files that describe the
+program you are documenting.
+It is ok to use these documents for reference, just as the author of a
+new algebra textbook can read other books on algebra.  A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject.  But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation.  Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+@node Managing Releases
+@chapter The Release Process
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP.  You should set up your software so
+that it can be configured to run on a variety of systems.  Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below.  Doing so
+makes it easy to include your package into the larger framework of
+all GNU software.
+@menu
+* Configuration::               How Configuration Should Work
+* Makefile Conventions::	Makefile Conventions
+* Releases::                    Making Releases
+@end menu
+@node Configuration
+@section How Configuration Should Work
+Each GNU distribution should come with a shell script named
+@code{configure}.  This script is given arguments which describe the
+kind of machine and system you want to compile the program for.
+The @code{configure} script must record the configuration options so
+that they affect compilation.
+One way to do this is to make a link from a standard name such as
+@file{config.h} to the proper configuration file for the chosen system.
+If you use this technique, the distribution should @emph{not} contain a
+file named @file{config.h}.  This is so that people won't be able to
+build the program without configuring it first.
+Another thing that @code{configure} can do is to edit the Makefile.  If
+you do this, the distribution should @emph{not} contain a file named
+@file{Makefile}.  Instead, it should include a file @file{Makefile.in} which
+contains the input used for editing.  Once again, this is so that people
+won't be able to build the program without configuring it first.
+If @code{configure} does write the @file{Makefile}, then @file{Makefile}
+should have a target named @file{Makefile} which causes @code{configure}
+to be rerun, setting up the same configuration that was set up last
+time.  The files that @code{configure} reads should be listed as
+dependencies of @file{Makefile}.
+All the files which are output from the @code{configure} script should
+have comments at the beginning explaining that they were generated
+automatically using @code{configure}.  This is so that users won't think
+of trying to edit them by hand.
+The @code{configure} script should write a file named @file{config.status}
+which describes which configuration options were specified when the
+program was last configured.  This file should be a shell script which,
+if run, will recreate the same configuration.
+The @code{configure} script should accept an option of the form
+@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
+(if it is not the current directory).  This makes it possible to build
+the program in a separate directory, so that the actual source directory
+is not modified.
+If the user does not specify @samp{--srcdir}, then @code{configure} should
+check both @file{.} and @file{..} to see if it can find the sources.  If
+it finds the sources in one of these places, it should use them from
+there.  Otherwise, it should report that it cannot find the sources, and
+should exit with nonzero status.
+Usually the easy way to support @samp{--srcdir} is by editing a
+definition of @code{VPATH} into the Makefile.  Some rules may need to
+refer explicitly to the specified source directory.  To make this
+possible, @code{configure} can add to the Makefile a variable named
+@code{srcdir} whose value is precisely the specified directory.
+The @code{configure} script should also take an argument which specifies the
+type of system to build the program for.  This argument should look like
+this:
+@example
+@var{cpu}-@var{company}-@var{system}
+@end example
+For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
+The @code{configure} script needs to be able to decode all plausible
+alternatives for how to describe a machine.  Thus, @samp{sun3-sunos4.1}
+would be a valid alias.  For many programs, @samp{vax-dec-ultrix} would
+be an alias for @samp{vax-dec-bsd}, simply because the differences
+between Ultrix and BSD are rarely noticeable, but a few programs
+might need to distinguish them.
+@c Real 4.4BSD now runs on some Suns.
+There is a shell script called @file{config.sub} that you can use
+as a subroutine to validate system types and canonicalize aliases.
+Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}.  This allows users to choose which
+optional features to include.  Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another.  No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior.  The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+@c  Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+Possible values of @var{package} include
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
+@samp{gdb},
+@samp{x},
+and
+@samp{x-toolkit}.
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files.  That is outside the scope of what @samp{--with}
+options are for.
+@item --nfp
+The target machine has no floating point processor.
+@item --gas
+The target machine assembler is GAS, the GNU assembler.
+This is obsolete; users should use @samp{--with-gnu-as} instead.
+@item --x
+The target machine has the X Window System installed.
+This is obsolete; users should use @samp{--with-x} instead.
+@end table
+All @code{configure} scripts should accept all of these ``detail''
+options, whether or not they make any difference to the particular
+package at hand.  In particular, they should accept any option that
+starts with @samp{--with-} or @samp{--enable-}.  This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of.  That is deliberate.  We want to limit the possible
+configuration options in GNU software.  We do not want GNU programs to
+have idiosyncratic configuration options.
+Packages that perform part of the compilation process may support cross-compilation.
+In such a case, the host and target machines for the program may be
+different.  The @code{configure} script should normally treat the
+specified type of system as both the host and the target, thus producing
+a program which works for the same type of machine that it runs on.
+The way to build a cross-compiler, cross-assembler, or what have you, is
+to specify the option @samp{--host=@var{hosttype}} when running
+@code{configure}.  This specifies the host system without changing the
+type of target system.  The syntax for @var{hosttype} is the same as
+described above.
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on.  Compilation packages accept a
+configuration option @samp{--build=@var{hosttype}} for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+Programs for which cross-operation is not meaningful need not accept the
+@samp{--host} option, because configuring an entire operating system for
+cross-operation is not a meaningful thing.
+Some programs have ways of configuring themselves automatically.  If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo.  Done by roland@gnu.ai.mit.edu on 1/6/93.
+@comment For this document, turn chapters into sections, etc.
+@lowersections
+@include make-stds.texi
+@raisesections
+@node Releases
+@section Making Releases
+Package the distribution of @code{Foo version 69.96} up in a gzipped tar
+file with the name @file{foo-69.96.tar.gz}.  It should unpack into a
+subdirectory named @file{foo-69.96}.
+Building and installing the program should never modify any of the files
+contained in the distribution.  This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}.  Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+The distribution should contain a file named @file{README} which gives
+the name of the package, and a general description of what it does.  It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any.  The @file{README} file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+The @file{README} file should refer to the file @file{INSTALL}, which
+should contain an explanation of the installation procedure.
+The @file{README} file should also refer to the file which contains the
+copying conditions.  The GNU GPL, if used, should be in a file called
+@file{COPYING}.  If the GNU LGPL is used, it should be in a file called
+@file{COPYING.LIB}.
+Naturally, all the source files must be in the distribution.  It is okay
+to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them.  We commonly include non-source files
+produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+Non-source files that might actually be modified by building and
+installing the program should @strong{never} be included in the
+distribution.  So if you do distribute non-source files, always make
+sure they are up to date when you make a new distribution.
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+Make sure that all the files in the distribution are world-readable.
+Make sure that no file name in the distribution is more than 14
+characters long.  Likewise, no file created by building the program
+should have a name longer than 14 characters.  The reason for this is
+that some systems adhere to a foolish interpretation of the @sc{posix}
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+Don't include any symbolic links in the distribution itself.  If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links.  Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
+Try to make sure that all the file names will be unique on MS-DOS.  A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters.  MS-DOS will truncate extra
+characters both before and after the period.  Thus,
+@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
+distinct.
+Include in your distribution a copy of the @file{texinfo.tex} you used
+to test print any @file{*.texinfo} or @file{*.texi} files.
+Likewise, if your program uses small GNU software packages like regex,
+getopt, obstack, or termcap, include them in the distribution file.
+Leaving them out would make the distribution file a little smaller at
+the expense of possible inconvenience to a user who doesn't know what
+other files to get.
+@node References
+@chapter References to Non-Free Software and Documentation
+A GNU program should not recommend use of any non-free program.  We
+can't stop some people from writing proprietary programs, or stop other
+people from using them.  But we can and should avoid helping to
+advertise them to new customers.
+Sometimes it is important to mention how to build your package on top of
+some non-free operating system or other non-free base package.  In such
+cases, please mention the name of the non-free package or system in the
+briefest possible way.  Don't include any references for where to find
+more information about the proprietary program.  The goal should be that
+people already using the proprietary program will get the advice they
+need about how to use your free program, while people who don't already
+use the proprietary program will not see anything to encourage them to
+take an interest in it.
+Likewise, a GNU package should not refer the user to any non-free
+documentation for free software.  The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+@contents
+@bye

Mercurial > hg > xemacs-beta

comparison man/standards.texi @ 428:3ecd8885ac67 r21-2-22