X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=55b6d1913777f56ca63da5a3bc8669121e76d2bc;hb=ac19f2d70a9379c512a24dc87c9ade4a239b4d6b;hp=c45ce991f41bd34196580b148c368c015440cdfa;hpb=30d9edd0c165fed3fdc2f260d2a0d3b8cba15123;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index c45ce991f..55b6d1913 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 17, 2006 +@set lastupdate January 22, 2007 @c %**end of header @dircategory GNU organization @@ -32,8 +32,9 @@ @copying The GNU coding standards, last updated @value{lastupdate}. -Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, -2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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.2 @@ -149,7 +150,7 @@ irrelevant and dissimilar to your results. For example, Unix utilities were generally optimized to minimize memory use; if you go for speed instead, your program will be very -different. You could keep the entire input file in core and scan it +different. You could keep the entire input file in memory and scan it there instead of using stdio. Use a smarter algorithm discovered more recently than the Unix program. Eliminate use of temporary files. Do it in one pass instead of two (we did this in the assembler). @@ -2144,7 +2145,7 @@ Print the version number. If a program typically uses just a few meg of memory, don't bother making any effort to reduce memory usage. For example, if it is impractical for other reasons to operate on files more than a few meg long, it is -reasonable to read entire input files into core to operate on them. +reasonable to read entire input files into memory to operate on them. However, for programs such as @code{cat} or @code{tail}, that can usefully operate on very large files, it is important to avoid using a @@ -2152,10 +2153,10 @@ technique that would artificially limit the size of files it can handle. If a program works by lines and could be applied to arbitrary user-supplied input files, it should keep only a line in memory, because this is not very hard and users will want to be able to operate on input -files that are bigger than will fit in core all at once. +files that are bigger than will fit in memory all at once. If your program creates complicated data structures, just make them in -core and give a fatal error if @code{malloc} returns zero. +memory and give a fatal error if @code{malloc} returns zero. @node File Usage @section File Usage @@ -2201,10 +2202,14 @@ 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 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. +function in column one, so that they will start a defun. 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. + +Avoid putting open-brace, open-parenthesis or open-bracket in column +one when they are inside a function, so that they won't start a defun. +The open-brace that starts a @code{struct} body can go in column one +if you find it useful to treat that definition as a defun. It is also important for function definitions to start the name of the function in column one. This helps people to search for function @@ -2563,8 +2568,9 @@ Don't declare both a structure tag and variables or typedefs in the same declaration. Instead, declare the structure tag separately and then use it to declare the variables or typedefs. -Try to avoid assignments inside @code{if}-conditions. For example, -don't write this: +Try to avoid assignments inside @code{if}-conditions (assignments +inside @code{while}-conditions are ok). For example, don't write +this: @example if ((foo = (char *) malloc (sizeof *foo)) == 0) @@ -2736,8 +2742,21 @@ machines. Thus, don't make the following mistake: @example int c; @dots{} -while ((c = getchar()) != EOF) - write(file_descriptor, &c, 1); +while ((c = getchar ()) != EOF) + write (file_descriptor, &c, 1); +@end example + +@noindent Instead, use @code{unsigned char} as follows. (The @code{unsigned} +is for portability to unusual systems where @code{char} is signed and +where there is integer overflow checking.) + +@example +int c; +while ((c = getchar ()) != EOF) + @{ + unsigned char u = c; + write (file_descriptor, &u, 1); + @} @end example It used to be ok to not worry about the difference between pointers @@ -2964,16 +2983,16 @@ sentence framework. Here is an example of what not to do: -@example +@smallexample printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk"); -@end example +@end smallexample If you apply gettext to all strings, like this, -@example +@smallexample printf (gettext ("%s is full"), capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk")); -@end example +@end smallexample @noindent the translator will hardly know that "disk" and "floppy disk" are meant to @@ -3761,8 +3780,8 @@ the shell script @cindex optional features, configure-time Other options are permitted to specify in more detail the software -or hardware present on the machine, and include or exclude optional -parts of the package: +or hardware present on the machine, to include or exclude optional parts +of the package, or to adjust the name of some tools or arguments to them: @table @samp @item --enable-@var{feature}@r{[}=@var{parameter}@r{]} @@ -3795,14 +3814,32 @@ and Do not use a @samp{--with} option to specify the file name to use to find certain files. That is outside the scope of what @samp{--with} options are for. + +@item @var{variable}=@var{value} +Set the value of the variable @var{variable} to @var{value}. This is +used to override the default values of commands or arguments in the +build process. For example, the user could issue @samp{configure +CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without +the default optimization. + +Specifying variables as arguments to @code{configure}, like this: +@example +./configure CC=gcc +@end example +is preferable to setting them in environment variables: +@example +CC=gcc ./configure +@end example +as it helps to recreate the same configuration later with +@file{config.status}. @end table -All @code{configure} scripts should accept all of these ``detail'' -options, whether or not they make any difference to the particular -package at hand. In particular, they should accept any option that -starts with @samp{--with-} or @samp{--enable-}. This is so users will -be able to configure an entire GNU source tree at once with a single set -of options. +All @code{configure} scripts should accept all of the ``detail'' +options and the variable settings, whether or not they make any +difference to the particular package at hand. In particular, they +should accept any option that starts with @samp{--with-} or +@samp{--enable-}. This is so users will be able to configure an +entire GNU source tree at once with a single set of options. You will note that the categories @samp{--with-} and @samp{--enable-} are narrow: they @strong{do not} provide a place for any sort of option @@ -3978,11 +4015,25 @@ the users of Foobar if the users of Foobar are few.) 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 Sun's Java implementation, 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. To recommend that program is inherently to -recommend the non-free platform as well; if you should not do the -latter, then don't do the former. +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. A GNU package should not refer the user to any non-free documentation for free software. Free documentation that can be included in free @@ -3996,7 +4047,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 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 +in the GNU system even if we are allowed to---they are outside the scope of an operating system project. Referring to a web site that describes or recommends a non-free