extern-inline: avoid compilation error with HP-UX cc

[gnulib.git] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index fc92652..fec548b 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 June 30, 2012
+@set lastupdate February 13, 2013

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


@@ -28,7 +28,7 @@ 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,
 
 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,

-2011, 2012 Free Software Foundation, Inc.
+2011, 2012, 2013 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


@@ -339,20 +339,21 @@ system.
 
 @node Compatibility
 @section Compatibility with Other Implementations
 
 @node Compatibility
 @section Compatibility with Other Implementations

-@cindex compatibility with C and @sc{posix} standards
-@cindex @sc{posix} compatibility
+@cindex compatibility with C and POSIX standards
+@cindex C compatibility
+@cindex POSIX compatibility

 
 With occasional exceptions, utility programs and libraries for GNU
 should be upward compatible with those in Berkeley Unix, and upward
 compatible with Standard C if Standard C specifies their
 
 With occasional exceptions, utility programs and libraries for GNU
 should be upward compatible with those in Berkeley Unix, and upward
 compatible with Standard C if Standard C specifies their

-behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
+behavior, and upward compatible with POSIX if POSIX specifies

 their behavior.
 
 When these standards conflict, it is useful to offer compatibility
 modes for each of them.
 
 @cindex options for compatibility
 their behavior.
 
 When these standards conflict, it is useful to offer compatibility
 modes for each of them.
 
 @cindex options for compatibility

-Standard C and @sc{posix} prohibit many kinds of extensions.  Feel
+Standard C and POSIX prohibit many kinds of extensions.  Feel

 free to make the extensions anyway, and include a @samp{--ansi},
 @samp{--posix}, or @samp{--compatible} option to turn them off.
 However, if the extension has a significant chance of breaking any real
 free to make the extensions anyway, and include a @samp{--ansi},
 @samp{--posix}, or @samp{--compatible} option to turn them off.
 However, if the extension has a significant chance of breaking any real


@@ -360,7 +361,7 @@ programs or scripts, then it is not really upward compatible.  So you
 should try to redesign its interface to make it upward compatible.
 
 @cindex @code{POSIXLY_CORRECT}, environment variable
 should try to redesign its interface to make it upward compatible.
 
 @cindex @code{POSIXLY_CORRECT}, environment variable

-Many GNU programs suppress extensions that conflict with @sc{posix} if the
+Many GNU programs suppress extensions that conflict with POSIX if the

 environment variable @code{POSIXLY_CORRECT} is defined (even if it is
 defined with a null value).  Please make your program recognize this
 variable if appropriate.
 environment variable @code{POSIXLY_CORRECT} is defined (even if it is
 defined with a null value).  Please make your program recognize this
 variable if appropriate.


@@ -408,18 +409,24 @@ already.  That would be extremely troublesome in certain cases.
 
 @node Standard C
 @section Standard C and Pre-Standard C
 
 @node Standard C
 @section Standard C and Pre-Standard C

-@cindex @sc{ansi} C standard
+@cindex ANSI C standard

 
 1989 Standard C is widespread enough now that it is ok to use its
 
 1989 Standard C is widespread enough now that it is ok to use its

-features in new programs.  There is one exception: do not ever use the
+features in programs.  There is one exception: do not ever use the

 ``trigraph'' feature of Standard C.
 
 ``trigraph'' feature of Standard C.
 

-1999 Standard C is not widespread yet, so please do not require its
-features in programs.  It is ok to use its features if they are present.
+The 1999 and 2011 editions of Standard C are not fully supported
+on all platforms.  If you aim to support compilation by
+compilers other than GCC, you should not require these C
+features in your programs.  It is ok to use these features
+conditionally when the compiler supports them.
+
+If your program is only meant to compile with GCC, then you can
+use these features if GCC supports them, when they give substantial
+benefit.

 
 However, it is easy to support pre-standard compilers in most programs,
 
 However, it is easy to support pre-standard compilers in most programs,

-so if you know how to do that, feel free.  If a program you are
-maintaining has such support, you should try to keep it working.
+so if you know how to do that, feel free.

 
 @cindex function prototypes
 To support pre-standard C, instead of writing function definitions in
 
 @cindex function prototypes
 To support pre-standard C, instead of writing function definitions in


@@ -664,10 +671,10 @@ These are supported compatibly by GNU.
 
 @cindex signal handling
 The preferred signal handling facilities are the BSD variant of
 
 @cindex signal handling
 The preferred signal handling facilities are the BSD variant of

