X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=4b1c03dd27d38c5052d44d52a298e85aa424c63a;hb=08d1a3f5fa8b36aa0f02ede9c0027ea03340a583;hp=4cb5ed3a6c92b677ffe0f7cdea0b721a5fbc342d;hpb=17d8d6d90303fa196a261291a2558d88e9c3766c;p=gnulib.git

diff --git a/doc/standards.texi b/doc/standards.texi
index 4cb5ed3a6..4b1c03dd2 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 February 23, 2008
+@set lastupdate April 12, 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,11 +89,29 @@ 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/}.
 
-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
-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.
+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.
+
+@cindex @code{bug-standards@@gnu.org} email address
+@cindex Savannah repository for gnustandards
+@cindex gnustandards project repository
+Please send corrections or suggestions for this document to
+@email{bug-standards@@gnu.org}.  If you make a suggestion, please
+include a suggested new wording for it, to help us consider the
+suggestion efficiently.  We prefer a context diff to the Texinfo
+source, but if that's difficult for you, you can make a context diff
+for some other version of this document, or propose it in any way that
+makes it clear.  The source repository for this document can be found
+at @url{http://savannah.gnu.org/projects/gnustandards}.
 
 These standards cover the minimum of what is important when writing a
 GNU package.  Likely, the need for additional standards will come up.
@@ -115,6 +129,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
@@ -305,13 +323,17 @@ for a language that is higher level than C.  Often much of the program
 is written in that language, too.  The Emacs editor pioneered this
 technique.
 
-@cindex GUILE
-The standard extensibility interpreter for GNU software is GUILE
+@cindex Guile
+@cindex GNOME and Guile
+The standard extensibility interpreter for GNU software is Guile
 (@uref{http://www.gnu.org/@/software/@/guile/}), which implements the
-language Scheme (an especially clean and simple dialect of Lisp).  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.
+language Scheme (an especially clean and simple dialect of Lisp).
+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.
+
 
 @node Compatibility
 @section Compatibility with Other Implementations
@@ -493,7 +515,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:
 
@@ -522,6 +544,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
@@ -673,7 +696,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
@@ -832,25 +855,32 @@ multi-column format.
 @node Graphical Interfaces
 @section Standards for Graphical Interfaces
 @cindex graphical user interface
+@cindex interface styles
+@cindex user interface styles
 
-@cindex gtk+
+@cindex GTK+
 When you write a program that provides a graphical user interface,
-please make it work with X Windows and the GTK+ toolkit unless the
-functionality specifically requires some alternative (for example,
-``displaying jpeg images while in console mode'').
+please make it work with the X Window System and the GTK+ toolkit
+unless the functionality specifically requires some alternative (for
+example, ``displaying jpeg images while in console mode'').
 
 In addition, please provide a command-line interface to control the
 functionality.  (In many cases, the graphical user interface can be a
 separate program which invokes the command-line program.)  This is
 so that the same jobs can be done from scripts.
 
-@cindex corba
-@cindex gnome
-Please also consider providing a CORBA interface (for use from GNOME), a
-library interface (for use from C), and perhaps a keyboard-driven
-console interface (for use by users from console mode).  Once you are
-doing the work to provide the functionality and the graphical interface,
-these won't be much extra work.
+@cindex CORBA
+@cindex GNOME
+@cindex D-bus
+@cindex keyboard interface
+@cindex library interface
+Please also consider providing a D-bus interface for use from other
+running programs, such as within GNOME.  (GNOME used to use CORBA
+for this, but that is being phased out.)  In addition, consider
+providing a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console
+mode).  Once you are doing the work to provide the functionality and
+the graphical interface, these won't be much extra work.
 
 
 @node Command-Line Interfaces
@@ -1018,10 +1048,7 @@ GNU General Public License, @url{http://www.gnu.org/@/licenses/@/gpl.html}.
 @item LGPL
 GNU Lesser General Public License, @url{http://www.gnu.org/@/licenses/@/lgpl.html}.
 
-@item GPL/Guile
-GNU GPL with the exception for Guile; for example, GPLv3+/Guile means
-the GNU GPL version 3 or later, with the extra exception for Guile.
-
+@item GPL/Ada
 GNU GPL with the exception for Ada.
 
 @item Apache
@@ -1052,12 +1079,12 @@ The non-license that is being in the public domain,
 The license for Python, @url{http://www.python.org/@/2.0.1/@/license.html}.
 
 @item RBSD
-The revised (3-clause) BSD, compatible with the GNU GPL,
+The revised (3-clause) BSD, compatible with the GNU GPL,@*
 @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#5}.
 
 @item X11
 The simple non-copyleft license used for most versions of the X Window
-system, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
+System, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
 
 @item Zlib
 The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}.
@@ -1081,13 +1108,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: <http://www.gnu.org/software/@var{pkg}/>
+General help using GNU software: <http://www.gnu.org/gethelp/>
 @end example
 
+It is ok to mention other appropriate mailing lists and web pages.
+
 
 @node Option Table
 @section Table of Long Options
@@ -1140,10 +1173,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}.
@@ -1265,7 +1298,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
@@ -1312,7 +1345,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}.
@@ -1330,7 +1363,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}.
@@ -1382,9 +1415,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}.
@@ -1496,7 +1528,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}.
@@ -1524,7 +1556,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}.
@@ -1558,13 +1590,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}.
@@ -1605,7 +1637,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}.
@@ -1623,7 +1655,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.
@@ -1638,7 +1670,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}.
@@ -1674,10 +1706,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}.
@@ -1704,7 +1736,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.
@@ -1779,7 +1811,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}.
@@ -1864,10 +1896,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}.
@@ -1888,7 +1920,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
@@ -1914,7 +1946,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}.
@@ -1923,8 +1955,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}.
@@ -2056,7 +2088,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}.
@@ -2126,7 +2158,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}.
@@ -2191,7 +2223,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}.
@@ -2209,6 +2241,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
@@ -3486,7 +3540,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
@@ -3494,22 +3548,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
@@ -3710,15 +3763,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
@@ -3770,15 +3818,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
@@ -3913,7 +3969,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''
@@ -4001,7 +4057,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
@@ -4016,13 +4072,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
@@ -4175,5 +4231,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: