mirror of
git://git.sv.gnu.org/autoconf
synced 2025-03-19 14:40:24 +08:00
Update auxiliary files.
This commit is contained in:
Akim Demaille
parent
c7a8dfd1cf
commit
174ad6ea74
18
config.guess
vendored
18
config.guess
vendored
@ -3,7 +3,7 @@
|
||||
# Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
|
||||
# Free Software Foundation, Inc.
|
||||
|
||||
version='2000-07-27'
|
||||
version='2000-10-03'
|
||||
|
||||
# This file is free software; you can redistribute it and/or modify it
|
||||
# under the terms of the GNU General Public License as published by
|
||||
@ -669,6 +669,9 @@ EOF
|
||||
i*:MINGW*:*)
|
||||
echo ${UNAME_MACHINE}-pc-mingw32
|
||||
exit 0 ;;
|
||||
i*:PW*:*)
|
||||
echo ${UNAME_MACHINE}-pc-pw32
|
||||
exit 0 ;;
|
||||
i*:Windows_NT*:* | Pentium*:Windows_NT*:*)
|
||||
# How do we know it's Interix rather than the generic POSIX subsystem?
|
||||
# It also conflicts with pre-2.0 versions of AT&T UWIN. Should we
|
||||
@ -695,8 +698,7 @@ EOF
|
||||
# The BFD linker knows what the default object file format is, so
|
||||
# first see if it will tell us. cd to the root directory to prevent
|
||||
# problems with other programs or directories called `ld' in the path.
|
||||
ld_help_string=`cd /; ld --help 2>&1`
|
||||
ld_supported_emulations=`echo $ld_help_string \
|
||||
ld_supported_emulations=`cd /; ld --help 2>&1 \
|
||||
| sed -ne '/supported emulations:/!d
|
||||
s/[ ][ ]*/ /g
|
||||
s/.*supported emulations: *//
|
||||
@ -855,14 +857,16 @@ EOF
|
||||
rm -f $dummy.c $dummy
|
||||
elif test "${UNAME_MACHINE}" = "s390"; then
|
||||
echo s390-ibm-linux && exit 0
|
||||
elif test "${UNAME_MACHINE}" = "x86_64"; then
|
||||
echo x86_64-unknown-linux-gnu && exit 0
|
||||
else
|
||||
# Either a pre-BFD a.out linker (linux-gnuoldld)
|
||||
# or one that does not give us useful --help.
|
||||
# GCC wants to distinguish between linux-gnuoldld and linux-gnuaout.
|
||||
# If ld does not provide *any* "supported emulations:"
|
||||
# that means it is gnuoldld.
|
||||
echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations:"
|
||||
test $? != 0 && echo "${UNAME_MACHINE}-pc-linux-gnuoldld" && exit 0
|
||||
test -z "$ld_supported_emulations" \
|
||||
&& echo "${UNAME_MACHINE}-pc-linux-gnuoldld" && exit 0
|
||||
|
||||
case "${UNAME_MACHINE}" in
|
||||
i?86)
|
||||
@ -1036,7 +1040,7 @@ EOF
|
||||
mc68*:A/UX:*:*)
|
||||
echo m68k-apple-aux${UNAME_RELEASE}
|
||||
exit 0 ;;
|
||||
news*:NEWS-OS:*:6*)
|
||||
news*:NEWS-OS:6*:*)
|
||||
echo mips-sony-newsos6
|
||||
exit 0 ;;
|
||||
R[34]000:*System_V*:*:* | R4000:UNIX_SYSV:*:* | R*000:UNIX_SV:*:*)
|
||||
@ -1079,7 +1083,7 @@ EOF
|
||||
*:QNX:*:4*)
|
||||
echo i386-pc-qnx
|
||||
exit 0 ;;
|
||||
NSR-W:NONSTOP_KERNEL:*:*)
|
||||
NSR-[KW]:NONSTOP_KERNEL:*:*)
|
||||
echo nsr-tandem-nsk${UNAME_RELEASE}
|
||||
exit 0 ;;
|
||||
BS2000:POSIX*:*:*)
|
||||
|
||||
16
config.sub
vendored
16
config.sub
vendored
@ -3,7 +3,7 @@
|
||||
# Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
|
||||
# Free Software Foundation, Inc.
|
||||
|
||||
version='2000-07-27'
|
||||
version='2000-09-11'
|
||||
|
||||
# This file is (in principle) common to ALL GNU software.
|
||||
# The presence of a machine in this file suggests that SOME GNU software
|
||||
@ -204,7 +204,7 @@ case $basic_machine in
|
||||
# Recognize the basic CPU types without company name.
|
||||
# Some are omitted here because they have special meanings below.
|
||||
tahoe | i860 | ia64 | m32r | m68k | m68000 | m88k | ns32k | arc | arm \
|
||||
| arme[lb] | pyramid | mn10200 | mn10300 | tron | a29k \
|
||||
| arme[lb] | armv[2345] | armv[345][lb] | pyramid | mn10200 | mn10300 | tron | a29k \
|
||||
| 580 | i960 | h8300 \
|
||||
| x86 | ppcbe | mipsbe | mipsle | shbe | shle | armbe | armle \
|
||||
| hppa | hppa1.0 | hppa1.1 | hppa2.0 | hppa2.0w | hppa2.0n \
|
||||
@ -232,7 +232,7 @@ case $basic_machine in
|
||||
# We use `pc' rather than `unknown'
|
||||
# because (1) that's what they normally are, and
|
||||
# (2) the word "unknown" tends to confuse beginning users.
|
||||
i[234567]86)
|
||||
i[234567]86 | x86_64)
|
||||
basic_machine=$basic_machine-pc
|
||||
;;
|
||||
# Object if more than one company name word.
|
||||
@ -262,7 +262,7 @@ case $basic_machine in
|
||||
| f301-* | armv*-* | s390-* | sv1-* | t3e-* \
|
||||
| m88110-* | m680[01234]0-* | m683?2-* | m68360-* | z8k-* | d10v-* \
|
||||
| thumb-* | v850-* | d30v-* | tic30-* | c30-* | fr30-* \
|
||||
| bs2000-* | tic54x-* | c54x-*)
|
||||
| bs2000-* | tic54x-* | c54x-* | x86_64-*)
|
||||
;;
|
||||
# Recognize the various machine names and aliases which stand
|
||||
# for a CPU type and a company and sometimes even an OS.
|
||||
@ -517,6 +517,10 @@ case $basic_machine in
|
||||
basic_machine=i386-unknown
|
||||
os=-mingw32
|
||||
;;
|
||||
i[34567]86-pw32 | pw32)
|
||||
basic_machine=i586-unknown
|
||||
os=-pw32
|
||||
;;
|
||||
iris | iris4d)
|
||||
basic_machine=mips-sgi
|
||||
case $os in
|
||||
@ -987,7 +991,7 @@ case $os in
|
||||
| -cygwin* | -pe* | -psos* | -moss* | -proelf* | -rtems* \
|
||||
| -mingw32* | -linux-gnu* | -uxpv* | -beos* | -mpeix* | -udk* \
|
||||
| -interix* | -uwin* | -rhapsody* | -darwin* | -opened* \
|
||||
| -openstep* | -oskit*)
|
||||
| -openstep* | -oskit* | -conix* | -pw32*)
|
||||
# Remember, each alternative MUST END IN *, to match a version number.
|
||||
;;
|
||||
-qnx*)
|
||||
@ -1048,7 +1052,7 @@ case $os in
|
||||
-ns2 )
|
||||
os=-nextstep2
|
||||
;;
|
||||
-nsk)
|
||||
-nsk*)
|
||||
os=-nsk
|
||||
;;
|
||||
# Preserve the version number of sinix5.
|
||||
|
||||
@ -249,9 +249,10 @@ Every Makefile should define the variable @code{INSTALL}, which is the
|
||||
basic command for installing a file into the system.
|
||||
|
||||
Every Makefile should also define the variables @code{INSTALL_PROGRAM}
|
||||
and @code{INSTALL_DATA}. (The default for each of these should be
|
||||
@code{$(INSTALL)}.) Then it should use those variables as the commands
|
||||
for actual installation, for executables and nonexecutables
|
||||
and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should
|
||||
be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
|
||||
@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the
|
||||
commands for actual installation, for executables and nonexecutables
|
||||
respectively. Use these variables as follows:
|
||||
|
||||
@example
|
||||
@ -289,19 +290,21 @@ These two variables set the root for the installation. All the other
|
||||
installation directories should be subdirectories of one of these two,
|
||||
and nothing should be directly installed into these two directories.
|
||||
|
||||
@table @samp
|
||||
@table @code
|
||||
@item prefix
|
||||
@vindex prefix
|
||||
A prefix used in constructing the default values of the variables listed
|
||||
below. The default value of @code{prefix} should be @file{/usr/local}.
|
||||
When building the complete GNU system, the prefix will be empty and
|
||||
@file{/usr} will be a symbolic link to @file{/}.
|
||||
(If you are using Autoconf, write it as @samp{@@prefix@@}.)
|
||||
|
||||
Running @samp{make install} with a different value of @code{prefix}
|
||||
from the one used to build the program should @var{not} recompile
|
||||
the program.
|
||||
Running @samp{make install} with a different value of @code{prefix} from
|
||||
the one used to build the program should @emph{not} recompile the
|
||||
program.
|
||||
|
||||
@item exec_prefix
|
||||
@vindex exec_prefix
|
||||
A prefix used in constructing the default values of some of the
|
||||
variables listed below. The default value of @code{exec_prefix} should
|
||||
be @code{$(prefix)}.
|
||||
@ -312,20 +315,22 @@ machine-specific files (such as executables and subroutine libraries),
|
||||
while @code{$(prefix)} is used directly for other directories.
|
||||
|
||||
Running @samp{make install} with a different value of @code{exec_prefix}
|
||||
from the one used to build the program should @var{not} recompile the
|
||||
from the one used to build the program should @emph{not} recompile the
|
||||
program.
|
||||
@end table
|
||||
|
||||
Executable programs are installed in one of the following directories.
|
||||
|
||||
@table @samp
|
||||
@table @code
|
||||
@item bindir
|
||||
@vindex bindir
|
||||
The directory for installing executable programs that users can run.
|
||||
This should normally be @file{/usr/local/bin}, but write it as
|
||||
@file{$(exec_prefix)/bin}.
|
||||
(If you are using Autoconf, write it as @samp{@@bindir@@}.)
|
||||
|
||||
@item sbindir
|
||||
@vindex sbindir
|
||||
The directory for installing executable programs that can be run from
|
||||
the shell, but are only generally useful to system administrators. This
|
||||
should normally be @file{/usr/local/sbin}, but write it as
|
||||
@ -333,6 +338,7 @@ should normally be @file{/usr/local/sbin}, but write it as
|
||||
(If you are using Autoconf, write it as @samp{@@sbindir@@}.)
|
||||
|
||||
@item libexecdir
|
||||
@vindex libexecdir
|
||||
@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
|
||||
The directory for installing executable programs to be run by other
|
||||
programs rather than by users. This directory should normally be
|
||||
@ -625,7 +631,8 @@ the installation commands. @xref{Install Command Categories}.
|
||||
|
||||
@item install-strip
|
||||
Like @code{install}, but strip the executable files while installing
|
||||
them. In many cases, the definition of this target can be very simple:
|
||||
them. In simple cases, this target can use the @code{install} target in
|
||||
a simple way:
|
||||
|
||||
@smallexample
|
||||
install-strip:
|
||||
@ -633,6 +640,14 @@ install-strip:
|
||||
install
|
||||
@end smallexample
|
||||
|
||||
But if the package installs scripts as well as real executables, the
|
||||
@code{install-strip} target can't just refer to the @code{install}
|
||||
target; it has to strip the executables but not the scripts.
|
||||
|
||||
@code{install-strip} should not strip the executables in the build
|
||||
directory which are being copied for installation. It should only strip
|
||||
the copies that are installed.
|
||||
|
||||
Normally we do not recommend stripping an executable unless you are sure
|
||||
the program has no bugs. However, it can be reasonable to install a
|
||||
stripped executable for actual execution while saving the unstripped
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
@setfilename standards.info
|
||||
@settitle GNU Coding Standards
|
||||
@c This date is automagically updated when you save this file:
|
||||
@set lastupdate July 25, 2000
|
||||
@set lastupdate August 29, 2000
|
||||
@c %**end of header
|
||||
|
||||
@ifinfo
|
||||
@ -65,7 +65,7 @@ by the Free Software Foundation.
|
||||
@page
|
||||
|
||||
@vskip 0pt plus 1filll
|
||||
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
|
||||
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of
|
||||
this manual provided the copyright notice and this permission notice
|
||||
@ -113,7 +113,7 @@ even if you write in another programming language. The rules often
|
||||
state reasons for writing in a certain way.
|
||||
|
||||
Corrections or suggestions for this document should be sent to
|
||||
@email{gnu@@gnu.org}. If you make a suggestion, please include a
|
||||
@email{bug-standards@@gnu.org}. If you make a suggestion, please include a
|
||||
suggested new wording for it; our time is limited. We prefer a context
|
||||
diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
|
||||
you don't have those files, please mail your suggestion anyway.
|
||||
@ -121,6 +121,8 @@ you don't have those files, please mail your suggestion anyway.
|
||||
This release of the GNU Coding Standards was last updated
|
||||
@value{lastupdate}.
|
||||
|
||||
@cindex where to obtain @code{standards.texi}
|
||||
@cindex downloading this manual
|
||||
If you did not obtain this file directly from the GNU project and
|
||||
recently, please check for a newer version. You can ftp the GNU Coding
|
||||
Standards from any GNU FTP host in the directory
|
||||
@ -132,6 +134,7 @@ server: @uref{http://www.gnu.org/prep/standards_toc.html}.
|
||||
|
||||
@node Legal Issues
|
||||
@chapter Keeping Free Software Free
|
||||
@cindex legal aspects
|
||||
|
||||
This @value{CHAPTER} discusses how you can make sure that GNU software
|
||||
avoids legal difficulties, and other related issues.
|
||||
@ -144,6 +147,8 @@ avoids legal difficulties, and other related issues.
|
||||
|
||||
@node Reading Non-Free Code
|
||||
@section Referring to Proprietary Programs
|
||||
@cindex proprietary programs
|
||||
@cindex avoiding proprietary code
|
||||
|
||||
Don't in any circumstances refer to Unix source code for or during
|
||||
your work on GNU! (Or to any other proprietary programs.)
|
||||
@ -177,6 +182,8 @@ to free memory, or use a new GNU facility such as obstacks.
|
||||
|
||||
@node Contributions
|
||||
@section Accepting Contributions
|
||||
@cindex legal papers
|
||||
@cindex accepting contributions
|
||||
|
||||
If the program you are working on is copyrighted by the Free Software
|
||||
Foundation, then when someone else sends you a piece of code to add to
|
||||
@ -221,6 +228,7 @@ released or not), please ask us for a copy.
|
||||
|
||||
@node Trademarks
|
||||
@section Trademarks
|
||||
@cindex trademarks
|
||||
|
||||
Please do not include any trademark acknowledgements in GNU software
|
||||
packages or documentation.
|
||||
@ -242,6 +250,7 @@ language.
|
||||
|
||||
@node Design Advice
|
||||
@chapter General Program Design
|
||||
@cindex program design
|
||||
|
||||
This @value{CHAPTER} discusses some of the issues you should take into
|
||||
account when designing your program.
|
||||
@ -254,15 +263,18 @@ account when designing your program.
|
||||
@c making minor changes. In 1990 ANSI then re-adopted ISO standard
|
||||
@c C. This version of C is known as either ANSI C or Standard C.
|
||||
|
||||
@c A major revision of the C Standard appeared in 1999.
|
||||
|
||||
@menu
|
||||
* Source Language:: Which languges to use.
|
||||
* Compatibility:: Compatibility with other implementations
|
||||
* Using Extensions:: Using non-standard features
|
||||
* Standard C:: Using Standard (ANSI 1989) C features
|
||||
* Standard C:: Using Standard C features
|
||||
@end menu
|
||||
|
||||
@node Source Language
|
||||
@section Which Languages to Use
|
||||
@cindex programming languges
|
||||
|
||||
When you want to use a language that gets compiled and runs at high
|
||||
speed, the best language to use is C. Using another language is like
|
||||
@ -276,7 +288,7 @@ C has one other advantage over C++ and other compiled languages: more
|
||||
people know C, so more people will find it easy to read and modify the
|
||||
program if it is written in C.
|
||||
|
||||
So in general it is much better to use use C, rather than the
|
||||
So in general it is much better to use C, rather than the
|
||||
comparable alternatives.
|
||||
|
||||
But there are two exceptions to that conclusion:
|
||||
@ -299,6 +311,7 @@ for a language that is higher level than C. Often much of the program
|
||||
is written in that language, too. The Emacs editor pioneered this
|
||||
technique.
|
||||
|
||||
@cindex GUILE
|
||||
The standard extensibility interpreter for GNU software is GUILE, which
|
||||
implements the language Scheme (an especially clean and simple dialect
|
||||
of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject
|
||||
@ -308,23 +321,27 @@ the GNU system.
|
||||
|
||||
@node Compatibility
|
||||
@section Compatibility with Other Implementations
|
||||
@cindex compatibility with C and @sc{posix} standards
|
||||
@cindex @sc{posix} compatibility
|
||||
|
||||
With occasional exceptions, utility programs and libraries for GNU
|
||||
should be upward compatible with those in Berkeley Unix, and upward
|
||||
compatible with 1989 Standard C if 1989 Standard C specifies their
|
||||
compatible with Standard C if Standard C specifies their
|
||||
behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
|
||||
their behavior.
|
||||
|
||||
When these standards conflict, it is useful to offer compatibility
|
||||
modes for each of them.
|
||||
|
||||
1989 Standard C and @sc{posix} prohibit many kinds of extensions. Feel
|
||||
@cindex options for compatibility
|
||||
Standard C and @sc{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
|
||||
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
|
||||
Many GNU programs suppress extensions that conflict with @sc{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
|
||||
@ -341,6 +358,7 @@ there is any precedent for them.
|
||||
|
||||
@node Using Extensions
|
||||
@section Using Non-standard Features
|
||||
@cindex non-standard extensions
|
||||
|
||||
Many GNU facilities that already exist support a number of convenient
|
||||
extensions over the comparable Unix facilities. Whether to use these
|
||||
@ -371,16 +389,21 @@ compiler, then no one can compile them without having them installed
|
||||
already. That would be extremely troublesome in certain cases.
|
||||
|
||||
@node Standard C
|
||||
@section 1989 Standard C and Pre-Standard C
|
||||
@section Standard C and Pre-Standard C
|
||||
@cindex @sc{ansi} C standard
|
||||
|
||||
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
|
||||
``trigraph'' feature of 1989 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.
|
||||
|
||||
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.
|
||||
|
||||
@cindex function prototypes
|
||||
To support pre-standard C, instead of writing function definitions in
|
||||
standard prototype form,
|
||||
|
||||
@ -460,11 +483,13 @@ command line interface, and how libraries should behave.
|
||||
@node Semantics
|
||||
@section Writing Robust Programs
|
||||
|
||||
@cindex arbitrary limits on data
|
||||
Avoid arbitrary limits on the length or number of @emph{any} data
|
||||
structure, including file names, lines, files, and symbols, by allocating
|
||||
all data structures dynamically. In most Unix utilities, ``long lines
|
||||
are silently truncated''. This is not acceptable in a GNU utility.
|
||||
|
||||
@cindex @code{NUL} characters
|
||||
Utilities reading files should not drop NUL characters, or any other
|
||||
nonprinting characters @emph{including those with codes above 0177}.
|
||||
The only sensible exceptions would be utilities specifically intended
|
||||
@ -474,6 +499,7 @@ Whenever possible, try to make programs work properly with
|
||||
sequences of bytes that represent multibyte characters, using encodings
|
||||
such as UTF-8 and others.
|
||||
|
||||
@cindex error messages
|
||||
Check every system call for an error return, unless you know you wish to
|
||||
ignore errors. Include the system error text (from @code{perror} or
|
||||
equivalent) in @emph{every} error message resulting from a failing
|
||||
@ -481,6 +507,8 @@ system call, as well as the name of the file if any and the name of the
|
||||
utility. Just ``cannot open foo.c'' or ``stat failed'' is not
|
||||
sufficient.
|
||||
|
||||
@cindex @code{malloc} return value
|
||||
@cindex memory allocation failure
|
||||
Check every call to @code{malloc} or @code{realloc} to see if it
|
||||
returned zero. Check @code{realloc} even if you are making the block
|
||||
smaller; in a system that rounds block sizes to a power of 2,
|
||||
@ -502,6 +530,7 @@ user), it is better to abort the command and return to the command
|
||||
reader loop. This allows the user to kill other processes to free up
|
||||
virtual memory, and then try the command again.
|
||||
|
||||
@cindex command-line arguments, decoding
|
||||
Use @code{getopt_long} to decode arguments, unless the argument syntax
|
||||
makes this unreasonable.
|
||||
|
||||
@ -516,6 +545,7 @@ are less likely to work compatibly. If you need to find all the files
|
||||
in a directory, use @code{readdir} or some other high-level interface.
|
||||
These are supported compatibly by GNU.
|
||||
|
||||
@cindex signal handling
|
||||
The preferred signal handling facilities are the BSD variant of
|
||||
@code{signal}, and the @sc{posix} @code{sigaction} function; the
|
||||
alternative USG @code{signal} interface is an inferior design.
|
||||
@ -527,6 +557,7 @@ systems running GNU libc version 1, you should include
|
||||
behavior. It is up to you whether to support systems where
|
||||
@code{signal} has only the USG behavior, or give up on them.
|
||||
|
||||
@cindex impossible conditions
|
||||
In error checks that detect ``impossible'' conditions, just abort.
|
||||
There is usually no point in printing any message. These checks
|
||||
indicate the existence of bugs. Whoever wants to fix the bugs will have
|
||||
@ -541,6 +572,8 @@ bits (0 through 255). A single run of the program might have 256
|
||||
errors; if you try to return 256 as the exit status, the parent process
|
||||
will see 0 as the status, and it will appear that the program succeeded.
|
||||
|
||||
@cindex temporary files
|
||||
@cindex @code{TMPDIR} environment variable
|
||||
If you make temporary files, check the @code{TMPDIR} environment
|
||||
variable; if that variable is defined, use the specified directory
|
||||
instead of @file{/tmp}.
|
||||
@ -560,6 +593,7 @@ In bash, use @code{set -C} to avoid this problem.
|
||||
|
||||
@node Libraries
|
||||
@section Library Behavior
|
||||
@cindex libraries
|
||||
|
||||
Try to make library functions reentrant. If they need to do dynamic
|
||||
storage allocation, at least try to avoid any nonreentrancy aside from
|
||||
@ -589,6 +623,8 @@ fit any naming convention.
|
||||
|
||||
@node Errors
|
||||
@section Formatting Error Messages
|
||||
@cindex formatting error messages
|
||||
@cindex error messages, formatting
|
||||
|
||||
Error messages from compilers should look like this:
|
||||
|
||||
@ -650,6 +686,8 @@ end with a period.
|
||||
@node User Interfaces
|
||||
@section Standards for Interfaces Generally
|
||||
|
||||
@cindex program name and its behavior
|
||||
@cindex behavior, dependent on program's name
|
||||
Please don't make the behavior of a utility depend on the name used
|
||||
to invoke it. It is useful sometimes to make a link to a utility
|
||||
with a different name, and that should not change what it does.
|
||||
@ -657,6 +695,7 @@ with a different name, and that should not change what it does.
|
||||
Instead, use a run time option or a compilation switch or both
|
||||
to select among the alternate behaviors.
|
||||
|
||||
@cindex output device and program's behavior
|
||||
Likewise, please don't make the behavior of the program depend on the
|
||||
type of output device it is used with. Device independence is an
|
||||
important principle of the system's design; do not compromise it merely
|
||||
@ -680,7 +719,9 @@ multi-column format.
|
||||
|
||||
@node Graphical Interfaces
|
||||
@section Standards for Graphical Interfaces
|
||||
@cindex graphical user interface
|
||||
|
||||
@cindex gtk
|
||||
When you write a program that provides a graphical user interface,
|
||||
please make it work with X Windows and the GTK toolkit unless the
|
||||
functionality specifically requires some alternative (for example,
|
||||
@ -691,6 +732,8 @@ functionality. (In many cases, the graphical user interface can be a
|
||||
separate program which invokes the command-line program.) This is
|
||||
so that the same jobs can be done from scripts.
|
||||
|
||||
@cindex corba
|
||||
@cindex gnome
|
||||
Please also consider providing a CORBA interface (for use from GNOME), a
|
||||
library interface (for use from C), and perhaps a keyboard-driven
|
||||
console interface (for use by users from console mode). Once you are
|
||||
@ -699,7 +742,9 @@ these won't be much extra work.
|
||||
|
||||
@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
|
||||
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}
|
||||
@ -707,6 +752,7 @@ will normally permit options anywhere among the arguments unless the
|
||||
special argument @samp{--} is used. This is not what @sc{posix}
|
||||
specifies; it is a GNU extension.
|
||||
|
||||
@cindex long-named options
|
||||
Please define long-named options that are equivalent to the
|
||||
single-letter Unix-style options. We hope to make GNU more user
|
||||
friendly this way. This is easy to do with the GNU function
|
||||
@ -726,16 +772,20 @@ file name as an ordinary argument for compatibility, try to provide an
|
||||
option as another way to specify it. This will lead to more consistency
|
||||
among GNU utilities, and fewer idiosyncracies for users to remember.
|
||||
|
||||
@cindex standard command-line options
|
||||
All programs should support two standard options: @samp{--version}
|
||||
and @samp{--help}.
|
||||
|
||||
@table @code
|
||||
@cindex @samp{--version} option
|
||||
@item --version
|
||||
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.
|
||||
|
||||
@cindex canonical name of a program
|
||||
@cindex program's canonical name
|
||||
The first line is meant to be easy for a program to parse; the version
|
||||
number proper starts after the last space. In addition, it contains
|
||||
the canonical name for this program, in this format:
|
||||
@ -808,12 +858,15 @@ versions' changes. You don't have to mention the name of the program in
|
||||
these notices, if that is inconvenient, since it appeared in the first
|
||||
line.
|
||||
|
||||
@cindex @samp{--help} option
|
||||
@item --help
|
||||
This option should output brief documentation for how to invoke the
|
||||
program, on standard output, then exit successfully. Other options and
|
||||
arguments should be ignored once this is seen, and the program should
|
||||
not perform its normal function.
|
||||
|
||||
@cindex address for bug reports
|
||||
@cindex bug reports
|
||||
Near the end of the @samp{--help} option's output there should be a line
|
||||
that says where to mail bug reports. It should have this format:
|
||||
|
||||
@ -824,11 +877,13 @@ Report bugs to @var{mailing-address}.
|
||||
|
||||
@node Option Table
|
||||
@section Table of Long Options
|
||||
@cindex long option names
|
||||
@cindex table of long options
|
||||
|
||||
Here is a table of long options used by GNU programs. It is surely
|
||||
incomplete, but we aim to list all the options that a new program might
|
||||
want to be compatible with. If you use names not already in the table,
|
||||
please send @email{gnu@@gnu.org} a list of them, with their
|
||||
please send @email{bug-standards@@gnu.org} a list of them, with their
|
||||
meanings, so we can update the table.
|
||||
|
||||
@c Please leave newlines between items in this table; it's much easier
|
||||
@ -1941,8 +1996,9 @@ Print the version number.
|
||||
|
||||
@node Memory Usage
|
||||
@section Memory Usage
|
||||
@cindex memory usage
|
||||
|
||||
If it typically uses just a few meg of memory, don't bother making any
|
||||
If a program typically uses just a few meg of memory, don't bother making any
|
||||
effort to reduce memory usage. For example, if it is impractical for
|
||||
other reasons to operate on files more than a few meg long, it is
|
||||
reasonable to read entire input files into core to operate on them.
|
||||
@ -1960,6 +2016,7 @@ core and give a fatal error if @code{malloc} returns zero.
|
||||
|
||||
@node File Usage
|
||||
@section File Usage
|
||||
@cindex file usage
|
||||
|
||||
Programs should be prepared to operate when @file{/usr} and @file{/etc}
|
||||
are read-only file systems. Thus, if the program manages log files,
|
||||
@ -1996,6 +2053,8 @@ when writing GNU software.
|
||||
@section Formatting Your Source Code
|
||||
@cindex formatting source code
|
||||
|
||||
@cindex open brace
|
||||
@cindex braces, in C source
|
||||
It is important to put the open-brace that starts the body of a C
|
||||
function in column zero, and avoid putting any other open-brace or
|
||||
open-parenthesis or open-bracket in column zero. Several tools look
|
||||
@ -2182,6 +2241,8 @@ There should be a comment on each static variable as well, like this:
|
||||
int truncate_lines;
|
||||
@end example
|
||||
|
||||
@cindex conditionals, comments for
|
||||
@cindex @code{#endif}, commenting
|
||||
Every @samp{#endif} should have a comment, except in the case of short
|
||||
conditionals (just a few lines) that are not nested. The comment should
|
||||
state the condition of the conditional that is ending, @emph{including
|
||||
@ -2223,12 +2284,17 @@ but, by contrast, write the comments this way for a @samp{#ifndef}:
|
||||
|
||||
@node Syntactic Conventions
|
||||
@section Clean Use of C Constructs
|
||||
@cindex syntactic conventions
|
||||
|
||||
@cindex implicit @code{int}
|
||||
@cindex function argument, declaring
|
||||
Please explicitly declare all arguments to functions.
|
||||
Don't omit them just because they are @code{int}s.
|
||||
Please explicitly declare the types of all objects. For example, you
|
||||
should explicitly declare all arguments to functions, and you should
|
||||
declare functions to return @code{int} rather than omitting the
|
||||
@code{int}.
|
||||
|
||||
@cindex compiler warnings
|
||||
@cindex @samp{-Wall} compiler option
|
||||
Some programmers like to use the GCC @samp{-Wall} option, and change the
|
||||
code whenever it issues a warning. If you want to do this, then do.
|
||||
Other programmers prefer not to use @samp{-Wall}, because it gives
|
||||
@ -2242,6 +2308,7 @@ source file should all go in one place near the beginning of the file
|
||||
should go in a header file. Don't put @code{extern} declarations inside
|
||||
functions.
|
||||
|
||||
@cindex temporary variables
|
||||
It used to be common practice to use the same local variables (with
|
||||
names like @code{tem}) over and over for different values within one
|
||||
function. Instead of doing this, it is better declare a separate local
|
||||
@ -2354,6 +2421,7 @@ if (foo == 0)
|
||||
fatal ("virtual memory exhausted");
|
||||
@end example
|
||||
|
||||
@pindex lint
|
||||
Don't make the program ugly to placate @code{lint}. Please don't insert any
|
||||
casts to @code{void}. Zero without a cast is perfectly fine as a null
|
||||
pointer constant, except when calling a varargs function.
|
||||
@ -2399,6 +2467,8 @@ When you want to define names with constant integer values, use
|
||||
@code{enum} rather than @samp{#define}. GDB knows about enumeration
|
||||
constants.
|
||||
|
||||
@cindex file-name limitations
|
||||
@pindex doschk
|
||||
Use file names of 14 characters or less, to avoid creating gratuitous
|
||||
problems on older System V systems. You can use the program
|
||||
@code{doschk} to test for this. @code{doschk} also tests for potential
|
||||
@ -2407,6 +2477,7 @@ system---something you may or may not care about.
|
||||
|
||||
@node System Portability
|
||||
@section Portability between System Types
|
||||
@cindex portability, between system types
|
||||
|
||||
In the Unix world, ``portability'' refers to porting to different Unix
|
||||
versions. For a GNU program, this kind of portability is desirable, but
|
||||
@ -2423,6 +2494,7 @@ But many users do run GNU software on non-GNU Unix or Unix-like systems.
|
||||
So supporting a variety of Unix-like systems is desirable, although not
|
||||
paramount.
|
||||
|
||||
@pindex autoconf
|
||||
The easiest way to achieve portability to most Unix-like systems is to
|
||||
use Autoconf. It's unlikely that your program needs to know more
|
||||
information about the host platform than Autoconf can provide, simply
|
||||
@ -2432,6 +2504,7 @@ written.
|
||||
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
|
||||
As for systems that are not like Unix, such as MSDOS, Windows, the
|
||||
Macintosh, VMS, and MVS, supporting them is often a lot of work. When
|
||||
that is the case, it is better to spend your time adding features that
|
||||
@ -2453,6 +2526,8 @@ to move your code into other GNU programs.
|
||||
@node CPU Portability
|
||||
@section Portability between @sc{cpu}s
|
||||
|
||||
@cindex data types, and portability
|
||||
@cindex portability, and data types
|
||||
Even GNU systems will differ because of differences among @sc{cpu}
|
||||
types---for example, difference in byte ordering and alignment
|
||||
requirements. It is absolutely essential to handle these differences.
|
||||
@ -2460,6 +2535,25 @@ However, don't make any effort to cater to the possibility that an
|
||||
@code{int} will be less than 32 bits. We don't support 16-bit machines
|
||||
in GNU.
|
||||
|
||||
Similarly, don't make any effort to cater to the possibility that
|
||||
@code{long} will be smaller than predefined types like @code{size_t}.
|
||||
For example, the following code is ok:
|
||||
|
||||
@example
|
||||
printf ("size = %lu\n", (unsigned long) sizeof array);
|
||||
printf ("diff = %ld\n", (long) (pointer2 - pointer1));
|
||||
@end example
|
||||
|
||||
1989 Standard C requires this to work, and we know of only one
|
||||
counterexample: 64-bit programs on Microsoft Windows IA-64. We will
|
||||
leave it to those who want to port GNU programs to that environment
|
||||
to figure out how to do it.
|
||||
|
||||
Predefined file-size types like @code{off_t} are an exception: they are
|
||||
longer than @code{long} on many platforms, so code like the above won't
|
||||
work with them. One way to print an @code{off_t} value portably is to
|
||||
print its digits yourself, one by one.
|
||||
|
||||
Don't assume that the address of an @code{int} object is also the
|
||||
address of its least-significant byte. This is false on big-endian
|
||||
machines. Thus, don't make the following mistake:
|
||||
@ -2474,7 +2568,7 @@ while ((c = getchar()) != EOF)
|
||||
When calling functions, you need not worry about the difference between
|
||||
pointers of various types, or between pointers and integers. On most
|
||||
machines, there's no difference anyway. As for the few machines where
|
||||
there is a difference, all of them support 1989 Standard C, so you can
|
||||
there is a difference, all of them support Standard C prototypes, so you can
|
||||
use prototypes (perhaps conditionalized to be active only in Standard C)
|
||||
to make the code work on those systems.
|
||||
|
||||
@ -2499,10 +2593,11 @@ the widest possible kind of argument; it is much simpler than any
|
||||
``correct'' alternative. Be sure @emph{not} to use a prototype for such
|
||||
functions.
|
||||
|
||||
If you have decided to use 1989 Standard C, then you can instead define
|
||||
If you have decided to use Standard C, then you can instead define
|
||||
@code{error} using @file{stdarg.h}, and pass the arguments along to
|
||||
@code{vfprintf}.
|
||||
|
||||
@cindex casting pointers to integers
|
||||
Avoid casting pointers to integers if you can. 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
|
||||
@ -2514,8 +2609,10 @@ from zero.
|
||||
|
||||
@node System Functions
|
||||
@section Calling System Functions
|
||||
@cindex library functions, and portability
|
||||
@cindex portability, and library functions
|
||||
|
||||
C implementations differ substantially. 1989 Standard C reduces but does
|
||||
C implementations differ substantially. Standard C reduces but does
|
||||
not eliminate the incompatibilities; meanwhile, many GNU packages still
|
||||
support pre-standard compilers because this is not hard to do. This
|
||||
chapter gives recommendations for how to use the more-or-less standard C
|
||||
@ -2534,6 +2631,7 @@ Be aware that @code{vfprintf} is not always available.
|
||||
terminate either by calling @code{exit} or by returning the integer
|
||||
status code; make sure it cannot ever return an undefined value.
|
||||
|
||||
@cindex declaration for system functions
|
||||
@item
|
||||
Don't declare system functions explicitly.
|
||||
|
||||
@ -2572,6 +2670,7 @@ exceptional systems (mostly 64-bit machines), you can use
|
||||
@code{realloc}---or put these declarations in configuration files
|
||||
specific to those systems.
|
||||
|
||||
@cindex string library functions
|
||||
@item
|
||||
The string functions require special treatment. Some Unix systems have
|
||||
a header file @file{string.h}; others have @file{strings.h}. Neither
|
||||
@ -2638,7 +2737,9 @@ One way to get them properly defined is to use Autoconf.
|
||||
|
||||
@node Internationalization
|
||||
@section Internationalization
|
||||
@cindex internationalization
|
||||
|
||||
@pindex gettext
|
||||
GNU has a library called GNU gettext that makes it easy to translate the
|
||||
messages in a program into various languages. You should use this
|
||||
library in every program. Use English for the messages as they appear
|
||||
@ -2665,6 +2766,7 @@ translations for this package from the translations for other packages.
|
||||
Normally, the text domain name should be the same as the name of the
|
||||
package---for example, @samp{fileutils} for the GNU file utilities.
|
||||
|
||||
@cindex message text, and internationalization
|
||||
To enable gettext to work well, avoid writing code that makes
|
||||
assumptions about the structure of words or sentences. When you want
|
||||
the precise text of a sentence to vary depending on the data, use two or
|
||||
@ -2736,6 +2838,7 @@ printf (f->tried_implicit
|
||||
|
||||
@node Mmap
|
||||
@section Mmap
|
||||
@findex mmap
|
||||
|
||||
Don't assume that @code{mmap} either works on all files or fails
|
||||
for all files. It may work on some files and fail on others.
|
||||
@ -2752,6 +2855,7 @@ all these kinds of files.
|
||||
|
||||
@node Documentation
|
||||
@chapter Documenting Programs
|
||||
@cindex documentation
|
||||
|
||||
A GNU program should ideally come with full free documentation, adequate
|
||||
for both reference and tutorial purposes. If the package can be
|
||||
@ -2760,8 +2864,10 @@ extending it, as well as just using it.
|
||||
|
||||
@menu
|
||||
* GNU Manuals:: Writing proper manuals.
|
||||
* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
|
||||
* Manual Structure Details:: Specific structure conventions.
|
||||
* License for Manuals:: Writing the distribution terms for a manual.
|
||||
* Manual Credits:: Giving credit to documentation contributors.
|
||||
* NEWS File:: NEWS files supplement manuals.
|
||||
* Change Logs:: Recording Changes
|
||||
* Man Pages:: Man pages are secondary.
|
||||
@ -2772,13 +2878,18 @@ extending it, as well as just using it.
|
||||
@node GNU Manuals
|
||||
@section GNU Manuals
|
||||
|
||||
The preferred way to document part of the GNU system is to write a
|
||||
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}).
|
||||
The preferred document format for the GNU system is the Texinfo
|
||||
formatting language. Every GNU package should (ideally) have
|
||||
documentation in Texinfo both for reference and for learners. Texinfo
|
||||
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}).
|
||||
|
||||
Nowadays some other formats such as Docbook and Sgmltexi can be
|
||||
converted automatically into Texinfo. It is ok to produce the Texinfo
|
||||
documentation by conversion this way, as long as it gives good results.
|
||||
|
||||
Programmers often find it most natural to structure the documentation
|
||||
following the structure of the implementation, which they know. But
|
||||
@ -2807,9 +2918,9 @@ have one manual for ``comparison of files'' which covers both of those
|
||||
programs, as well as @code{cmp}. By documenting these programs
|
||||
together, we can make the whole subject clearer.
|
||||
|
||||
The manual which discusses a program should document all of the
|
||||
program's command-line options and all of its commands. It should give
|
||||
examples of their use. But don't organize the manual as a list of
|
||||
The manual which discusses a program should certainly document all of
|
||||
the program's command-line options and all of its commands. It should
|
||||
give examples of their use. But don't organize the manual as a list of
|
||||
features. Instead, organize it logically, by subtopics. Address the
|
||||
questions that a user will ask when thinking about the job that the
|
||||
program does.
|
||||
@ -2834,10 +2945,19 @@ are purely tutorial and cover the basics of the subject. These provide
|
||||
the framework for a beginner to understand the rest of the manual. The
|
||||
Bison manual provides a good example of how to do this.
|
||||
|
||||
To serve as a reference, a manual should have an Index that list all the
|
||||
functions, variables, options, and important concepts that are part of
|
||||
the program. One combined Index should do for a short manual, but
|
||||
sometimes for a complex package it is better to use multiple indices.
|
||||
The Texinfo manual includes advice on preparing good index entries, see
|
||||
@ref{Index Entries, , Making Index Entries, texinfo, The GNU Texinfo
|
||||
Manual}, and see @ref{Indexing Commands, , Defining the Entries of an
|
||||
Index, texinfo, The GNU Texinfo manual}.
|
||||
|
||||
Don't use Unix man pages as a model for how to write GNU documentation;
|
||||
most of them are terse, badly structured, and give inadequate
|
||||
explanation of the underlying concepts. (There are, of course
|
||||
exceptions.) Also Unix man pages use a particular format which is
|
||||
explanation of the underlying concepts. (There are, of course, some
|
||||
exceptions.) Also, Unix man pages use a particular format which is
|
||||
different from what we use in GNU manuals.
|
||||
|
||||
Please include an email address in the manual for where to report
|
||||
@ -2849,10 +2969,38 @@ documentation; use ``file name'' (two words) instead. We use the term
|
||||
|
||||
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
|
||||
``illegal'' for violations of law.
|
||||
``illegal'' for activities punishable by law.
|
||||
|
||||
@node Doc Strings and Manuals
|
||||
@section Doc Strings and Manuals
|
||||
|
||||
Some programming systems, such as Emacs, provide a documentation string
|
||||
for each function, command or variable. You may be tempted to write a
|
||||
reference manual by compiling the documentation strings and writing a
|
||||
little additional text to go around them---but you must not do it. That
|
||||
approach is a fundamental mistake. The text of well-written
|
||||
documentation strings will be entirely wrong for a manual.
|
||||
|
||||
A documentation string needs to stand alone---when it appears on the
|
||||
screen, there will be no other text to introduce or explain it.
|
||||
Meanwhile, it can be rather informal in style.
|
||||
|
||||
The text describing a function or variable in a manual must not stand
|
||||
alone; it appears in the context of a section or subsection. Other text
|
||||
at the beginning of the section should explain some of the concepts, and
|
||||
should often make some general points that apply to several functions or
|
||||
variables. The previous descriptions of functions and variables in the
|
||||
section will also have given information about the topic. A description
|
||||
written to stand alone would repeat some of that information; this
|
||||
redundance looks bad. Meanwhile, the informality that is acceptable in
|
||||
a documentation string is totally unacceptable in a manual.
|
||||
|
||||
The only good way to use documentation strings in writing a good manual
|
||||
is to use them as a source of information for writing good text.
|
||||
|
||||
@node Manual Structure Details
|
||||
@section Manual Structure Details
|
||||
@cindex manual structure
|
||||
|
||||
The title page of the manual should state the version of the programs or
|
||||
packages documented in the manual. The Top node of the manual should
|
||||
@ -2872,14 +3020,16 @@ Alternatively, put a menu item in some menu whose item name fits one of
|
||||
the above patterns. This identifies the node which that item points to
|
||||
as the node for this purpose, regardless of the node's actual name.
|
||||
|
||||
There will be automatic features for specifying a program name and
|
||||
quickly reading just this part of its manual.
|
||||
The @samp{--usage} feature of the Info reader looks for such a node
|
||||
or menu item in order to find the relevant text, so it is essential
|
||||
for every Texinfo file to have one.
|
||||
|
||||
If one manual describes several programs, it should have such a node for
|
||||
each program described.
|
||||
each program described in the manual.
|
||||
|
||||
@node License for Manuals
|
||||
@section License for Manuals
|
||||
@cindex license for manuals
|
||||
|
||||
Please use the GNU Free Documentation License for all GNU manuals that
|
||||
are more than a few pages long. Likewise for a collection of short
|
||||
@ -2887,8 +3037,18 @@ documents---you only need one copy of the GNU FDL for the whole
|
||||
collection. For a single short document, you can use a very permissive
|
||||
non-copyleft license, to avoid taking up space with a long license.
|
||||
|
||||
@node Manual Credits
|
||||
@section Manual Credits
|
||||
@cindex credits for manuals
|
||||
|
||||
Please credit the principal human writers of the manual as the authors,
|
||||
on the title page of the manual. If a company sponsored the work, thank
|
||||
the company in a suitable place in the manual, but do not cite the
|
||||
company as an author.
|
||||
|
||||
@node NEWS File
|
||||
@section The NEWS File
|
||||
@cindex @file{NEWS} file
|
||||
|
||||
In addition to its manual, the package should have a file named
|
||||
@file{NEWS} which contains a list of user-visible changes worth
|
||||
@ -2903,6 +3063,7 @@ user to that file.
|
||||
|
||||
@node Change Logs
|
||||
@section Change Logs
|
||||
@cindex change logs
|
||||
|
||||
Keep a change log to describe all the changes made to program source
|
||||
files. The purpose of this is so that people investigating bugs in the
|
||||
@ -2958,10 +3119,16 @@ Then describe the changes you made to that function or variable.
|
||||
|
||||
@node Style of Change Logs
|
||||
@subsection Style of Change Logs
|
||||
@cindex change logs, style
|
||||
|
||||
Here are some examples of change log entries:
|
||||
Here are some simple examples of change log entries, starting with the
|
||||
header line that says who made the change and when, followed by
|
||||
descriptions of specific changes. (These examples are drawn from Emacs
|
||||
and GCC.)
|
||||
|
||||
@example
|
||||
1998-08-17 Richard Stallman <rms@@gnu.org>
|
||||
|
||||
* register.el (insert-register): Return nil.
|
||||
(jump-to-register): Likewise.
|
||||
|
||||
@ -2974,9 +3141,6 @@ Restart the tex shell if process is gone or stopped.
|
||||
* expr.c (store_one_arg): Round size up for move_block_to_reg.
|
||||
(expand_call): Round up when emitting USE insns.
|
||||
* stmt.c (assign_parms): Round size up for move_block_from_reg.
|
||||
|
||||
* keyboard.c (menu_bar_items, tool_bar_items)
|
||||
(Fexecute_extended_command): Deal with `keymap' property.
|
||||
@end example
|
||||
|
||||
It's important to name the changed function or variable in full. Don't
|
||||
@ -2997,7 +3161,12 @@ name and the asterisk when successive entries are in the same file.
|
||||
|
||||
Break long lists of function names by closing continued lines with
|
||||
@samp{)}, rather than @samp{,}, and opening the continuation with
|
||||
@samp{(} as in the example above.
|
||||
@samp{(} as in this example:
|
||||
|
||||
@example
|
||||
* keyboard.c (menu_bar_items, tool_bar_items)
|
||||
(Fexecute_extended_command): Deal with `keymap' property.
|
||||
@end example
|
||||
|
||||
@node Simple Changes
|
||||
@subsection Simple Changes
|
||||
@ -3006,9 +3175,10 @@ Certain simple kinds of changes don't need much detail in the change
|
||||
log.
|
||||
|
||||
When you change the calling sequence of a function in a simple fashion,
|
||||
and you change all the callers of the function, there is no need to make
|
||||
individual entries for all the callers that you changed. Just write in
|
||||
the entry for the function being called, ``All callers changed.''
|
||||
and you change all the callers of the function to use the new calling
|
||||
sequence, there is no need to make individual entries for all the
|
||||
callers that you changed. Just write in the entry for the function
|
||||
being called, ``All callers changed''---like this:
|
||||
|
||||
@example
|
||||
* keyboard.c (Fcommand_execute): New arg SPECIAL.
|
||||
@ -3028,6 +3198,8 @@ documentation says with the way the program actually works.
|
||||
|
||||
@node Conditional Changes
|
||||
@subsection Conditional Changes
|
||||
@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
|
||||
@ -3072,8 +3244,8 @@ a certain macro is @emph{not} defined:
|
||||
|
||||
Indicate the part of a function which changed by using angle brackets
|
||||
enclosing an indication of what the changed part does. Here is an entry
|
||||
for a change in the part of the function that deals with @code{sh}
|
||||
commands.
|
||||
for a change in the part of the function @code{sh-while-getopts} that
|
||||
deals with @code{sh} commands:
|
||||
|
||||
@example
|
||||
* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
|
||||
@ -3083,6 +3255,7 @@ user-specified option string is empty.
|
||||
|
||||
@node Man Pages
|
||||
@section Man Pages
|
||||
@cindex man pages
|
||||
|
||||
In the GNU project, man pages are secondary. It is not necessary or
|
||||
expected for every GNU program to have a man page, but some of them do.
|
||||
@ -3129,6 +3302,7 @@ with the FSF about the individual case.
|
||||
|
||||
@node Managing Releases
|
||||
@chapter The Release Process
|
||||
@cindex releasing
|
||||
|
||||
Making a release is more than just bundling up your source files in a
|
||||
tar file and putting it up for FTP. You should set up your software so
|
||||
@ -3146,7 +3320,9 @@ all GNU software.
|
||||
|
||||
@node Configuration
|
||||
@section How Configuration Should Work
|
||||
@cindex program configuration
|
||||
|
||||
@pindex configure
|
||||
Each GNU distribution should come with a shell script named
|
||||
@code{configure}. This script is given arguments which describe the
|
||||
kind of machine and system you want to compile the program for.
|
||||
@ -3221,6 +3397,7 @@ might need to distinguish them.
|
||||
There is a shell script called @file{config.sub} that you can use
|
||||
as a subroutine to validate system types and canonicalize aliases.
|
||||
|
||||
@cindex optional features, configure-time
|
||||
Other options are permitted to specify in more detail the software
|
||||
or hardware present on the machine, and include or exclude optional
|
||||
parts of the package:
|
||||
@ -3315,6 +3492,7 @@ ignore most of its arguments.
|
||||
|
||||
@node Releases
|
||||
@section Making Releases
|
||||
@cindex packaging
|
||||
|
||||
Package the distribution of @code{Foo version 69.96} up in a gzipped tar
|
||||
file with the name @file{foo-69.96.tar.gz}. It should unpack into a
|
||||
@ -3327,6 +3505,7 @@ files} and @dfn{non-source files}. Source files are written by humans
|
||||
and never changed automatically; non-source files are produced from
|
||||
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
|
||||
@ -3385,6 +3564,7 @@ characters both before and after the period. Thus,
|
||||
are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
|
||||
distinct.
|
||||
|
||||
@cindex @file{texinfo.tex}, in a distribution
|
||||
Include in your distribution a copy of the @file{texinfo.tex} you used
|
||||
to test print any @file{*.texinfo} or @file{*.texi} files.
|
||||
|
||||
@ -3396,6 +3576,7 @@ other files to get.
|
||||
|
||||
@node References
|
||||
@chapter References to Non-Free Software and Documentation
|
||||
@cindex references to non-free material
|
||||
|
||||
A GNU program should not recommend use of any non-free program. We
|
||||
can't stop some people from writing proprietary programs, or stop other
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
% Load plain if necessary, i.e., if running under initex.
|
||||
\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
|
||||
%
|
||||
\def\texinfoversion{2000-05-28.15}
|
||||
\def\texinfoversion{2000-09-06.09}
|
||||
%
|
||||
% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99
|
||||
% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 2000
|
||||
% Free Software Foundation, Inc.
|
||||
%
|
||||
% This texinfo.tex file is free software; you can redistribute it and/or
|
||||
@ -3155,7 +3155,6 @@ width0pt\relax} \fi
|
||||
%
|
||||
% Double the \vsize as well. (We don't need a separate register here,
|
||||
% since nobody clobbers \vsize.)
|
||||
\advance\vsize by -\ht\partialpage
|
||||
\vsize = 2\vsize
|
||||
}
|
||||
|
||||
@ -3169,6 +3168,7 @@ width0pt\relax} \fi
|
||||
% previous page.
|
||||
\dimen@ = \vsize
|
||||
\divide\dimen@ by 2
|
||||
\advance\dimen@ by -\ht\partialpage
|
||||
%
|
||||
% box0 will be the left-hand column, box2 the right.
|
||||
\setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
|
||||
@ -3176,15 +3176,18 @@ width0pt\relax} \fi
|
||||
\unvbox255
|
||||
\penalty\outputpenalty
|
||||
}
|
||||
%
|
||||
% Re-output the contents of the output page -- any previous material,
|
||||
% followed by the two boxes we just split, in box0 and box2.
|
||||
\def\pagesofar{%
|
||||
% Re-output the contents of the output page -- any previous material,
|
||||
% followed by the two boxes we just split, in box0 and box2.
|
||||
\unvbox\partialpage
|
||||
%
|
||||
\hsize = \doublecolumnhsize
|
||||
\wd0=\hsize \wd2=\hsize
|
||||
\hbox to\pagewidth{\box0\hfil\box2}%
|
||||
}
|
||||
%
|
||||
% All done with double columns.
|
||||
\def\enddoublecolumns{%
|
||||
\output = {%
|
||||
% Split the last of the double-column material. Leave it on the
|
||||
@ -3209,8 +3212,9 @@ width0pt\relax} \fi
|
||||
% \endgroup where \vsize got restored).
|
||||
\pagegoal = \vsize
|
||||
}
|
||||
%
|
||||
% Called at the end of the double column material.
|
||||
\def\balancecolumns{%
|
||||
% Called at the end of the double column material.
|
||||
\setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
|
||||
\dimen@ = \ht0
|
||||
\advance\dimen@ by \topskip
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user