X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fstandards.texi;h=75c154c94ea2bad3e4d0fb2bc186c83de92381c7;hb=0aee6c1867357efc96226bf37b342ba876e5d0f3;hp=150202da126e6b30b73be856bf524dd50f5a9b64;hpb=92e01d0ea2f65bb0f11a260bcda64b31bcb972fb;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index 150202da1..75c154c94 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 August 18, 2005 +@set lastupdate February 8, 2006 @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, -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 @@ -518,6 +518,8 @@ software. It also describes general standards for error messages, the 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 @@ -529,6 +531,50 @@ command line interface, and how libraries should behave. * 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 @@ -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 -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: @@ -2178,9 +2224,9 @@ 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 @@ -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 -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 @@ -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 -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. @@ -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. -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 @@ -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 -@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