*printf-posix: Put more info into config.log.

[gnulib.git] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index 7246c7b..60a0ea2 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:
-@set lastupdate December 31, 2011
+@set lastupdate June 1, 2012
 @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,
-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
@@ -751,15 +751,15 @@ fit any naming convention.
 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
 
@@ -779,22 +779,22 @@ avoid redundant information such as a duplicate line number.
 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
@@ -810,7 +810,7 @@ when there is no relevant source file.
 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
@@ -998,7 +998,7 @@ copyright notice.  If more than one copyright notice is called for, put
 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.
@@ -2384,6 +2384,7 @@ when writing GNU software.
 
 @cindex open brace
 @cindex braces, in C source
+@cindex function definitions, formatting
 It is important to put the open-brace that starts the body of a C
 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
@@ -2430,6 +2431,20 @@ lots_of_args (int an_integer, long a_long, short a_short,
 @dots{}
 @end example
 
+@cindex @code{struct} types, formatting
+@cindex @code{enum} types, formatting
+For @code{struct} and @code{enum} types, likewise put the braces in
+column one, unless the whole contents fits on one line:
+
+@example
+struct foo
+@{
+  int a, b;
+@}
+@exdent @r{or}
+struct foo @{ int a, b; @}
+@end example
+
 The rest of this section gives our recommendations for other aspects of
 C formatting style, which is also the default style of the @code{indent}
 program in version 1.2 and newer.  It corresponds to the options
@@ -2576,7 +2591,7 @@ about the value rather than the variable itself.  Thus, ``the inode
 number NODE_NUM'' rather than ``an inode''.
 
 There is usually no purpose in restating the name of the function in
-the comment before it, because the reader can see that for himself.
+the comment before it, because readers can see that for themselves.
 There might be an exception when the comment is so long that the function
 itself would be off the bottom of the screen.
 
@@ -2655,10 +2670,10 @@ Don't make the program ugly just to placate static analysis tools such
 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
@@ -3516,11 +3531,16 @@ history of how the conflicting concepts arose and who they came from.
 @node Change Log Concepts
 @subsection Change Log Concepts
 
+@cindex change set
+@cindex batch of changes
 You can think of the change log as a conceptual ``undo list'' which
 explains how earlier versions were different from the current version.
-People can see the current version; they don't need the change log
-to tell them what is in it.  What they want from a change log is a
-clear explanation of how the earlier version differed.
+People can see the current version; they don't need the change log to
+tell them what is in it.  What they want from a change log is a clear
+explanation of how the earlier version differed.  Each @dfn{entry} in
+a change log describes either an individual change or the smallest
+batch of changes that belong together, also known as a @dfn{change
+set}.
 
 The change log file is normally called @file{ChangeLog} and covers an
 entire directory.  Each directory can have its own change log, or a
@@ -3534,7 +3554,7 @@ to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
 
 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
+to describe the overall purpose of a change log entry.  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
@@ -3543,15 +3563,17 @@ 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.
+files (manuals, help files, media 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.
 
 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
-of the changed functions, variables or whatever, followed by a colon.
-Then describe the changes you made to that function or variable.
+command @kbd{M-x add-change-log-entry}.  An individual change should
+have an asterisk, the name of the changed file, and then in
+parentheses the name of the changed functions, variables or whatever,
+followed by a colon.  Then describe the changes you made to that
+function or variable.
+
 
 @node Style of Change Logs
 @subsection Style of Change Logs
@@ -3590,10 +3612,10 @@ names by writing @samp{* register.el (@{insert,jump-to@}-register)};
 this is not a good idea, since searching for @code{jump-to-register} or
 @code{insert-register} would not find that entry.
 
-Separate unrelated change log entries with blank lines.  When two
-entries represent parts of the same change, so that they work together,
-then don't put blank lines between them.  Then you can omit the file
-name and the asterisk when successive entries are in the same file.
+Separate unrelated change log entries with blank lines.  Don't put
+blank lines between individual changes of an entry.  You can omit the
+file name and the asterisk when successive individual changes are in
+the same file.
 
 Break long lists of function names by closing continued lines with
 @samp{)}, rather than @samp{,}, and opening the continuation with
@@ -3718,9 +3740,10 @@ Finally, here is an entry for a change that takes effect only when
 a certain macro is @emph{not} defined:
 
 @example
-(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+* host.c (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
 @end example
 
+
 @node Indicating the Part Changed
 @subsection Indicating the Part Changed