+1999-04-01 Ben Elliston <bje@cygnus.com>
+
+ * standards.texi: Update from FSF.
+
+ * acspecific.m4 (AC_PROG_INSTALL): Avoid using the installation
+ script belonging to HP `pwplus' when running the install
+ program. Contributed by Steven G. Johnson <stevenj@alum.mit.edu>
+ and Dave Adams <adams@hpesdwa.fc.hp.com>.
+
1999-03-28 Tom Tromey <tromey@cygnus.com>
* autoconf.texi (AC_OUTPUT_COMMANDS): Add to macro index.
grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
# AIX install. It has an incompatible calling convention.
:
+ elif test $ac_prog = install &&
+ grep pwplus $ac_dir/$ac_prog >/dev/null 2>&1; then
+ # program-specific install script used by HP pwplus--don't use.
+ :
else
ac_cv_path_install="$ac_dir/$ac_prog -c"
break 2
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate February 9, 1999
+@set lastupdate March 26, 1999
@c %**end of header
@ifinfo
@sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
compilers.
+If you don't know non-@sc{ansi} C, there's no need to learn it; just
+write in @sc{ansi} C.
+
However, it is easy to support non-@sc{ansi} compilers in most programs,
-so you might still consider doing so when you write a program. Instead
-of writing function definitions in @sc{ansi} prototype form,
+so you might still consider doing so when you write a program. And if a
+program you are maintaining has such support, you should try to keep it
+working.
+
+To support pre-@sc{ansi} C, instead of writing function definitions in
+@sc{ansi} prototype form,
@example
int
You need such a declaration anyway, in a header file, to get the benefit
of @sc{ansi} C prototypes in all the files where the function is called.
-And once you have it, you lose nothing by writing the function
-definition in the pre-@sc{ansi} style.
-
-If you don't know non-@sc{ansi} C, there's no need to learn it; just
-write in @sc{ansi} C.
+And once you have the declaration, you normally lose nothing by writing
+the function definition in the pre-@sc{ansi} style.
+
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+
+There are a few special cases where this technique is hard to use. For
+example, if a function argument needs to hold the system type
+@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+@code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines. There
+is no type you can safely use on all machines in a non-@sc{ansi}
+definition. The only way to support non-@sc{ansi} C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly. This may not be worth the trouble.
@node Source Language
@section Using Languages Other Than C
@table @code
@item --version
-This option should direct the program to information about its name,
+This option should direct the program to print information about its name,
version, origin and legal status, all on standard output, and then exit
successfully. Other options and arguments should be ignored once this
is seen, and the program should not perform its normal function.
@item dereference-args
@samp{-D} in @code{du}.
+@item device
+Specify an I/O device (special file name).
+
@item diacritics
@samp{-d} in @code{recode}.
@item prompt
@samp{-p} in @code{ed}.
+@item proxy
+Specify an HTTP proxy.
+
@item query-user
@samp{-X} in @code{shar}.
@item time
Used in @code{ls} and @code{touch}.
+@item timeout
+Specify how long to wait before giving up on some operation.
+
@item to-stdout
@samp{-O} in @code{tar}.
casts to @code{void}. Zero without a cast is perfectly fine as a null
pointer constant, except when calling a varargs function.
-@node Names
+@node Names
@section Naming Variables and Functions
The names of global variables and functions in a program serve as
Local variable names can be shorter, because they are used only within
one context, where (presumably) comments explain their purpose.
+Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
Please use underscores to separate words in a name, so that the Emacs
word commands can be useful within them. Stick to lower case; reserve
upper case for macros and @code{enum} constants, and for name-prefixes
@example
error (s, a1, a2, a3)
char *s;
- int a1, a2, a3;
+ char *a1, *a2, *a3;
@{
fprintf (stderr, "error: ");
fprintf (stderr, s, a1, a2, a3);
@end example
@noindent
-In practice, this works on all machines, and it is much simpler than any
-``correct'' alternative. Be sure @emph{not} to use a prototype
-for such functions.
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument, and it is much simpler than any
+``correct'' alternative. Be sure @emph{not} to use a prototype for such
+functions.
However, avoid casting pointers to integers unless you really need to.
-These assumptions really reduce portability, and in most programs they
-are easy to avoid. In the cases where casting pointers to integers is
-essential---such as, a Lisp interpreter which stores type information as
-well as an address in one word---it is ok to do so, but you'll have to
-make explicit provisions to handle different word sizes.
+Outside of special situations, such casts greatly reduce portability,
+and in most programs they are easy to avoid. In the cases where casting
+pointers to integers is essential---such as, a Lisp interpreter which
+stores type information as well as an address in one word---it is ok to
+do it, but you'll have to make explicit provisions to handle different
+word sizes.
@node System Functions
@section Calling System Functions
@menu
* GNU Manuals:: Writing proper manuals.
* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
* NEWS File:: NEWS files supplement manuals.
* Change Logs:: Recording Changes
* Man Pages:: Man pages are secondary.
@section GNU Manuals
The preferred way to document part of the GNU system is to write a
-manual in the Texinfo formatting language. See the Texinfo manual,
-either the hardcopy, or the on-line version available through
-@code{info} or the Emacs Info subsystem (@kbd{C-h i}).
+manual in the Texinfo formatting language. This makes it possible to
+produce a good quality formatted book, using @TeX{}, and to generate an
+Info file. It is also possible to generate HTML output from Texinfo
+source. See the Texinfo manual, either the hardcopy, or the on-line
+version available through @code{info} or the Emacs Info subsystem
+(@kbd{C-h i}).
Programmers often find it most natural to structure the documentation
following the structure of the implementation, which they know. But
and for reading straight through (appendixes aside). A GNU manual
should give a good introduction to a beginner reading through from the
start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
That is not as hard as it first sounds. Arrange each chapter as a
logical breakdown of its topic, but order the sections, and write their
Please do not use the term ``pathname'' that is used in Unix
documentation; use ``file name'' (two words) instead. We use the term
-``path'' only for search paths, which are lists of file names.
+``path'' only for search paths, which are lists of directory names.
Please do not use the term ``illegal'' to refer to erroneous input to a
computer program. Please use ``invalid'' for this, and reserve the term
frequently than or independent of the program, also state a version
number for the manual in both of these places.
-Each program documented in the manual should should have a node named
+Each program documented in the manual should have a node named
@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
node (together with its subnodes, if any) should describe the program's
command line arguments and how to run it (the sort of information people
If one manual describes several programs, it should have such a node for
each program described.
+@node License for Manuals
+@section License for Manuals
+
+If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
+contains chapters that make political or personal statements, please
+copy the distribution terms of the GNU Emacs Manual, and adapt it by
+modifying appropriately the list of special chapters that may not be
+modified or deleted.
+
+If the manual does not contain any such chapters, then imitate the
+simpler distribution terms of the Texinfo manual.
+
@node NEWS File
@section The NEWS File
grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
# AIX install. It has an incompatible calling convention.
:
+ elif test $ac_prog = install &&
+ grep pwplus $ac_dir/$ac_prog >/dev/null 2>&1; then
+ # program-specific install script used by HP pwplus--don't use.
+ :
else
ac_cv_path_install="$ac_dir/$ac_prog -c"
break 2
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate February 9, 1999
+@set lastupdate March 26, 1999
@c %**end of header
@ifinfo
@sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
compilers.
+If you don't know non-@sc{ansi} C, there's no need to learn it; just
+write in @sc{ansi} C.
+
However, it is easy to support non-@sc{ansi} compilers in most programs,
-so you might still consider doing so when you write a program. Instead
-of writing function definitions in @sc{ansi} prototype form,
+so you might still consider doing so when you write a program. And if a
+program you are maintaining has such support, you should try to keep it
+working.
+
+To support pre-@sc{ansi} C, instead of writing function definitions in
+@sc{ansi} prototype form,
@example
int
You need such a declaration anyway, in a header file, to get the benefit
of @sc{ansi} C prototypes in all the files where the function is called.
-And once you have it, you lose nothing by writing the function
-definition in the pre-@sc{ansi} style.
-
-If you don't know non-@sc{ansi} C, there's no need to learn it; just
-write in @sc{ansi} C.
+And once you have the declaration, you normally lose nothing by writing
+the function definition in the pre-@sc{ansi} style.
+
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+
+There are a few special cases where this technique is hard to use. For
+example, if a function argument needs to hold the system type
+@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+@code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines. There
+is no type you can safely use on all machines in a non-@sc{ansi}
+definition. The only way to support non-@sc{ansi} C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly. This may not be worth the trouble.
@node Source Language
@section Using Languages Other Than C
@table @code
@item --version
-This option should direct the program to information about its name,
+This option should direct the program to print information about its name,
version, origin and legal status, all on standard output, and then exit
successfully. Other options and arguments should be ignored once this
is seen, and the program should not perform its normal function.
@item dereference-args
@samp{-D} in @code{du}.
+@item device
+Specify an I/O device (special file name).
+
@item diacritics
@samp{-d} in @code{recode}.
@item prompt
@samp{-p} in @code{ed}.
+@item proxy
+Specify an HTTP proxy.
+
@item query-user
@samp{-X} in @code{shar}.
@item time
Used in @code{ls} and @code{touch}.
+@item timeout
+Specify how long to wait before giving up on some operation.
+
@item to-stdout
@samp{-O} in @code{tar}.
casts to @code{void}. Zero without a cast is perfectly fine as a null
pointer constant, except when calling a varargs function.
-@node Names
+@node Names
@section Naming Variables and Functions
The names of global variables and functions in a program serve as
Local variable names can be shorter, because they are used only within
one context, where (presumably) comments explain their purpose.
+Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
Please use underscores to separate words in a name, so that the Emacs
word commands can be useful within them. Stick to lower case; reserve
upper case for macros and @code{enum} constants, and for name-prefixes
@example
error (s, a1, a2, a3)
char *s;
- int a1, a2, a3;
+ char *a1, *a2, *a3;
@{
fprintf (stderr, "error: ");
fprintf (stderr, s, a1, a2, a3);
@end example
@noindent
-In practice, this works on all machines, and it is much simpler than any
-``correct'' alternative. Be sure @emph{not} to use a prototype
-for such functions.
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument, and it is much simpler than any
+``correct'' alternative. Be sure @emph{not} to use a prototype for such
+functions.
However, avoid casting pointers to integers unless you really need to.
-These assumptions really reduce portability, and in most programs they
-are easy to avoid. In the cases where casting pointers to integers is
-essential---such as, a Lisp interpreter which stores type information as
-well as an address in one word---it is ok to do so, but you'll have to
-make explicit provisions to handle different word sizes.
+Outside of special situations, such casts greatly reduce portability,
+and in most programs they are easy to avoid. In the cases where casting
+pointers to integers is essential---such as, a Lisp interpreter which
+stores type information as well as an address in one word---it is ok to
+do it, but you'll have to make explicit provisions to handle different
+word sizes.
@node System Functions
@section Calling System Functions
@menu
* GNU Manuals:: Writing proper manuals.
* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
* NEWS File:: NEWS files supplement manuals.
* Change Logs:: Recording Changes
* Man Pages:: Man pages are secondary.
@section GNU Manuals
The preferred way to document part of the GNU system is to write a
-manual in the Texinfo formatting language. See the Texinfo manual,
-either the hardcopy, or the on-line version available through
-@code{info} or the Emacs Info subsystem (@kbd{C-h i}).
+manual in the Texinfo formatting language. This makes it possible to
+produce a good quality formatted book, using @TeX{}, and to generate an
+Info file. It is also possible to generate HTML output from Texinfo
+source. See the Texinfo manual, either the hardcopy, or the on-line
+version available through @code{info} or the Emacs Info subsystem
+(@kbd{C-h i}).
Programmers often find it most natural to structure the documentation
following the structure of the implementation, which they know. But
and for reading straight through (appendixes aside). A GNU manual
should give a good introduction to a beginner reading through from the
start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
That is not as hard as it first sounds. Arrange each chapter as a
logical breakdown of its topic, but order the sections, and write their
Please do not use the term ``pathname'' that is used in Unix
documentation; use ``file name'' (two words) instead. We use the term
-``path'' only for search paths, which are lists of file names.
+``path'' only for search paths, which are lists of directory names.
Please do not use the term ``illegal'' to refer to erroneous input to a
computer program. Please use ``invalid'' for this, and reserve the term
frequently than or independent of the program, also state a version
number for the manual in both of these places.
-Each program documented in the manual should should have a node named
+Each program documented in the manual should have a node named
@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
node (together with its subnodes, if any) should describe the program's
command line arguments and how to run it (the sort of information people
If one manual describes several programs, it should have such a node for
each program described.
+@node License for Manuals
+@section License for Manuals
+
+If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
+contains chapters that make political or personal statements, please
+copy the distribution terms of the GNU Emacs Manual, and adapt it by
+modifying appropriately the list of special chapters that may not be
+modified or deleted.
+
+If the manual does not contain any such chapters, then imitate the
+simpler distribution terms of the Texinfo manual.
+
@node NEWS File
@section The NEWS File
projects / thirdparty / autoconf.git / commitdiff
