@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate December 2, 2011
+@set lastupdate December 23, 2011
@c %**end of header
@dircategory GNU organization
@url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
how to use the GNU FDL.
+If you write a manual that people might want to buy on paper, please
+write to @email{maintainers@@gnu.org} to tell the FSF about it. We
+might want to publish it.
+
If the manual is over 400 pages, or if the FSF thinks it might be a
good choice for publishing on paper, then please include the GNU GPL,
as in the notice above. Please also include our standard invariant
terminology and its reasons, you can refer to the URL
@url{http://www.gnu.org/gnu/linux-and-gnu.html}.
+To make it clear that Linux is a kernel, not an operating system,
+please take care to avoid using the term ``Linux system'' in those
+materials. If you want to have occasion to make a statement about
+systems in which the kernel is Linux, write ``systems in which the
+kernel is Linux'' or ``systems with Linux as the kernel.'' That
+explicitly contrasts the system and the kernel, and will help readers
+understand the difference between the two. Please avoid simplified
+forms such as ``Linux-based systems'' because those fail to highlight
+the difference between the kernel and the system, and could encourage
+readers to overlook the distinction.
+
To contrast the GNU system properly with respect to GNU/Linux, you can
call it ``GNU/Hurd'' or ``the GNU/Hurd system''. However, when that
contrast is not specifically the focus, please call it just ``GNU'' or
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate December 10, 2011
+@set lastupdate December 22, 2011
@c %**end of header
@dircategory GNU organization
@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.
-Our convention for indicating conditional changes is to use square
-brackets around the name of the condition.
+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.
-Here is a simple example, describing a change which is conditional but
-does not have a function or entity name associated with it:
+Our convention for indicating conditional changes is to use
+@emph{square brackets around the name of the condition}.
+
+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