X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=73885d6670b58683d2f71834e15ed7d65392fb78;hb=a155c5688ab059c1c2fff7f132116b455ddb37ba;hp=cbf2f842868ef0a0614bd614431cf16a94c29225;hpb=685e635cfdf3f40e507877d11fb5ffad45746ad3;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index cbf2f8428..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 December 11, 2009 +@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, 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 @@ -101,11 +101,17 @@ interface at @url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}. Archives are also available there. -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. +@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. @@ -509,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: @@ -690,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 @@ -849,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 @@ -1035,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. @@ -1070,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}. @@ -3531,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 @@ -3539,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 @@ -4183,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