-@code{signal}, and the @sc{posix} @code{sigaction} function; the
+@code{signal}, and the POSIX @code{sigaction} function; the

 alternative USG @code{signal} interface is an inferior design.
 
 alternative USG @code{signal} interface is an inferior design.
 

-Nowadays, using the @sc{posix} signal functions may be the easiest way
+Nowadays, using the POSIX signal functions may be the easiest way

 to make a program portable.  If you use @code{signal}, then on GNU/Linux
 systems running GNU libc version 1, you should include
 @file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
 to make a program portable.  If you use @code{signal}, then on GNU/Linux
 systems running GNU libc version 1, you should include
 @file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD


@@ -894,17 +901,16 @@ keyboard-driven console interface (for use by users from console
 mode).  Once you are doing the work to provide the functionality and
 the graphical interface, these won't be much extra work.
 
 mode).  Once you are doing the work to provide the functionality and
 the graphical interface, these won't be much extra work.
 

-

 @node Command-Line Interfaces
 @section Standards for Command Line Interfaces
 @cindex command-line interface
 
 @findex getopt
 @node Command-Line Interfaces
 @section Standards for Command Line Interfaces
 @cindex command-line interface
 
 @findex getopt

-It is a good idea to follow the @sc{posix} guidelines for the
+It is a good idea to follow the POSIX guidelines for the

 command-line options of a program.  The easiest way to do this is to use
 @code{getopt} to parse them.  Note that the GNU version of @code{getopt}
 will normally permit options anywhere among the arguments unless the
 command-line options of a program.  The easiest way to do this is to use
 @code{getopt} to parse them.  Note that the GNU version of @code{getopt}
 will normally permit options anywhere among the arguments unless the

-special argument @samp{--} is used.  This is not what @sc{posix}
+special argument @samp{--} is used.  This is not what POSIX

 specifies; it is a GNU extension.
 
 @cindex long-named options
 specifies; it is a GNU extension.
 
 @cindex long-named options


@@ -1047,7 +1053,8 @@ have legal significance.
 Finally, here is the table of our suggested license abbreviations.
 Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning
 that particular version, or later versions with the @samp{+}, as shown
 Finally, here is the table of our suggested license abbreviations.
 Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning
 that particular version, or later versions with the @samp{+}, as shown

-above.
+above.  In the case of a GNU license, @emph{always} indicate the permitted
+versions in this way.

 
 In the case of exceptions for extra permissions with the GPL, we use
 @samp{/} for a separator; the version number can follow the license
 
 In the case of exceptions for extra permissions with the GPL, we use
 @samp{/} for a separator; the version number can follow the license


@@ -2864,7 +2871,7 @@ versions.  For a GNU program, this kind of portability is desirable, but
 not paramount.
 
 The primary purpose of GNU software is to run on top of the GNU kernel,
 not paramount.
 
 The primary purpose of GNU software is to run on top of the GNU kernel,

-compiled with the GNU C compiler, on various types of @sc{cpu}.  So the
+compiled with the GNU C compiler, on various types of CPU.  So the

 kinds of portability that are absolutely necessary are quite limited.
 But it is important to support Linux-based GNU systems, since they
 are the form of GNU that is popular.
 kinds of portability that are absolutely necessary are quite limited.
 But it is important to support Linux-based GNU systems, since they
 are the form of GNU that is popular.


@@ -2886,7 +2893,7 @@ written.
 Avoid using the format of semi-internal data bases (e.g., directories)
 when there is a higher-level alternative (@code{readdir}).
 
 Avoid using the format of semi-internal data bases (e.g., directories)
 when there is a higher-level alternative (@code{readdir}).
 

-@cindex non-@sc{posix} systems, and portability
+@cindex non-POSIX systems, and portability

 As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS,
 and older Macintosh systems, supporting them is often a lot of work.
 When that is the case, it is better to spend your time adding features
 As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS,
 and older Macintosh systems, supporting them is often a lot of work.
 When that is the case, it is better to spend your time adding features


@@ -2915,11 +2922,11 @@ using their names for any other meanings.  Doing so would make it hard
 to move your code into other GNU programs.
 
 @node CPU Portability
 to move your code into other GNU programs.
 
 @node CPU Portability

-@section Portability between @sc{cpu}s
+@section Portability between CPUs

 
 @cindex data types, and portability
 @cindex portability, and data types
 
 @cindex data types, and portability
 @cindex portability, and data types

-Even GNU systems will differ because of differences among @sc{cpu}
+Even GNU systems will differ because of differences among CPU

 types---for example, difference in byte ordering and alignment
 requirements.  It is absolutely essential to handle these differences.
 However, don't make any effort to cater to the possibility that an
 types---for example, difference in byte ordering and alignment
 requirements.  It is absolutely essential to handle these differences.
 However, don't make any effort to cater to the possibility that an


@@ -2990,12 +2997,12 @@ from zero.
 
 Historically, C implementations differed substantially, and many
 systems lacked a full implementation of ANSI/ISO C89.  Nowadays,
 
 Historically, C implementations differed substantially, and many
 systems lacked a full implementation of ANSI/ISO C89.  Nowadays,

-however, very few systems lack a C89 compiler and GNU C supports
-almost all of C99.  Similarly, most systems implement POSIX.1-1993
-libraries and tools, and many have POSIX.1-2001.
+however, all practical systems have a C89 compiler and GNU C supports
+almost all of C99 and some of C11.  Similarly, most systems implement
+POSIX.1-2001 libraries and tools, and many have POSIX.1-2008.

 
 Hence, there is little reason to support old C or non-POSIX systems,
 
 Hence, there is little reason to support old C or non-POSIX systems,

-and you may want to take advantage of C99 and POSIX-1.2001 to write
+and you may want to take advantage of standard C and POSIX to write

 clearer, more portable, or faster code.  You should use standard
 interfaces where possible; but if GNU extensions make your program
 more maintainable, powerful, or otherwise better, don't hesitate to
 clearer, more portable, or faster code.  You should use standard
 interfaces where possible; but if GNU extensions make your program
 more maintainable, powerful, or otherwise better, don't hesitate to


@@ -4063,6 +4070,7 @@ ignore most of its arguments.
 @section Making Releases
 @cindex packaging
 
 @section Making Releases
 @cindex packaging
 

+@cindex version numbers, for releases

 You should identify each release with a pair of version numbers, a
 major version and a minor.  We have no objection to using more than
 two numbers, but it is very unlikely that you really need them.
 You should identify each release with a pair of version numbers, a
 major version and a minor.  We have no objection to using more than
 two numbers, but it is very unlikely that you really need them.


@@ -4079,20 +4087,28 @@ and never changed automatically; non-source files are produced from
 source files by programs under the control of the Makefile.
 
 @cindex @file{README} file
 source files by programs under the control of the Makefile.
 
 @cindex @file{README} file

-The distribution should contain a file named @file{README} which gives
-the name of the package, and a general description of what it does.  It
-is also good to explain the purpose of each of the first-level
-subdirectories in the package, if there are any.  The @file{README} file
-should either state the version number of the package, or refer to where
-in the package it can be found.
-
-The @file{README} file should refer to the file @file{INSTALL}, which
-should contain an explanation of the installation procedure.
-
-The @file{README} file should also refer to the file which contains the
-copying conditions.  The GNU GPL, if used, should be in a file called
-@file{COPYING}.  If the GNU LGPL is used, it should be in a file called
+The distribution should contain a file named @file{README} with a
+general overview of the package:
+
+@itemize
+@item the name of the package;
+
+@item the version number of the package, or refer to where in the
+package the version can be found;
+
+@item a general description of what the package does;
+
+@item a reference to the file @file{INSTALL}, which
+should in turn contain an explanation of the installation procedure;
+
+@item a brief explanation of any unusual top-level directories or
+files, or other hints for readers to find their way around the source;
+
+@item a reference to the file which contains the copying conditions.
+The GNU GPL, if used, should be in a file called @file{COPYING}.  If
+the GNU LGPL is used, it should be in a file called

 @file{COPYING.LESSER}.
 @file{COPYING.LESSER}.

+@end itemize

 
 Naturally, all the source files must be in the distribution.  It is
 okay to include non-source files in the distribution along with the
 
 Naturally, all the source files must be in the distribution.  It is
 okay to include non-source files in the distribution along with the


@@ -4100,9 +4116,10 @@ source files they are generated from, provided they are up-to-date
 with the source they are made from, and machine-independent, so that
 normal building of the distribution will never modify them.  We
 commonly include non-source files produced by Autoconf, Automake,
 with the source they are made from, and machine-independent, so that
 normal building of the distribution will never modify them.  We
 commonly include non-source files produced by Autoconf, Automake,

-Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+Bison, @code{flex}, @TeX{}, and @code{makeinfo}; this helps avoid

 unnecessary dependencies between our distributions, so that users can
 unnecessary dependencies between our distributions, so that users can

-install whichever packages they want to install.
+install whichever versions of whichever packages they like.  Do not
+induce new dependencies on other software lightly.

 
 Non-source files that might actually be modified by building and
 installing the program should @strong{never} be included in the
 
 Non-source files that might actually be modified by building and
 installing the program should @strong{never} be included in the