X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=b550bd022aaa591ccdf8b926df7b0861d5957096;hb=b187ff0528e2a081392a834e684d1d0c161708a7;hp=02848ef275dc801556a0824864551768a2c41baa;hpb=9a5672c5b879f0817149c499eb8f63497122b148;p=gnulib.git
diff --git a/doc/standards.texi b/doc/standards.texi
index 02848ef27..b550bd022 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3,7 +3,7 @@
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate May 5, 2008
+@set lastupdate February 17, 2010
@c %**end of header
@dircategory GNU organization
@@ -27,16 +27,15 @@
The GNU coding standards, last updated @value{lastupdate}.
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2
-or any later version published by the Free Software Foundation;
-with no Invariant Sections, with no
-Front-Cover Texts, and with no Back-Cover Texts.
-A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
@end copying
@titlepage
@@ -82,9 +81,6 @@ 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.
-This release of the GNU Coding Standards was last updated
-@value{lastupdate}.
-
@cindex where to obtain @code{standards.texi}
@cindex downloading this manual
If you did not obtain this file directly from the GNU project and
@@ -93,6 +89,18 @@ Coding Standards from the GNU web server in many
different formats, including the Texinfo source, PDF, HTML, DVI, plain
text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
+If you are maintaining an official GNU package, in addition to this
+document, please read and follow the GNU maintainer information
+(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU
+Software}).
+
+@cindex @code{gnustandards-commit@@gnu.org} mailing list
+If you want to receive diffs for every change to these GNU documents,
+join the mailing list @code{gnustandards-commit@@gnu.org}, via the web
+interface at
+@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
+Archives are also available there.
+
Corrections or suggestions for this document should be sent to
@email{bug-standards@@gnu.org}. If you make a suggestion, please include a
suggested new wording for it; our time is limited. We prefer a context
@@ -115,6 +123,10 @@ The GNU Hello program serves as an example of how to follow the GNU
coding standards for a trivial program.
@uref{http://www.gnu.org/software/hello/hello.html}.
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
+
@node Legal Issues
@chapter Keeping Free Software Free
@cindex legal aspects
@@ -314,7 +326,7 @@ Guile also includes bindings for GTK+/GNOME, making it practical to
write modern GUI functionality within Guile. We don't reject programs
written in other ``scripting languages'' such as Perl and Python, but
using Guile is very important for the overall consistency of the GNU
-system.
+system.
@node Compatibility
@@ -497,7 +509,7 @@ and is not always appropriate, following this policy would have saved
GCC developers many hours, or even days, per year.
In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
-GCC which cannot be simply used in @code{if( ...)} statements, there is
+GCC which cannot be simply used in @code{if (...)} statements, there is
an easy workaround. Simply introduce another macro
@code{HAS_REVERSIBLE_CC_MODE} as in the following example:
@@ -526,6 +538,7 @@ command line interface, and how libraries should behave.
* Graphical Interfaces:: Standards for graphical interfaces.
* Command-Line Interfaces:: Standards for command line interfaces.
* Option Table:: Table of long options.
+* OID Allocations:: Table of OID slots for GNU.
* Memory Usage:: When and how to care about memory needs.
* File Usage:: Which files to use, and where.
@end menu
@@ -677,7 +690,7 @@ creating temporary files in world-writable directories. In C, you can
avoid this problem by creating temporary files in this manner:
@example
-fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
@end example
@noindent
@@ -1086,13 +1099,19 @@ is seen, and the program should not perform its normal function.
@cindex address for bug reports
@cindex bug reports
-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:
+Near the end of the @samp{--help} option's output, please place lines
+giving the email address for bug reports, the package's home page
+(normally @indicateurl{http://www.gnu.org/software/@var{pkg}}, and the
+general page for help using GNU programs. The format should be like this:
@example
-Report bugs to @var{mailing-address}.
+Report bugs to: @var{mailing-address}
+@var{pkg} home page:
+General help using GNU software:
@end example
+It is ok to mention other appropriate mailing lists and web pages.
+
@node Option Table
@section Table of Long Options
@@ -1145,10 +1164,10 @@ and @code{unexpand}.
@samp{-v} in @code{gawk}.
@item assume-new
-@samp{-W} in Make.
+@samp{-W} in @code{make}.
@item assume-old
-@samp{-o} in Make.
+@samp{-o} in @code{make}.
@item auto-check
@samp{-a} in @code{recode}.
@@ -1270,7 +1289,7 @@ Used in @code{tar} and @code{cpio}.
@samp{-d} in @code{touch}.
@item debug
-@samp{-d} in Make and @code{m4};
+@samp{-d} in @code{make} and @code{m4};
@samp{-t} in Bison.
@item define
@@ -1317,7 +1336,7 @@ specially.
@samp{-X} in @code{strip}.
@item dry-run
-@samp{-n} in Make.
+@samp{-n} in @code{make}.
@item ed
@samp{-e} in @code{diff}.
@@ -1335,7 +1354,7 @@ specially.
@samp{-N} in @code{diff}.
@item environment-overrides
-@samp{-e} in Make.
+@samp{-e} in @code{make}.
@item eof
@samp{-e} in @code{xargs}.
@@ -1387,9 +1406,8 @@ Used in GDB.
@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}.
+@samp{-f} in @code{gawk}, @code{info}, @code{make}, @code{mt},
+@code{sed}, and @code{tar}.
@item field-separator
@samp{-F} in @code{gawk}.
@@ -1501,7 +1519,7 @@ In @code{makeinfo}, output HTML.
@samp{-i} in @code{diff} and @code{wdiff}.
@item ignore-errors
-@samp{-i} in Make.
+@samp{-i} in @code{make}.
@item ignore-file
@samp{-i} in @code{ptx}.
@@ -1529,7 +1547,7 @@ In @code{makeinfo}, output HTML.
@samp{-I} in @code{m4}.
@item include-dir
-@samp{-I} in Make.
+@samp{-I} in @code{make}.
@item incremental
@samp{-G} in @code{tar}.
@@ -1563,13 +1581,13 @@ init file.
Used in @code{date}
@item jobs
-@samp{-j} in Make.
+@samp{-j} in @code{make}.
@item just-print
-@samp{-n} in Make.
+@samp{-n} in @code{make}.
@item keep-going
-@samp{-k} in Make.
+@samp{-k} in @code{make}.
@item keep-files
@samp{-k} in @code{csplit}.
@@ -1610,7 +1628,7 @@ Used in @code{gawk}.
@samp{-N} in @code{ls}.
@item load-average
-@samp{-l} in Make.
+@samp{-l} in @code{make}.
@item login
Used in @code{su}.
@@ -1628,7 +1646,7 @@ Used in @code{uname}.
@samp{-d} in @code{cpio}.
@item makefile
-@samp{-f} in Make.
+@samp{-f} in @code{make}.
@item mapped
Used in GDB.
@@ -1643,7 +1661,7 @@ Used in GDB.
@samp{-l} in @code{xargs}.
@item max-load
-@samp{-l} in Make.
+@samp{-l} in @code{make}.
@item max-procs
@samp{-P} in @code{xargs}.
@@ -1679,10 +1697,10 @@ Used in GDB.
@samp{-a} in @code{shar}.
@item new-file
-@samp{-W} in Make.
+@samp{-W} in @code{make}.
@item no-builtin-rules
-@samp{-r} in Make.
+@samp{-r} in @code{make}.
@item no-character-count
@samp{-w} in @code{shar}.
@@ -1709,7 +1727,7 @@ Used in GDB.
@samp{-2} in @code{wdiff}.
@item no-keep-going
-@samp{-S} in Make.
+@samp{-S} in @code{make}.
@item no-lines
@samp{-l} in Bison.
@@ -1784,7 +1802,7 @@ Used in GDB.
@samp{-o} in @code{tar}.
@item old-file
-@samp{-o} in Make.
+@samp{-o} in @code{make}.
@item one-file-system
@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
@@ -1869,10 +1887,10 @@ Used in @code{tar} and @code{cp}.
@samp{-L} in @code{cmp}.
@item print-data-base
-@samp{-p} in Make.
+@samp{-p} in @code{make}.
@item print-directory
-@samp{-w} in Make.
+@samp{-w} in @code{make}.
@item print-file-name
@samp{-o} in @code{nm}.
@@ -1893,7 +1911,7 @@ Specify an HTTP proxy.
@samp{-X} in @code{shar}.
@item question
-@samp{-q} in Make.
+@samp{-q} in @code{make}.
@item quiet
Used in many programs to inhibit the usual output. Every
@@ -1919,7 +1937,7 @@ Used in @code{gawk}.
Used in GDB.
@item recon
-@samp{-n} in Make.
+@samp{-n} in @code{make}.
@item record-number
@samp{-R} in @code{tar}.
@@ -1928,8 +1946,8 @@ Used in GDB.
Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
and @code{rm}.
-@item reference-limit
-Used in @code{makeinfo}.
+@item reference
+@samp{-r} in @code{touch}.
@item references
@samp{-r} in @code{ptx}.
@@ -2061,7 +2079,7 @@ a directory to start processing with.
@samp{-S} in @code{shar}.
@item stop
-@samp{-S} in Make.
+@samp{-S} in @code{make}.
@item strict
@samp{-s} in @code{recode}.
@@ -2131,7 +2149,7 @@ Specify how long to wait before giving up on some operation.
@samp{-c} in @code{du}.
@item touch
-@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+@samp{-t} in @code{make}, @code{ranlib}, and @code{recode}.
@item trace
@samp{-t} in @code{m4}.
@@ -2196,7 +2214,7 @@ Print the version number.
@samp{-V} in @code{tar}.
@item what-if
-@samp{-W} in Make.
+@samp{-W} in @code{make}.
@item whole-size-limit
@samp{-l} in @code{shar}.
@@ -2214,6 +2232,28 @@ Print the version number.
@samp{-z} in @code{gprof}.
@end table
+@node OID Allocations
+@section OID Allocations
+@cindex OID allocations for GNU
+@cindex SNMP
+@cindex LDAP
+@cindex X.509
+
+The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
+GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP,
+X.509 certificates, and so on. The web site
+@url{http://www.alvestrand.no/objectid} has a (voluntary) listing of
+many OID assignments.
+
+If you need a new slot for your GNU package, write
+@email{maintainers@@gnu.org}. Here is a list of arcs currently
+assigned:
+
+@example
+@include gnu-oids.texi
+@end example
+
+
@node Memory Usage
@section Memory Usage
@cindex memory usage
@@ -3491,7 +3531,7 @@ 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
+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
@@ -3499,22 +3539,21 @@ 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.
+There's no need to describe the full purpose of the changes or how
+they work together. However, sometimes it is useful to write one line
+to describe the overall purpose of a change or a batch of changes. If
+you think that a change calls for explanation, you're probably right.
+Please do explain it---but please put the full 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.
In the past, we recommended not mentioning changes in non-software
files (manuals, help files, etc.) in change logs. However, we've been
advised that it is a good idea to include them, for the sake of
copyright records.
-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
@@ -3715,15 +3754,10 @@ 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.
-Be sure that man pages include a copyright statement and free
-license. The simple all-permissive license is appropriate for simple
-man pages:
-
-@example
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
-@end example
+Be sure that man pages include a copyright statement and free license.
+The simple all-permissive license is appropriate for simple man pages
+(@pxref{License Notices for Other Files,,,maintain,Information for GNU
+Maintainers}).
For long man pages, with enough explanation and documentation that
they can be considered true manuals, use the GFDL (@pxref{License for
@@ -3775,15 +3809,23 @@ all GNU software.
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.
+The description here is the specification of the interface for the
+@code{configure} script in GNU packages. Many packages implement it
+using GNU Autoconf (@pxref{Top,, Introduction, autoconf, Autoconf})
+and/or GNU Automake (@pxref{Top,, Introduction, automake, Automake}),
+but you do not have to use these tools. You can implement it any way
+you like; for instance, by making @code{configure} be a wrapper around
+a completely different configuration system.
+
+Another way for the @code{configure} script to operate 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
@@ -3918,7 +3960,7 @@ is preferable to setting them in environment variables:
CC=gcc ./configure
@end example
as it helps to recreate the same configuration later with
-@file{config.status}.
+@file{config.status}. However, both methods should be supported.
@end table
All @code{configure} scripts should accept all of the ``detail''
@@ -4006,7 +4048,7 @@ 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}.
+@file{COPYING.LESSER}.
Naturally, all the source files must be in the distribution. It is okay
to include non-source files in the distribution, provided they are
@@ -4021,13 +4063,13 @@ 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 all the files in the distribution are world-readable, and
+that directories are world-readable and world-searchable (octal mode 755).
+We used to recommend that all directories in the distribution also be
+world-writable (octal mode 777), because ancient versions of @code{tar}
+would otherwise not cope when extracting the archive as an unprivileged
+user. That can easily lead to security issues when creating the archive,
+however, so now we recommend against that.
Don't include any symbolic links in the distribution itself. If the tar
file contains symbolic links, then people cannot even unpack it on
@@ -4180,5 +4222,5 @@ eval: (add-hook 'write-file-hooks 'time-stamp)
time-stamp-start: "@set lastupdate "
time-stamp-end: "$"
time-stamp-format: "%:b %:d, %:y"
-compile-command: "make just-standards"
+compile-command: "cd work.s && make"
End: