Update

[gnulib.git] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index 150202d..75c154c 100644 (file)
--- 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:
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:

-@set lastupdate August 18, 2005
+@set lastupdate February 8, 2006

 @c %**end of header
 
 @dircategory GNU organization
 @c %**end of header
 
 @dircategory GNU organization


@@ -33,7 +33,7 @@
 The GNU coding standards, last updated @value{lastupdate}.
 
 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
 The GNU coding standards, last updated @value{lastupdate}.
 
 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,

-2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+2001, 2002, 2003, 2004, 2005, 2006 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.1
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1


@@ -518,6 +518,8 @@ software.  It also describes general standards for error messages, the
 command line interface, and how libraries should behave.
 
 @menu
 command line interface, and how libraries should behave.
 
 @menu

+* Non-GNU Standards::           We consider standards such as POSIX;
+                                  we don't "obey" them.

 * Semantics::                   Writing robust programs
 * Libraries::                   Library behavior
 * Errors::                      Formatting error messages
 * Semantics::                   Writing robust programs
 * Libraries::                   Library behavior
 * Errors::                      Formatting error messages


@@ -529,6 +531,50 @@ command line interface, and how libraries should behave.
 * File Usage::                  Which files to use, and where
 @end menu
 
 * File Usage::                  Which files to use, and where
 @end menu
 

+@node Non-GNU Standards
+@section Non-GNU Standards
+
+The GNU Project regards standards published by other organizations as
+suggestions, not orders.  We consider those standards, but we do not
+``obey'' them.  In developing a GNU program, you should implement
+an outside standard's specifications when that makes the GNU system
+better overall in an objective sense.  When it doesn't, you shouldn't.
+
+In most cases, following published standards is convenient for
+users---it means that their programs or scripts will work more
+portably.  For instance, GCC implements nearly all the features of
+Standard C as specified by that standard.  C program developers would
+be unhappy if it did not.  And GNU utilities mostly follow
+specifications of POSIX.2; shell script writers and users would be
+unhappy if our programs were incompatible.
+
+But we do not follow either of these specifications rigidly, and there
+are specific points on which we decided not to follow them, so as to
+make the GNU system better for users.
+
+For instance, Standard C says that nearly all extensions to C are
+prohibited.  How silly!  GCC implements many extensions, some of which
+were later adopted as part of the standard.  If you want these
+constructs to give an error message as ``required'' by the standard,
+you must specify @samp{--pedantic}, which was implemented only so that
+we can say ``GCC is a 100% implementation of the standard,'' not
+because there is any reason to actually use it.
+
+POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
+default in units of 512 bytes.  What users want is units of 1k, so
+that is what we do by default.  If you want the ridiculous behavior
+``required'' by POSIX, you must set the environment variable
+@samp{POSIXLY_CORRECT} (which was originally going to be named
+@samp{POSIX_ME_HARDER}).
+
+GNU utilities also depart from the letter of the POSIX.2 specification
+when they support long-named command-line options, and intermixing
+options with ordinary arguments.  This minor incompatibility with
+POSIX is never a problem in practice, and it is very useful.
+
+In particular, don't reject a new feature, or remove an old one,
+merely because a standard says it is ``forbidden'' or ``deprecated.''
+

 @node Semantics
 @section Writing Robust Programs
 
 @node Semantics
 @section Writing Robust Programs
 


@@ -2154,13 +2200,13 @@ when writing GNU software.
 @cindex open brace
 @cindex braces, in C source
 It is important to put the open-brace that starts the body of a C
 @cindex open brace
 @cindex braces, in C source
 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.
+function in column one, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column one.  Several tools look
+for open-braces in column one 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
 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
+function in column one.  This helps people to search for function

 definitions, and may also help certain tools recognize them.  Thus,
 using Standard C syntax, the format is this:
 
 definitions, and may also help certain tools recognize them.  Thus,
 using Standard C syntax, the format is this:
 


@@ -2178,9 +2224,9 @@ this:
 
 @example
 static char *
 
 @example
 static char *

-concat (s1, s2)        /* Name starts in column zero here */
+concat (s1, s2)        /* Name starts in column one here */

      char *s1, *s2;
      char *s1, *s2;

-@{                     /* Open brace in column zero here */
+@{                     /* Open brace in column one here */

   @dots{}
 @}
 @end example
   @dots{}
 @}
 @end example


@@ -2582,7 +2628,7 @@ constants.
 @cindex file-name limitations
 @pindex doschk
 You might want to make sure that none of the file names would conflict
 @cindex file-name limitations
 @pindex doschk
 You might want to make sure that none of the file names would conflict

-the files were loaded onto an MS-DOS file system which shortens the
+if the files were loaded onto an MS-DOS file system which shortens the

 names.  You can use the program @code{doschk} to test for this.
 
 Some GNU programs were designed to limit themselves to file names of 14
 names.  You can use the program @code{doschk} to test for this.
 
 Some GNU programs were designed to limit themselves to file names of 14


@@ -2673,7 +2719,7 @@ printf ("diff = %ld\n", (long) (pointer2 - pointer1));
 @end example
 
 1989 Standard C requires this to work, and we know of only one
 @end example
 
 1989 Standard C requires this to work, and we know of only one

-counterexample: 64-bit programs on Microsoft Windows IA-64.  We will
+counterexample: 64-bit programs on Microsoft Windows.  We will

 leave it to those who want to port GNU programs to that environment
 to figure out how to do it.
 
 leave it to those who want to port GNU programs to that environment
 to figure out how to do it.
 


@@ -3021,13 +3067,13 @@ how it does quoting, if different than the preferred method of @samp{`}
 and @samp{'}.  This is especially important if the output of your
 program is ever likely to be parsed by another program.
 
 and @samp{'}.  This is especially important if the output of your
 program is ever likely to be parsed by another program.
 

-Quotation characters are a difficult area in the computing world at this
-time: there are no true left or right quote characters in ASCII, or even
-Latin1; the @samp{`} character we use was standardized as a grave
+Quotation characters are a difficult area in the computing world at
+this time: there are no true left or right quote characters in Latin1;
+the @samp{`} character we use was standardized there as a grave

 accent.  Moreover, Latin1 is still not universally usable.
 
 Unicode contains the unambiguous quote characters required, and its
 accent.  Moreover, Latin1 is still not universally usable.
 
 Unicode contains the unambiguous quote characters required, and its

-common encoding UTF-8 is upward compatible with ASCII@.  However,
+common encoding UTF-8 is upward compatible with Latin1.  However,

 Unicode and UTF-8 are not universally well-supported, either. 
 
 This may change over the next few years, and then we will revisit
 Unicode and UTF-8 are not universally well-supported, either. 
 
 This may change over the next few years, and then we will revisit


@@ -3862,7 +3908,9 @@ social and ethical problem, and the point of GNU is to solve that
 problem.
 
 The GNU definition of free software is found on the GNU web site at
 problem.
 
 The GNU definition of free software is found on the GNU web site at

-@url{http://www.gnu.org/philosophy/free-sw.html}.  A list of
+@url{http://www.gnu.org/philosophy/free-sw.html}, and the definition
+of free documentation is found at
+@url{http://www.gnu.org/philosophy/free-doc.html}.  A list of

 important licenses and whether they qualify as free is in
 @url{http://www.gnu.org/licenses/license-list.html}.  The terms
 ``free'' and ``non-free'', used in this document, refer to that
 important licenses and whether they qualify as free is in
 @url{http://www.gnu.org/licenses/license-list.html}.  The terms
 ``free'' and ``non-free'', used in this document, refer to that