X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=f24942ac3e719993e888af53643177dcf4c64666;hb=4f01268d0c584c20704e42527f4fa125e7525aae;hp=088f2fabbccc64e29631422bc5807c920695cd94;hpb=31d3154399f8c679ba23afb0f6bef03b73d4c741;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index 088f2fabb..f24942ac3 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 June 7, 2009 +@set lastupdate March 25, 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, 2009 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 @@ -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 @@ -839,9 +858,9 @@ multi-column format. @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 @@ -1022,10 +1041,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. @@ -1062,7 +1077,7 @@ The revised (3-clause) BSD, compatible with the GNU GPL, @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}. @@ -3518,7 +3533,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 @@ -3526,22 +3541,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 @@ -3948,7 +3962,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'' @@ -4051,13 +4065,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 @@ -4210,5 +4224,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: