@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
+<<<<<<< HEAD
@set lastupdate December 10, 2011
+=======
+@set lastupdate March 8, 2012
+>>>>>>> snapshot-start
@c %**end of header
@dircategory GNU organization
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, 2010, 2011
-Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+2011, 2012 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.3 or
Error messages from compilers should look like this:
@example
-@var{source-file-name}:@var{lineno}: @var{message}
+@var{sourcefile}:@var{lineno}: @var{message}
@end example
@noindent
If you want to mention the column number, use one of these formats:
@example
-@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
-@var{source-file-name}:@var{lineno}.@var{column}: @var{message}
+@var{sourcefile}:@var{lineno}:@var{column}: @var{message}
+@var{sourcefile}:@var{lineno}.@var{column}: @var{message}
@end example
Here are the possible formats:
@example
-@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
-@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
-@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
+@var{sourcefile}:@var{line1}.@var{column1}-@var{line2}.@var{column2}: @var{message}
+@var{sourcefile}:@var{line1}.@var{column1}-@var{column2}: @var{message}
+@var{sourcefile}:@var{line1}-@var{line2}: @var{message}
@end example
@noindent
When an error is spread over several files, you can use this format:
@example
-@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
+@var{file1}:@var{line1}.@var{column1}-@var{file2}:@var{line2}.@var{column2}: @var{message}
@end example
Error messages from other noninteractive programs should look like this:
@example
-@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@var{program}:@var{sourcefile}:@var{lineno}: @var{message}
@end example
@noindent
If you want to mention the column number, use this format:
@example
-@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@var{program}:@var{sourcefile}:@var{lineno}:@var{column}: @var{message}
@end example
In an interactive program (one that is reading commands from a
each on a separate line.
Next should follow a line stating the license, preferably using one of
-abbrevations below, and a brief statement that the program is free
+abbreviations below, and a brief statement that the program is free
software, and that users are free to copy and change it. Also mention
that there is no warranty, to the extent permitted by law. See
recommended wording below.
* System Functions:: Portability and ``standard'' library functions.
* Internationalization:: Techniques for internationalization.
* Character Set:: Use ASCII by default.
-* Quote Characters:: Use `...' in the C locale.
+* Quote Characters:: Use "..." or '...' in the C locale.
* Mmap:: How you can safely use @code{mmap}.
@end menu
as @command{lint}, @command{clang}, and GCC with extra warnings
options such as @option{-Wconversion} and @option{-Wundef}. These
tools can help find bugs and unclear code, but they can also generate
-so many false alarms that that it hurts readability to silence them
-with unnecessary casts, wrappers, and other complications. For
-example, please don't insert casts to @code{void} or calls to
-do-nothing functions merely to pacify a lint checker.
+so many false alarms that it hurts readability to silence them with
+unnecessary casts, wrappers, and other complications. For example,
+please don't insert casts to @code{void} or calls to do-nothing
+functions merely to pacify a lint checker.
Declarations of external functions and functions to appear later in the
source file should all go in one place near the beginning of the file
around each string that might need translation---like this:
@example
-printf (gettext ("Processing file `%s'..."));
+printf (gettext ("Processing file '%s'..."), file);
@end example
@noindent
This permits GNU gettext to replace the string @code{"Processing file
-`%s'..."} with a translated version.
+'%s'..."} with a translated version.
Once a program uses gettext, please make a point of writing calls to
@code{gettext} when you add new strings that call for translation.
@cindex quote characters
@cindex locale-specific quote characters
@cindex left quote
+@cindex right quote
+@cindex opening quote
+@cindex single quote
+@cindex double quote
@cindex grave accent
+@set txicodequoteundirected
+@set txicodequotebacktick
-In the C locale, GNU programs should stick to plain ASCII for quotation
-characters in messages to users: preferably 0x60 (@samp{`}) for left
-quotes and 0x27 (@samp{'}) for right quotes. It is ok, but not
-required, to use locale-specific quotes in other locales.
+In the C locale, the output of GNU programs should stick to plain
+ASCII for quotation characters in messages to users: preferably 0x22
+(@samp{"}) or 0x27 (@samp{'}) for both opening and closing quotes.
+Although GNU programs traditionally used 0x60 (@samp{`}) for opening
+and 0x27 (@samp{'}) for closing quotes, nowadays quotes @samp{`like
+this'} are typically rendered asymmetrically, so quoting @samp{"like
+this"} or @samp{'like this'} typically looks better.
-The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
-@code{quotearg} modules provide a reasonably straightforward way to
-support locale-specific quote characters, as well as taking care of
-other issues, such as quoting a filename that itself contains a quote
-character. See the Gnulib documentation for usage details.
+It is ok, but not required, for GNU programs to generate
+locale-specific quotes in non-C locales. For example:
-In any case, the documentation for your program should clearly specify
-how it does quoting, if different than the preferred method of @samp{`}
-and @samp{'}. This is especially important if the output of your
-program is ever likely to be parsed by another program.
-
-Quotation characters are a difficult area in the computing world at
-this time: there are no true left or right quote characters in Latin1;
-the @samp{`} character we use was standardized there as a grave
-accent. Moreover, Latin1 is still not universally usable.
+@example
+printf (gettext ("Processing file '%s'..."), file);
+@end example
+@noindent
+Here, a French translation might cause @code{gettext} to return the
+string @code{"Traitement de fichier
+@guilsinglleft{}@tie{}%s@tie{}@guilsinglright{}..."}, yielding quotes
+more appropriate for a French locale.
+
+Sometimes a program may need to use opening and closing quotes
+directly. By convention, @code{gettext} translates the string
+@samp{"`"} to the opening quote and the string @samp{"'"} to the
+closing quote, and a program can use these translations. Generally,
+though, it is better to translate quote characters in the context of
+longer strings.
+
+<<<<<<< HEAD
Unicode contains the unambiguous quote characters required. However,
Unicode and UTF-8 are not universally well-supported, either.
+=======
+If the output of your program is ever likely to be parsed by another
+program, it is good to provide an option that makes this parsing
+reliable. For example, you could escape special characters using
+conventions from the C language or the Bourne shell. See for example
+the option @option{--quoting-style} of GNU @code{ls}.
+>>>>>>> snapshot-start
-This may change over the next few years, and then we will revisit
-this.
+@clear txicodequoteundirected
+@clear txicodequotebacktick
@node Mmap
@example
* keyboard.c (menu_bar_items, tool_bar_items)
-(Fexecute_extended_command): Deal with `keymap' property.
+(Fexecute_extended_command): Deal with 'keymap' property.
@end example
When you install someone else's changes, put the contributor's name in
@cindex conditional changes, and change logs
@cindex change logs, conditional changes
-C programs often contain compile-time @code{#if} conditionals. Many
-changes are conditional; sometimes you add a new definition which is
-entirely contained in a conditional. It is very useful to indicate in
-the change log the conditions for which the change applies.
+Source files can often contain code that is conditional to build-time
+or static conditions. For example, C programs can contain
+compile-time @code{#if} conditionals; programs implemented in
+interpreted languages can contain module imports of function
+definitions that are only performed for certain versions of the
+interpreter; and Automake @file{Makefile.am} files can contain
+variable definitions or target declarations that are only to be
+considered if a configure-time Automake conditional is true.
+
+Many changes are conditional as well: sometimes you add a new variable,
+or function, or even a new program or library, which is entirely
+dependent on a build-time condition. It is useful to indicate
+in the change log the conditions for which a change applies.
-Our convention for indicating conditional changes is to use square
-brackets around the name of the condition.
+Our convention for indicating conditional changes is to use
+@emph{square brackets around the name of the condition}.
-Here is a simple example, describing a change which is conditional but
-does not have a function or entity name associated with it:
+Conditional changes can happen in numerous scenarios and with many
+variations, so here are some examples to help clarify. This first
+example describes changes in C, Perl, and Python files which are
+conditional but do not have an associated function or entity name:
@example
-* xterm.c [SOLARIS2]: Include string.h.
+* xterm.c [SOLARIS2]: Include <string.h>.
+* FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module.
+* framework.py [sys.version_info < (2, 6)]: Make "with" statement
+ available by importing it from __future__,
+ to support also python 2.5.
@end example
-Here is an entry describing a new definition which is entirely
-conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
-used only when @code{HAVE_X_WINDOWS} is defined:
+Our other examples will for simplicity be limited to C, as the minor
+changes necessary to adapt them to other languages should be
+self-evident.
+
+Next, here is an entry describing a new definition which is entirely
+conditional: the C macro @code{FRAME_WINDOW_P} is defined (and used)
+only when the macro @code{HAVE_X_WINDOWS} is defined:
@example
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
@end example
-Here is an entry for a change within the function @code{init_display},
-whose definition as a whole is unconditional, but the changes themselves
-are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+Next, an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes
+themselves are contained in a @samp{#ifdef HAVE_LIBNCURSES}
+conditional:
@example
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
@end example
-Here is an entry for a change that takes affect only when
+Finally, here is an entry for a change that takes effect only when
a certain macro is @emph{not} defined:
@example
projects / gnulib.git / blobdiff