@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
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
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
* 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
@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
-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:
@example
static char *
-concat (s1, s2) /* Name starts in column zero here */
+concat (s1, s2) /* Name starts in column one here */
char *s1, *s2;
-@{ /* Open brace in column zero here */
+@{ /* Open brace in column one here */
@dots{}
@}
@end example
@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
@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.
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
-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
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
projects / gnulib.git / blobdiff