maint: spelling fixes

[gnulib.git] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index b7ec606..06fd9c7 100644 (file)
--- 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:
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:

-@set lastupdate December 4, 2011
+@set lastupdate January 8, 2012

 @c %**end of header
 
 @dircategory GNU organization
 @c %**end of header
 
 @dircategory GNU organization


@@ -27,8 +27,8 @@
 The GNU coding standards, last updated @value{lastupdate}.
 
 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 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
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or


@@ -611,10 +611,9 @@ are silently truncated''.  This is not acceptable in a GNU utility.
 Utilities reading files should not drop NUL characters, or any other
 nonprinting characters @emph{including those with codes above 0177}.
 The only sensible exceptions would be utilities specifically intended
 Utilities reading files should not drop NUL characters, or any other
 nonprinting characters @emph{including those with codes above 0177}.
 The only sensible exceptions would be utilities specifically intended

-for interface to certain types of terminals or printers
-that can't handle those characters.
-Whenever possible, try to make programs work properly with
-sequences of bytes that represent multibyte characters; 
+for interface to certain types of terminals or printers that can't
+handle those characters.  Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters;

 UTF-8 is the most important.
 
 @cindex error messages
 UTF-8 is the most important.
 
 @cindex error messages


@@ -752,26 +751,27 @@ fit any naming convention.
 Error messages from compilers should look like this:
 
 @example
 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
 @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
 
 @noindent
 Line numbers should start from 1 at the beginning of the file, and
 
 @end example
 
 @noindent
 Line numbers should start from 1 at the beginning of the file, and

-column numbers should start from 1 at the beginning of the line.  (Both
-of these conventions are chosen for compatibility.)  Calculate column
-numbers assuming that space and all ASCII printing characters have
-equal width, and assuming tab stops every 8 columns.  For non-ASCII
-characters, Unicode character widths should be used when in a UTF-8
-locale; GNU libc and GNU gnulib provide suitable @code{wcwidth} functions.
+column numbers should start from 1 at the beginning of the line.
+(Both of these conventions are chosen for compatibility.)  Calculate
+column numbers assuming that space and all ASCII printing characters
+have equal width, and assuming tab stops every 8 columns.  For
+non-ASCII characters, Unicode character widths should be used when in
+a UTF-8 locale; GNU libc and GNU gnulib provide suitable
+@code{wcwidth} functions.

 
 The error message can also give both the starting and ending positions
 of the erroneous text.  There are several formats so that you can
 
 The error message can also give both the starting and ending positions
 of the erroneous text.  There are several formats so that you can


@@ -779,22 +779,22 @@ avoid redundant information such as a duplicate line number.
 Here are the possible formats:
 
 @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
 @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
 @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
 @end example
 
 @noindent


@@ -810,7 +810,7 @@ when there is no relevant source file.
 If you want to mention the column number, use this format:
 
 @example
 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
 @end example
 
 In an interactive program (one that is reading commands from a


@@ -2374,7 +2374,7 @@ when writing GNU software.
 * System Functions::            Portability and ``standard'' library functions.
 * Internationalization::        Techniques for internationalization.
 * Character Set::               Use ASCII by default.
 * 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
 
 * Mmap::                        How you can safely use @code{mmap}.
 @end menu
 


@@ -3049,12 +3049,12 @@ Using GNU gettext involves putting a call to the @code{gettext} macro
 around each string that might need translation---like this:
 
 @example
 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
 @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.
 
 Once a program uses gettext, please make a point of writing calls to
 @code{gettext} when you add new strings that call for translation.


@@ -3175,9 +3175,9 @@ accented characters in month names like ``Flor@'eal''.  Also, it is OK
 (but not required) to use non-ASCII characters to represent proper
 names of contributors in change logs (@pxref{Change Logs}).
 
 (but not required) to use non-ASCII characters to represent proper
 names of contributors in change logs (@pxref{Change Logs}).
 

-If you need to use non-ASCII characters, you should normally stick with
-one encoding, certainly within a single file.  UTF-8 is likely to be
-the best choice.
+If you need to use non-ASCII characters, you should normally stick
+with one encoding, certainly within a single file.  UTF-8 is likely to
+be the best choice.

 
 
 @node Quote Characters
 
 
 @node Quote Characters


@@ -3185,35 +3185,50 @@ the best choice.
 @cindex quote characters
 @cindex locale-specific quote characters
 @cindex left quote
 @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
 @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.
+@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.

 
 

-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.
+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.

 
 

-Unicode contains the unambiguous quote characters required, and its
-common encoding UTF-8 is upward compatible with Latin1.  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}.

 
 

-This may change over the next few years, and then we will revisit
-this.
+@clear txicodequoteundirected
+@clear txicodequotebacktick

 
 
 @node Mmap
 
 
 @node Mmap


@@ -3586,7 +3601,7 @@ Break long lists of function names by closing continued lines with
 
 @example
 * keyboard.c (menu_bar_items, tool_bar_items)
 
 @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
 @end example
 
 When you install someone else's changes, put the contributor's name in


@@ -3648,38 +3663,58 @@ make the records of authorship more accurate.
 @cindex conditional changes, and change logs
 @cindex change logs, conditional changes
 
 @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
 
 @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
 
 @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
 
 
 @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
 
 
 @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
 a certain macro is @emph{not} defined:
 
 @example