X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=73885d6670b58683d2f71834e15ed7d65392fb78;hb=c47e73f47733362996652ecbb683347920a183b6;hp=bd90a92df8f1faa8311e4a491d1653f1c74513d6;hpb=2643a6d0df895ff969e2d8a0689e0f862834a756;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index bd90a92df..73885d667 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 November 6, 2008 +@set lastupdate June 21, 2010 @c %**end of header @dircategory GNU organization @@ -27,7 +27,7 @@ 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 @@ -81,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 @@ -92,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. @@ -114,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 @@ -313,7 +332,7 @@ 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. +system. @node Compatibility @@ -496,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: @@ -677,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 @@ -836,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 @@ -1022,10 +1048,6 @@ 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. @@ -1057,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}. @@ -1086,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: +General help using GNU software: @end example +It is ok to mention other appropriate mailing lists and web pages. + @node Option Table @section Table of Long Options @@ -3512,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 @@ -3520,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 @@ -3736,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 @@ -3947,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'' @@ -4035,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 @@ -4050,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 @@ -4169,7 +4191,7 @@ 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 are non-free. This is because we don't include such -things in the GNU system even they are free---they are outside the +things in the GNU system even if 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 @@ -4209,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: