@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate September 9, 2007
+@set lastupdate June 10, 2008
@c %**end of header
@dircategory GNU organization
@direntry
-* Standards: (standards). GNU coding standards.
+* Standards: (standards). GNU coding standards.
@end direntry
@c @setchapternewpage odd
@c This is used by a cross ref in make-stds.texi
@set CODESTD 1
-@iftex
-@set CHAPTER chapter
-@end iftex
-@ifinfo
-@set CHAPTER node
-@end ifinfo
@copying
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 Free Software
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
is written in that language, too. The Emacs editor pioneered this
technique.
-@cindex 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.
+@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).
+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
@table @asis
@item GPL
-GNU General Public License, @url{http://www.gnu.org/licenses/gpl.html}.
+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}.
+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
The Apache Software Foundation license,
-@url{http://www.apache.org/licenses}.
+@url{http://www.apache.org/@/licenses}.
@item Artistic
-The Artistic license used for Perl, @url{http://www.perlfoundation.org/legal}.
+The Artistic license used for Perl, @url{http://www.perlfoundation.org/@/legal}.
@item Expat
-The Expat license, @url{http://www.jclark.com/xml/copying.txt}.
+The Expat license, @url{http://www.jclark.com/@/xml/@/copying.txt}.
@item MPL
-The Mozilla Public License, @url{http://www.mozilla.org/MPL/}.
+The Mozilla Public License, @url{http://www.mozilla.org/@/MPL/}.
@item OBSD
The original (4-clause) BSD license, incompatible with the GNU GPL
-@url{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6}.
+@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#6}.
@item PHP
-The license used for PHP, @url{http://www.php.net/license/}.
+The license used for PHP, @url{http://www.php.net/@/license/}.
@item public domain
The non-license that is being in the public domain,
-@url{http://www.gnu.org/licenses/license-list.html#PublicDomain}.
+@url{http://www.gnu.org/@/licenses/@/license-list.html#PublicDomain}.
@item Python
-The license for Python, @url{http://www.python.org/2.0.1/license.html}.
+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,
-@url{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5}.
+@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}.
+The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}.
@end table
More information about these licenses and many more are on the GNU
licensing web pages,
-@url{http://www.gnu.org/licenses/license-list.html}.
+@url{http://www.gnu.org/@/licenses/@/license-list.html}.
@node --help
@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}.
@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
@samp{-X} in @code{strip}.
@item dry-run
-@samp{-n} in Make.
+@samp{-n} in @code{make}.
@item ed
@samp{-e} in @code{diff}.
@samp{-N} in @code{diff}.
@item environment-overrides
-@samp{-e} in Make.
+@samp{-e} in @code{make}.
@item eof
@samp{-e} in @code{xargs}.
@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}.
@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}.
@samp{-I} in @code{m4}.
@item include-dir
-@samp{-I} in Make.
+@samp{-I} in @code{make}.
@item incremental
@samp{-G} in @code{tar}.
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}.
@samp{-N} in @code{ls}.
@item load-average
-@samp{-l} in Make.
+@samp{-l} in @code{make}.
@item login
Used in @code{su}.
@samp{-d} in @code{cpio}.
@item makefile
-@samp{-f} in Make.
+@samp{-f} in @code{make}.
@item mapped
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}.
@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}.
@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.
@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}.
@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}.
@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
Used in GDB.
@item recon
-@samp{-n} in Make.
+@samp{-n} in @code{make}.
@item record-number
@samp{-R} in @code{tar}.
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}.
@samp{-S} in @code{shar}.
@item stop
-@samp{-S} in Make.
+@samp{-S} in @code{make}.
@item strict
@samp{-s} in @code{recode}.
@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}.
@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}.
hacker terminology, calling something a ``win'' is a form of praise.
You're free to praise Microsoft Windows on your own if you want, but
please don't do this in GNU packages. Instead of abbreviating
-``Windows'' to ``un'', you can write it in full or abbreviate it to
+``Windows'' to ``win'', you can write it in full or abbreviate it to
``woe'' or ``w''. In GNU Emacs, for instance, we use @samp{w32} in
file names of Windows-specific files, but the macro for Windows
conditionals is called @code{WINDOWSNT}.
A simple way to use the Gnulib error module is to obtain the two
source files @file{error.c} and @file{error.h} from the Gnulib library
source code repository at
-@uref{http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/}.
+@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=gnulib.git}.
Here's a sample use:
@example
possible, @code{configure} can add to the Makefile a variable named
@code{srcdir} whose value is precisely the specified directory.
+In addition, the @samp{configure} script should take options
+corresponding to most of the standard directory variables
+(@pxref{Directory Variables}). Here is the list:
+
+@example
+--prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
+--sharedstatedir --localstatedir --libdir --includedir --oldincludedir
+--datarootdir --datadir --infodir --localedir --mandir --docdir
+--htmldir --dvidir --pdfdir --psdir
+@end example
+
The @code{configure} script should also take an argument which specifies the
type of system to build the program for. This argument should look like
this:
alternatives for how to describe a machine. Thus,
@samp{athlon-pc-gnu/linux} would be a valid alias. There is a shell
script called
-@uref{http://savannah.gnu.org/@/cgi-bin/@/viewcvs/@/*checkout*/@/config/@/config/@/config.sub,
+@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD,
@file{config.sub}} that you can use as a subroutine to validate system
types and canonicalize aliases.
i686-pc-linux-gnu}. When the build type is not specified by an option
or argument, the @code{configure} script should normally guess it using
the shell script
-@uref{http://savannah.gnu.org/@/cgi-bin/@/viewcvs/@/*checkout*/@/config/@/config/@/config.guess,
+@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD,
@file{config.guess}}.
@cindex optional features, configure-time
@chapter References to Non-Free Software and Documentation
@cindex references to non-free material
-A GNU program should not recommend use of any non-free program. We
+A GNU program should not recommend, promote, or grant legitimacy to
+the use of any non-free program. Proprietary software is a social and
+ethical problem, and our aim is to put an end to that problem. We
can't stop some people from writing proprietary programs, or stop
other people from using them, but we can and should refuse to
-advertise them to new potential customers. Proprietary software is a
-social and ethical problem, and the point of GNU is to solve that
-problem.
+advertise them to new potential customers, or to give the public the
+idea that their existence is ethical.
The GNU definition of free software is found on the GNU web site at
-@url{http://www.gnu.org/philosophy/free-sw.html}, and the definition
+@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
-definition. If it is not clear whether a license qualifies as free
-under this definition, please ask the GNU Project by writing to
-@email{licensing@@gnu.org}. We will answer, and if the license is an
-important one, we will add it to the list.
+@url{http://www.gnu.org/@/philosophy/@/free-doc.html}. The terms ``free''
+and ``non-free'', used in this document, refer to those definitions.
+
+A list of important licenses and whether they qualify as free is in
+@url{http://www.gnu.org/@/licenses/@/license-list.html}. If it is not
+clear whether a license qualifies as free, please ask the GNU Project
+by writing to @email{licensing@@gnu.org}. We will answer, and if the
+license is an important one, we will add it to the list.
When a non-free program or system is well known, you can mention it in
passing---that is harmless, since users who might want to use it
thing. The goal should be that people already using the proprietary
program will get the advice they need about how to use your free
program with it, while people who don't already use the proprietary
-program will not see anything to lead them to take an interest in it.
+program will not see anything likely to lead them to take an interest
+in it.
If a non-free program or system is obscure in your program's domain,
your program should not mention or support it at all, since doing so
would tend to popularize the non-free program more than it popularizes
-your program. (You cannot hope to find many additional users among
-the users of Foobar if the users of Foobar are few.)
+your program. (You cannot hope to find many additional users for your
+program among the users of Foobar, if the existence of Foobar is not
+generally known among people who might want to use your program.)
Sometimes a program is free software in itself but depends on a
non-free platform in order to run. For instance, many Java programs
-depend on the parts of Sun's Java implementation which are not yet
-free software, and won't run on the GNU Java Compiler (which does not
-yet have all the features) or won't run with the GNU Java libraries.
-We hope this particular problem will be gone in a few months, when Sun
-makes the standard Java libraries free software, but of course the
-general principle remains: you should not recommend programs that
-depend on non-free software to run.
-
-Some free programs encourage the use of non-free software. A typical
-example is @command{mplayer}. It is free software in itself, and the
-free code can handle some kinds of files. However, @command{mplayer}
-recommends use of non-free codecs for other kinds of files, and users
-that install @command{mplayer} are very likely to install those codecs
-along with it. To recommend @command{mplayer} is, in effect, to
-recommend the non-free codecs. We must not do that, so we cannot
-recommend @command{mplayer} either.
-
-In general, you should also not recommend programs that themselves
-strongly recommend the use of non-free software.
+depend on some non-free Java libraries. To recommend or promote such
+a program is to promote the other programs it needs. This is why we
+are careful about listing Java programs in the Free Software
+Directory: we don't want to promote the non-free Java libraries.
+
+We hope this particular problem with Java will be gone by and by, as
+we replace the remaining non-free standard Java libraries with free
+software, but the general principle will remain the same: don't
+recommend, promote or legitimize programs that depend on non-free
+software to run.
+
+Some free programs strongly encourage the use of non-free software. A
+typical example is @command{mplayer}. It is free software in itself,
+and the free code can handle some kinds of files. However,
+@command{mplayer} recommends use of non-free codecs for other kinds of
+files, and users that install @command{mplayer} are very likely to
+install those codecs along with it. To recommend @command{mplayer}
+is, in effect, to promote use of the non-free codecs.
+
+Thus, you should not recommend programs that strongly encourage the
+use of non-free software. This is why we do not list
+@command{mplayer} in the Free Software Directory.
A GNU package should not refer the user to any non-free documentation
for free software. Free documentation that can be included in free
operating systems is essential for completing the GNU system, or any
-free operating system, so it is a major focus of the GNU Project; to
-recommend use of documentation that we are not allowed to use in GNU
-would weaken the impetus for the community to produce documentation
-that we can include. So GNU packages should never recommend non-free
+free operating system, so encouraging it is a priority; to recommend
+use of documentation that we are not allowed to include undermines the
+impetus for the community to produce documentation that we can
+include. So GNU packages should never recommend non-free
documentation.
By contrast, it is ok to refer to journal articles and textbooks in
the comments of a program for explanation of how it functions, even
-though they be non-free. This is because we don't include such things
-in the GNU system even if we are allowed to---they are outside the
-scope of an operating system project.
+though they are non-free. This is because we don't include such
+things in the GNU system even they are free---they are outside the
+scope of what a software distribution needs to include.
Referring to a web site that describes or recommends a non-free
-program is in effect promoting that software, so please do not make
-links (or mention by name) web sites that contain such material. This
-policy is relevant particularly for the web pages for a GNU package.
-
-Following links from nearly any web site can lead to non-free
-software; this is an inescapable aspect of the nature of the web, and
-in itself is no objection to linking to a site. As long as the site
-does not itself recommend a non-free program, there is no need to be
-concerned about the sites it links to for other reasons.
-
-Thus, for example, you should not make a link to AT&T's web site,
-because that recommends AT&T's non-free software packages; you should
-not make a link to a site that links to AT&T's site saying it is a
-place to get a non-free program; but if a site you want to link to
-refers to AT&T's web site in some other context (such as long-distance
-telephone service), that is not a problem.
-
+program is promoting that program, so please do not make links (or
+mention by name) web sites that contain such material. This policy is
+relevant particularly for the web pages for a GNU package.
+
+Following links from nearly any web site can lead eventually to
+non-free software; this is inherent in the nature of the web. So it
+makes no sense to criticize a site for having such links. As long as
+the site does not itself recommend a non-free program, there is no
+need to consider the question of the sites that it links to for other
+reasons.
+
+Thus, for example, you should not refer to AT&T's web site if that
+recommends AT&T's non-free software packages; you should not refer to
+a site that links to AT&T's site presenting it as a place to get some
+non-free program, because that link recommends and legitimizes the
+non-free program. However, that a site contains a link to AT&T's web
+site for some other purpose (such as long-distance telephone service)
+is not an objection against it.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
projects / gnulib.git / blobdiff