# HG changeset patch # User Karl Berry # Date 1324691468 28800 # Node ID 7a476ef3b9c8be52d0ab069f2b6d427415af558e # Parent 88f5f782f0aa5e21394fdda7132f0cc1ee5f9465 autoupdate diff --git a/doc/maintain.texi b/doc/maintain.texi --- a/doc/maintain.texi +++ b/doc/maintain.texi @@ -5,7 +5,7 @@ @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 @@ -874,6 +874,10 @@ @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 @@ -2126,6 +2130,17 @@ 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 diff --git a/doc/standards.texi b/doc/standards.texi --- 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 10, 2011 +@set 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: +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 +@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 . +* 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