gnustandards standards.texi ChangeLog

[Karl Berry]

CVSROOT:        /sources/gnustandards
Module name:    gnustandards
Changes by:     Karl Berry <karl>       11/12/23 00:30:29

Modified files:
        .              : standards.texi ChangeLog 

Log message:
        (Conditional Changes): more examples in more languages

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnustandards/standards.texi?cvsroot=gnustandards&r1=1.209&r2=1.210
http://cvs.savannah.gnu.org/viewcvs/gnustandards/ChangeLog?cvsroot=gnustandards&r1=1.147&r2=1.148

Patches:
Index: standards.texi
===================================================================
RCS file: /sources/gnustandards/gnustandards/standards.texi,v
retrieving revision 1.209
retrieving revision 1.210
diff -u -b -r1.209 -r1.210
--- standards.texi      10 Dec 2011 16:27:20 -0000      1.209
+++ standards.texi      23 Dec 2011 00:30:29 -0000      1.210
@@ -3,7 +3,7 @@
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
address@hidden lastupdate December 10, 2011
address@hidden lastupdate December 22, 2011
 @c %**end of header
 
 @dircategory GNU organization
@@ -3647,38 +3647,58 @@
 @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.
-
-Our convention for indicating conditional changes is to use 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:
-
address@hidden
-* xterm.c [SOLARIS2]: Include string.h.
address@hidden 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:
+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
address@hidden 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:
+
address@hidden
+* 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.
address@hidden example
+
+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

Index: ChangeLog
===================================================================
RCS file: /sources/gnustandards/gnustandards/ChangeLog,v
retrieving revision 1.147
retrieving revision 1.148
diff -u -b -r1.147 -r1.148
--- ChangeLog   10 Dec 2011 16:27:20 -0000      1.147
+++ ChangeLog   23 Dec 2011 00:30:29 -0000      1.148
@@ -1,3 +1,8 @@
+2011-12-22  Stefano Lattarini  <address@hidden>
+
+       * standards.texi (Conditional Changes): more examples
+       in more languages.
+
 2011-12-10  Karl Berry  <address@hidden>
 
        * standards.texi (Quote Characters): UTF-8 is not compatible