This file contains unidiffs between version 2.7 and 2.9 of GNU Autoconf. Changes in files produced by Makeinfo and TeX have been omitted. You will need GNU patch to apply these patches. diff -ruN autoconf-2.7/ChangeLog autoconf-2.9/ChangeLog --- autoconf-2.7/ChangeLog Wed Nov 22 12:35:33 1995 +++ autoconf-2.9/ChangeLog Sat Mar 16 15:54:07 1996 @@ -1,3 +1,93 @@ +Sat Mar 16 15:53:22 1996 Roland McGrath + + * Version 2.9 released. + * acgeneral.m4 (AC_ACVERSION): Updated to 2.9. + +Wed Mar 13 12:49:51 1996 Roland McGrath + + * acgeneral.m4 (AC_OUTPUT_HEADER): Undo last change to $ac_dB, + and instead change the code written into conftest.hdr. + +Tue Mar 12 02:51:24 1996 Roland McGrath + + * acgeneral.m4 (AC_OUTPUT_HEADER): Apply Jan 15 fix to + AC_OUTPUT_MAKE_DEFS here too: Match `#define foo' without trailing + space in confdefs.h. Before configure would lose if all its trailing + whitespace got stripped, and that can happen in mail. + +Sun Mar 10 20:30:09 1996 Roland McGrath + + * acgeneral.m4 (AC_INIT_NOTICE): Add 95 and 96 to copyright years. + +Sat Mar 9 18:28:42 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Add missing [. + +Fri Mar 8 15:06:48 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Declare $2 to override gcc2 internal + prototype. + + * Version 2.8 released. + +Wed Mar 6 14:38:31 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Use a cache variable name containing + both the library and function name. + +Tue Jan 16 16:39:21 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_PROG): Take optional 6th arg, full name + of program to reject if found in search path. + * acspecific.m4 (AC_PROG_CC): If gcc not found use AC_CHECK_PROG + for cc, rejecting /usr/ucb/cc. + Fatal configure error if no $CC found at all. + +Mon Jan 15 15:57:36 1996 Roland McGrath + + * acgeneral.m4 (AC_OUTPUT_MAKE_DEFS): Match `#define foo' without + trailing space in confdefs.h. Before configure would lose if + all its trailing whitespace got stripped, and that can happen in mail. + +Fri Jan 12 14:38:37 1996 Roland McGrath + + * acgeneral.m4 (AC_TRY_CPP): Use "" instead of '' when setting + ac_try; we need one level of expansion there for $ac_cpp, then + AC_TRY_EVAL does one more for its the expansion of $ac_cpp. + +Thu Jan 11 10:38:19 1996 Roland McGrath + + * acgeneral.m4 (AC_LANG_C, AC_LANG_CPLUSPLUS): Removed echo cmds + from $ac_cpp, $ac_compile, and $ac_link. + (AC_TRY_EVAL, AC_TRY_COMMAND): New macros for running tests' commands. + Always put the configure source line and command line into config.log. + (AC_TRY_CPP, AC_TRY_COMPILE, AC_TRY_LINK): Use them. + * acspecific.m4: Use AC_TRY_EVAL and AC_TRY_COMMAND for running + all tests. + +Fri Jan 5 17:50:28 1996 Roland McGrath + + * acspecific.m4 (AC_PATH_X, AC_PATH_X_XMKMF, AC_PATH_X_DIRECT): + Rearrange logic: do no tests if $with_x=no; make incl and lib + tests independent, and distinguish unset from empty. + + * autoconf.sh (undefined macro check): \ sed \s inside "". If + grep $name in $infile misses, give error message that there must + be an Autoconf bug. + +Tue Dec 19 10:49:20 1995 David J. MacKenzie + + * autoconf.sh: Ignore undefined macros in shell comments. + +Mon Dec 11 22:12:54 1995 Roland McGrath + + * acspecific.m4 (AC_PROG_CC_C_O): Rearrange logic to get the right + answer for cc. + +Fri Nov 24 17:26:38 1995 Miles Bader + + * autoconf.sh: Define $AWK from the subst @AWK@, and use it. + Wed Nov 22 11:01:16 1995 David J. MacKenzie * Version 2.7. diff -ruN autoconf-2.7/acgeneral.m4 autoconf-2.9/acgeneral.m4 --- autoconf-2.7/acgeneral.m4 Wed Nov 22 11:42:00 1995 +++ autoconf-2.9/acgeneral.m4 Sat Mar 16 15:53:07 1996 @@ -1,7 +1,7 @@ dnl Parameterized macros. dnl Requires GNU m4. dnl This file is part of Autoconf. -dnl Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +dnl Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. dnl dnl This program is free software; you can redistribute it and/or modify dnl it under the terms of the GNU General Public License as published by @@ -51,7 +51,7 @@ divert(-1)dnl Throw away output until AC_INIT is called. changequote([, ]) -define(AC_ACVERSION, 2.7) +define(AC_ACVERSION, 2.9) dnl Some old m4's don't support m4exit. But they provide dnl equivalent functionality by core dumping because of the @@ -143,7 +143,7 @@ AC_DEFUN(AC_INIT_NOTICE, [# Guess values for system-dependent variables and create Makefiles. # Generated automatically using autoconf version] AC_ACVERSION [ -# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. # # This configure script is free software; the Free Software Foundation # gives unlimited permission to copy, distribute and modify it. @@ -1158,12 +1158,9 @@ [define([AC_LANG], [C])dnl ac_ext=c # CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. -ac_cpp='echo $CPP $CPPFLAGS 1>&AC_FD_CC; -$CPP $CPPFLAGS' -ac_compile='echo ${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC; -${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC 2>&AC_FD_CC' -ac_link='echo ${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC; -${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC 2>&AC_FD_CC' +ac_cpp='$CPP $CPPFLAGS' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC' +ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC' ]) dnl AC_LANG_CPLUSPLUS() @@ -1171,12 +1168,9 @@ [define([AC_LANG], [CPLUSPLUS])dnl ac_ext=C # CXXFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. -ac_cpp='echo $CXXCPP $CPPFLAGS 1>&AC_FD_CC; -$CXXCPP $CPPFLAGS' -ac_compile='echo ${CXX-g++} -c $CXXFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC; -${CXX-g++} -c $CXXFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC 2>&AC_FD_CC' -ac_link='echo ${CXX-g++} -o conftest $CXXFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC; -${CXX-g++} -o conftest $CXXFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC 2>&AC_FD_CC' +ac_cpp='$CXXCPP $CPPFLAGS' +ac_compile='${CXX-g++} -c $CXXFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC' +ac_link='${CXX-g++} -o conftest $CXXFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC' ]) dnl Push the current language on a stack. @@ -1190,6 +1184,21 @@ [ifelse(AC_LANG_STACK, C, [ifelse(AC_LANG, C, , [AC_LANG_C])], [ifelse(AC_LANG, CPLUSPLUS, , [AC_LANG_CPLUSPLUS])])[]popdef([AC_LANG_STACK])]) +dnl ### Compiler-running mechanics + + +dnl The purpose of this macro is to "configure:123: command line" +dnl written into config.log for every test run. +dnl AC_TRY_EVAL(VARIABLE) +AC_DEFUN(AC_TRY_EVAL, +[{ (eval echo configure:__oline__: \"[$]$1\") 1>&AC_FD_CC; dnl +(eval [$]$1) 2>&AC_FD_CC; }]) + +dnl AC_TRY_COMMAND(COMMAND) +AC_DEFUN(AC_TRY_COMMAND, +[{ ac_try='$1'; AC_TRY_EVAL(ac_try); }]) + + dnl ### Dependencies between macros @@ -1220,7 +1229,7 @@ dnl AC_CHECK_PROG(VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND -dnl [, VALUE-IF-NOT-FOUND [, PATH]]) +dnl [, [VALUE-IF-NOT-FOUND] [, [PATH] [, [REJECT]]]]) AC_DEFUN(AC_CHECK_PROG, [# Extract the first word of "$2", so it can be a program name with args. set dummy $2; ac_word=[$]2 @@ -1230,14 +1239,43 @@ ac_cv_prog_$1="[$]$1" # Let the user override the test. else IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" +ifelse([$6], , , [ ac_prog_rejected=no +])dnl for ac_dir in ifelse([$5], , $PATH, [$5]); do test -z "$ac_dir" && ac_dir=. if test -f $ac_dir/$ac_word; then +ifelse([$6], , , dnl +[ if test "[$ac_dir/$ac_word]" = "$6"; then + ac_prog_rejected=yes + continue + fi +])dnl ac_cv_prog_$1="$3" break fi done IFS="$ac_save_ifs" +ifelse([$6], , , [if test $ac_prog_rejected = yes; then + # We found a bogon in the path, so make sure we never use it. + set dummy [$]ac_cv_prog_$1 + shift + if test [$]# -gt 0; then + # We chose a different compiler from the bogus one. + # However, it has the same basename, so the bogon will be chosen + # first if we set $1 to just the basename; use the full file name. + shift + set dummy "$ac_dir/$ac_word" "[$]@" + shift + ac_cv_prog_$1="[$]@" +ifelse([$2], [$4], dnl +[ else + # Default is a loser. + AC_MSG_ERROR([$1=$6 unacceptable, but no other $4 found in dnl +ifelse([$5], , [\$]PATH, [$5])]) +])dnl + fi +fi +])dnl dnl If no 4th arg is given, leave the cache variable unset, dnl so AC_CHECK_PROGS will keep looking. ifelse([$4], , , [ test -z "[$]ac_cv_prog_$1" && ac_cv_prog_$1="$4" @@ -1366,14 +1404,24 @@ dnl [, OTHER-LIBRARIES]]]) AC_DEFUN(AC_CHECK_LIB, [AC_MSG_CHECKING([for -l$1]) -changequote(, )dnl -ac_lib_var=`echo $1 | tr '.-/+' '___p'` -changequote([, ])dnl +dnl Use a cache variable name containing both the library and function name, +dnl because the test really is for library $1 defining function $2, not +dnl just for library $1. Separate tests with the same $1 and different $2s +dnl may have different results. +ac_lib_var=`echo $1[_]$2 | tr '.-/+' '___p'` AC_CACHE_VAL(ac_cv_lib_$ac_lib_var, [ac_save_LIBS="$LIBS" LIBS="-l$1 $5 $LIBS" -AC_TRY_LINK(, [$2()], eval "ac_cv_lib_$ac_lib_var=yes", - eval "ac_cv_lib_$ac_lib_var=no")dnl +AC_TRY_LINK([/* Override any gcc2 internal prototype to avoid an error. */ +]ifelse(AC_LANG, CPLUSPLUS, [#ifdef __cplusplus +extern "C" +#endif +])dnl +[char $2(); +], + [$2()], + eval "ac_cv_lib_$ac_lib_var=yes", + eval "ac_cv_lib_$ac_lib_var=no")dnl LIBS="$ac_save_LIBS" ])dnl if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes"; then @@ -1438,7 +1486,8 @@ dnl We used to copy stderr to stdout and capture it in a variable, but dnl that breaks under sh -x, which writes compile commands starting dnl with ` +' to stderr in eval and subshells. -eval "$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" +ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" +AC_TRY_EVAL(ac_try) ac_err=`grep -v '^ *+' conftest.out` if test -z "$ac_err"; then ifelse([$2], , :, [rm -rf conftest* @@ -1499,7 +1548,7 @@ [$2] ; return 0; } EOF -if eval $ac_compile; then +if AC_TRY_EVAL(ac_compile); then ifelse([$3], , :, [rm -rf conftest* $3]) ifelse([$4], , , [else @@ -1537,7 +1586,7 @@ [$2] ; return 0; } EOF -if eval $ac_link; then +if AC_TRY_EVAL(ac_link); then ifelse([$3], , :, [rm -rf conftest* $3]) ifelse([$4], , , [else @@ -1572,7 +1621,7 @@ ])dnl [$1] EOF -eval $ac_link +AC_TRY_EVAL(ac_link) if test -s conftest && (./conftest; exit) 2>/dev/null; then ifelse([$2], , :, [$2]) ifelse([$3], , , [else @@ -1850,7 +1899,7 @@ # Protect against Makefile macro expansion. cat > conftest.defs <<\EOF changequote(<<, >>)dnl -s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) \(.*\)%-D\1=\2%g +s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g s%[ `~<<#>>$^&*(){}\\|;'"<>?]%\\&%g s%\[%\\&%g s%\]%\\&%g @@ -2009,7 +2058,7 @@ changequote(<<, >>)dnl s/[\\&%]/\\&/g s%[\\$`]%\\&%g -s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) \(.*\)%${ac_dA}\1${ac_dB}\1${ac_dC}\2${ac_dD}%gp +s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%${ac_dA}\1${ac_dB}\1${ac_dC}\2${ac_dD}%gp s%ac_d%ac_u%gp s%ac_u%ac_e%gp changequote([, ])dnl diff -ruN autoconf-2.7/acspecific.m4 autoconf-2.9/acspecific.m4 --- autoconf-2.7/acspecific.m4 Wed Nov 22 11:58:04 1995 +++ autoconf-2.9/acspecific.m4 Sun Mar 10 20:30:51 1996 @@ -1,6 +1,6 @@ dnl Macros that test for specific features. dnl This file is part of Autoconf. -dnl Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +dnl Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. dnl dnl This program is free software; you can redistribute it and/or modify dnl it under the terms of the GNU General Public License as published by @@ -71,7 +71,11 @@ AC_DEFUN(AC_PROG_CC, [AC_BEFORE([$0], [AC_PROG_CPP])dnl -AC_CHECK_PROG(CC, gcc, gcc, cc) +AC_CHECK_PROG(CC, gcc, gcc) +if test -z "$CC"; then + AC_CHECK_PROG(CC, cc, cc, , , /usr/ucb/cc) + test -z "$CC" && AC_MSG_ERROR([no acceptable cc found in \$PATH]) +fi AC_CACHE_CHECK(whether we are using GNU C, ac_cv_prog_gcc, [dnl The semicolon is to pacify NeXT's syntax-checking cpp. @@ -80,7 +84,7 @@ yes; #endif EOF -if ${CC-cc} -E conftest.c 2>&AC_FD_CC | egrep yes >/dev/null 2>&1; then +if AC_TRY_COMMAND(${CC-cc} -E conftest.c) | egrep yes >/dev/null 2>&1; then ac_cv_prog_gcc=yes else ac_cv_prog_gcc=no @@ -120,7 +124,7 @@ yes; #endif EOF -if ${CXX-g++} -E conftest.C 2>&AC_FD_CC | egrep yes >/dev/null 2>&1; then +if AC_TRY_COMMAND(${CXX-g++} -E conftest.C) | egrep yes >/dev/null 2>&1; then ac_cv_prog_gxx=yes else ac_cv_prog_gxx=no @@ -178,33 +182,37 @@ else AC_MSG_CHECKING(whether cc understands -c and -o together) fi -set dummy $CC; ac_cc="`echo [$]2 | +set dummy $CC; ac_cc="`echo [$]2 | changequote(, )dnl sed -e 's/[^a-zA-Z0-9_]/_/g' -e 's/^[0-9]/_/'`" changequote([, ])dnl AC_CACHE_VAL(ac_cv_prog_cc_${ac_cc}_c_o, -[eval ac_cv_prog_cc_${ac_cc}_c_o=no -echo 'foo(){}' > conftest.c +[echo 'foo(){}' > conftest.c # Make sure it works both with $CC and with simple cc. # We do the test twice because some compilers refuse to overwrite an # existing .o file with -o, though they will create one. -if ${CC-cc} -c conftest.c -o conftest.o 1>&AC_FD_CC 2>&AC_FD_CC && - test -f conftest.o && ${CC-cc} -c conftest.c -o conftest.o 1>&AC_FD_CC 2>&AC_FD_CC +ac_try='${CC-cc} -c conftest.c -o conftest.o 1>&AC_FD_CC' +if AC_TRY_EVAL(ac_try) && + test -f conftest.o && AC_TRY_EVAL(ac_try); then + eval ac_cv_prog_cc_${ac_cc}_c_o=yes if test "x$CC" != xcc; then # Test first that cc exists at all. - if cc -c conftest.c 1>&AC_FD_CC 2>&AC_FD_CC - then - if cc -c conftest.c -o conftest2.o 1>&AC_FD_CC 2>&AC_FD_CC && - test -f conftest2.o && cc -c conftest.c -o conftest2.o 1>&AC_FD_CC 2>&AC_FD_CC + if AC_TRY_COMMAND(cc -c conftest.c 1>&AC_FD_CC); then + ac_try='cc -c conftest.c -o conftest.o 1>&AC_FD_CC' + if AC_TRY_EVAL(ac_try) && + test -f conftest.o && AC_TRY_EVAL(ac_try); then - eval ac_cv_prog_cc_${ac_cc}_c_o=yes + # cc works too. + : + else + # cc exists but doesn't like -o. + eval ac_cv_prog_cc_${ac_cc}_c_o=no fi - else - # There is no cc, so we don't care about it. - eval ac_cv_prog_cc_${ac_cc}_c_o=yes fi fi +else + eval ac_cv_prog_cc_${ac_cc}_c_o=no fi rm -f conftest* ])dnl @@ -405,7 +413,7 @@ fi fi dnl We do special magic for INSTALL instead of AC_SUBST, to get -dnl relative paths right. +dnl relative paths right. AC_MSG_RESULT($INSTALL) # Use test -z because SunOS4 sh mishandles braces in ${var-val}. @@ -504,7 +512,7 @@ ]) AC_DEFUN(AC_HEADER_MAJOR, -[AC_CACHE_CHECK(whether sys/types.h defines makedev, +[AC_CACHE_CHECK(whether sys/types.h defines makedev, ac_cv_header_sys_types_h_makedev, [AC_TRY_LINK([#include ], [return makedev(0, 0);], ac_cv_header_sys_types_h_makedev=yes, ac_cv_header_sys_types_h_makedev=no) @@ -1641,40 +1649,48 @@ AC_MSG_CHECKING(for X) AC_ARG_WITH(x, [ --with-x use the X Window System]) +# $have_x is `yes', `no', `disabled', or empty when we do not yet know. if test "x$with_x" = xno; then - no_x=yes + # The user explicitly disabled X. + have_x=disabled else if test "x$x_includes" != xNONE && test "x$x_libraries" != xNONE; then - no_x= + # Both variables are already set. + have_x=yes else -AC_CACHE_VAL(ac_cv_path_x, +AC_CACHE_VAL(ac_cv_have_x, [# One or both of the vars are not set, and there is no cached value. -no_x=yes +ac_x_includes=NO ac_x_libraries=NO AC_PATH_X_XMKMF -if test "$no_x" = yes; then AC_PATH_X_DIRECT -fi -if test "$no_x" = yes; then - ac_cv_path_x="no_x=yes" -else - ac_cv_path_x="no_x= ac_x_includes=$ac_x_includes ac_x_libraries=$ac_x_libraries" +if test "$ac_x_includes" = NO || test "$ac_x_libraries" = NO; then + # Didn't find X anywhere. Cache the known absence of X. + ac_cv_have_x="have_x=no" +else + # Record where we found X for the cache. + ac_cv_have_x="have_x=yes \ + ac_x_includes=$ac_x_includes ac_x_libraries=$ac_x_libraries" fi])dnl fi - eval "$ac_cv_path_x" + eval "$ac_cv_have_x" fi # $with_x != no -if test "$no_x" = yes; then - AC_MSG_RESULT(no) +if test "$have_x" != yes; then + AC_MSG_RESULT($have_x) + no_x=yes else + # If each of the values was on the command line, it overrides each guess. test "x$x_includes" = xNONE && x_includes=$ac_x_includes test "x$x_libraries" = xNONE && x_libraries=$ac_x_libraries - ac_cv_path_x="no_x= ac_x_includes=$x_includes ac_x_libraries=$x_libraries" + # Update the cache value to reflect the command line values. + ac_cv_have_x="have_x=yes \ + ac_x_includes=$x_includes ac_x_libraries=$x_libraries" AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) fi ]) dnl Internal subroutine of AC_PATH_X. -dnl Set ac_x_includes, ac_x_libraries, and no_x (initially yes). +dnl Set ac_x_includes and/or ac_x_libraries. AC_DEFUN(AC_PATH_X_XMKMF, [rm -fr conftestdir if mkdir conftestdir; then @@ -1685,7 +1701,6 @@ @echo 'ac_im_incroot="${INCROOT}"; ac_im_usrlibdir="${USRLIBDIR}"; ac_im_libdir="${LIBDIR}"' EOF if (xmkmf) >/dev/null 2>/dev/null && test -f Makefile; then - no_x= # GNU make sometimes prints "make[1]: Entering...", which would confuse us. eval `${MAKE-make} acfindx 2>/dev/null | grep -v make` # Open Windows xmkmf reportedly sets LIBDIR instead of USRLIBDIR. @@ -1711,14 +1726,18 @@ ]) dnl Internal subroutine of AC_PATH_X. -dnl Set ac_x_includes, ac_x_libraries, and no_x (initially yes). +dnl Set ac_x_includes and/or ac_x_libraries. AC_DEFUN(AC_PATH_X_DIRECT, -[test -z "$x_direct_test_library" && x_direct_test_library=Xt -test -z "$x_direct_test_function" && x_direct_test_function=XtMalloc -test -z "$x_direct_test_include" && x_direct_test_include=X11/Intrinsic.h +[if test "$ac_x_includes" = NO; then + # Guess where to find include files, by looking for this one X11 .h file. + test -z "$x_direct_test_include" && x_direct_test_include=X11/Intrinsic.h + + # First, try using that file with no special directory specified. AC_TRY_CPP([#include <$x_direct_test_include>], -[no_x= ac_x_includes=], -[ for ac_dir in \ +[# We can compile using X headers with no special include directory. +ac_x_includes=], +[# Look for the header file in a standard set of common directories. + for ac_dir in \ /usr/X11R6/include \ /usr/X11R5/include \ /usr/X11R4/include \ @@ -1756,18 +1775,26 @@ ; \ do if test -r "$ac_dir/$x_direct_test_include"; then - no_x= ac_x_includes=$ac_dir + ac_x_includes=$ac_dir break fi done]) +fi # $ac_x_includes = NO -# Check for the libraries. -# See if we find them without any special options. -# Don't add to $LIBS permanently. -ac_save_LIBS="$LIBS" -LIBS="-l$x_direct_test_library $LIBS" +if test "$ac_x_libraries" = NO; then + # Check for the libraries. + + test -z "$x_direct_test_library" && x_direct_test_library=Xt + test -z "$x_direct_test_function" && x_direct_test_function=XtMalloc + + # See if we find them without any special options. + # Don't add to $LIBS permanently. + ac_save_LIBS="$LIBS" + LIBS="-l$x_direct_test_library $LIBS" AC_TRY_LINK(, [${x_direct_test_function}()], -[LIBS="$ac_save_LIBS" no_x= ac_x_libraries=], +[LIBS="$ac_save_LIBS" +# We can link X programs with no special library path. +ac_x_libraries=], [LIBS="$ac_save_LIBS" # First see if replacing the include by lib works. for ac_dir in `echo "$ac_x_includes" | sed s/include/lib/` \ @@ -1807,19 +1834,22 @@ /usr/openwin/share/lib \ ; \ do +dnl XXX Shouldn't this really use AC_TRY_LINK to be portable & robust?? for ac_extension in a so sl; do if test -r $ac_dir/lib${x_direct_test_library}.$ac_extension; then - no_x= ac_x_libraries=$ac_dir + ac_x_libraries=$ac_dir break 2 fi done -done])]) +done]) +fi # $ac_x_libraries = NO +]) dnl Find additional X libraries, magic flags, etc. AC_DEFUN(AC_PATH_XTRA, [AC_REQUIRE([AC_ISC_POSIX])dnl AC_REQUIRE([AC_PATH_X])dnl -if test "$no_x" = yes; then +if test "$no_x" = yes; then # Not all programs may use this symbol, but it does not hurt to define it. X_CFLAGS="$X_CFLAGS -DX_DISPLAY_MISSING" else diff -ruN autoconf-2.7/autoconf.sh autoconf-2.9/autoconf.sh --- autoconf-2.7/autoconf.sh Mon Nov 20 15:35:21 1995 +++ autoconf-2.9/autoconf.sh Tue Jan 16 17:07:41 1996 @@ -1,6 +1,6 @@ #! /bin/sh # autoconf -- create `configure' using m4 macros -# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +# Copyright (C) 1992, 1993, 1994, 1996 Free Software Foundation, Inc. # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -21,8 +21,8 @@ # the given template file. usage="\ -Usage: autoconf [-h] [--help] [-m dir] [--macrodir=dir] - [-l dir] [--localdir=dir] [--version] [template-file]" +Usage: autoconf [-h] [--help] [-m dir] [--macrodir=dir] + [-l dir] [--localdir=dir] [--version] [template-file]" # NLS nuisances. # Only set `LANG' and `LC_ALL' to "C" if already set. @@ -33,6 +33,7 @@ : ${AC_MACRODIR=@datadir@} : ${M4=@M4@} +: ${AWK=@AWK@} case "${M4}" in /*) # Handle the case that m4 has moved since we were configured. # It may have been found originally in a build directory. @@ -45,7 +46,7 @@ show_version=no while test $# -gt 0 ; do - case "${1}" in + case "${1}" in -h | --help | --h* ) echo "${usage}" 1>&2; exit 0 ;; --localdir=* | --l*=* ) @@ -59,7 +60,7 @@ --macrodir=* | --m*=* ) AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" shift ;; - -m | --macrodir | --m* ) + -m | --macrodir | --m* ) shift test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } AC_MACRODIR="${1}" @@ -125,11 +126,12 @@ pattern="AC_" status=0 -if grep "${pattern}" $tmpout > /dev/null 2>&1; then +if grep "^[^#]*${pattern}" $tmpout > /dev/null 2>&1; then echo "autoconf: Undefined macros:" >&2 - grep "${pattern}" $tmpout | sed "s/.*\(${pattern}[_A-Za-z0-9]*\).*/\1/" | - while read name; do - grep -n $name $infile /dev/null + sed -n "s/^[^#]*\\(${pattern}[_A-Za-z0-9]*\\).*/\\1/p" $tmpout | + while read macro; do + grep -n "^[^#]*$macro" $infile /dev/null + test $? -eq 1 && echo >&2 "***BUG in Autoconf--please report*** $macro" done | sort -u >&2 status=1 fi @@ -141,11 +143,11 @@ fi # Put the real line numbers into configure to make config.log more helpful. -awk ' +$AWK ' /__oline__/ { printf "%d:", NR + 1 } { print } ' $tmpout | sed ' -/__oline__/s/^\([0-9][0-9]*\):\(.*\)__oline__\(.*\)$/\2\1\3/ +/__oline__/s/^\([0-9][0-9]*\):\(.*\)__oline__/\2\1/ ' >&4 rm -f $tmpout diff -ruN autoconf-2.7/autoconf.texi autoconf-2.9/autoconf.texi --- autoconf-2.7/autoconf.texi Wed Nov 22 12:32:39 1995 +++ autoconf-2.9/autoconf.texi Fri Mar 8 15:04:47 1996 @@ -6,9 +6,9 @@ @c @setchapternewpage odd @c %**end of header -@set EDITION 2.7 -@set VERSION 2.7 -@set UPDATED November 1995 +@set EDITION 2.8 +@set VERSION 2.8 +@set UPDATED January 1996 @iftex @finalout @@ -27,7 +27,7 @@ configure source code packages using templates and an @code{m4} macro package. -Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -61,7 +61,7 @@ @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +Copyright @copyright{} 1992, '93, '94, '95, '96 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -1655,12 +1655,16 @@ $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) @end example -@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) +@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found} @r{[}, @var{path}, @r{[} @var{reject} @r{]]]}) @maindex CHECK_PROG Check whether program @var{prog-to-check-for} exists in @code{PATH}. If it is found, set @var{variable} to @var{value-if-found}, otherwise to -@var{value-if-not-found}, if given. If @var{variable} was already set, -do nothing. Calls @code{AC_SUBST} for @var{variable}. +@var{value-if-not-found}, if given. Always pass over @var{reject} (an +absolute file name) even if it is the first found in the search path; in +that case, set @var{variable} using the absolute file name of the +@var{prog-to-check-for} found that is not @var{reject}. If +@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for +@var{variable}. @end defmac @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) @@ -2749,7 +2753,7 @@ preprocessors. @end defmac -Here is now to find out whether a header file contains a particular +Here is how to find out whether a header file contains a particular declaration, such as a typedef, a structure, a structure member, or a function. Use @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the header file; on some systems the symbol might be defined diff -ruN autoconf-2.7/config.guess autoconf-2.9/config.guess --- autoconf-2.7/config.guess Wed Oct 25 18:49:51 1995 +++ autoconf-2.9/config.guess Sat Mar 16 15:54:24 1996 @@ -1,6 +1,6 @@ #! /bin/sh # Attempt to guess a canonical system name. -# Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +# Copyright (C) 1992, 93, 94, 95, 1996 Free Software Foundation, Inc. # # 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 @@ -51,9 +51,10 @@ # Note: order is significant - the case branches are not exclusive. case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in - alpha:OSF1:V*:*) + alpha:OSF1:[VX]*:*) # After 1.2, OSF1 uses "V1.3" for uname -r. - echo alpha-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^V//'` + # After 4.x, OSF1 uses "X4.x" for uname -r. + echo alpha-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^[VX]//'` exit 0 ;; alpha:OSF1:*:*) # 1.2 uses "1.2" for uname -r. @@ -62,6 +63,9 @@ 21064:Windows_NT:50:3) echo alpha-dec-winnt3.5 exit 0 ;; + Amiga*:UNIX_System_V:4.0:*) + echo m68k-cbm-sysv4 + exit 0;; amiga:NetBSD:*:*) echo m68k-cbm-netbsd${UNAME_RELEASE} exit 0 ;; @@ -120,6 +124,9 @@ mips:*:5*:RISCos) echo mips-mips-riscos${UNAME_RELEASE} exit 0 ;; + Night_Hawk:Power_UNIX:*:*) + echo powerpc-harris-powerunix + exit 0 ;; m88k:CX/UX:7*:*) echo m88k-harris-cxux7 exit 0 ;; @@ -130,12 +137,17 @@ echo m88k-motorola-sysv3 exit 0 ;; AViiON:dgux:*:*) + # DG/UX returns AViiON for all architectures + UNAME_PROCESSOR=`uname -p` + if [ $UNAME_PROCESSOR = mc88100 -o $UNAME_PROCESSOR = mc88100 ] ; then if [ ${TARGET_BINARY_INTERFACE}x = m88kdguxelfx \ -o ${TARGET_BINARY_INTERFACE}x = x ] ; then echo m88k-dg-dgux${UNAME_RELEASE} else echo m88k-dg-dguxbcs${UNAME_RELEASE} fi + else echo i586-dg-dgux${UNAME_RELEASE} + fi exit 0 ;; M88*:DolphinOS:*:*) # DolphinOS (SVR3) echo m88k-dolphin-sysv3 @@ -219,7 +231,7 @@ case "${UNAME_MACHINE}" in 9000/31? ) HP_ARCH=m68000 ;; 9000/[34]?? ) HP_ARCH=m68k ;; - 9000/7?? | 9000/8?[79] ) HP_ARCH=hppa1.1 ;; + 9000/7?? | 9000/8?[679] ) HP_ARCH=hppa1.1 ;; 9000/8?? ) HP_ARCH=hppa1.0 ;; esac HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'` @@ -312,6 +324,12 @@ *:NetBSD:*:*) echo ${UNAME_MACHINE}-unknown-netbsd`echo ${UNAME_RELEASE}|sed -e 's/[-_].*/\./'` exit 0 ;; + i*:CYGWIN*:*) + echo i386-unknown-cygwin32 + exit 0 ;; + p*:CYGWIN*:*) + echo powerpcle-unknown-cygwin32 + exit 0 ;; *:GNU:*:*) echo `echo ${UNAME_MACHINE}|sed -e 's,/.*$,,'`-unknown-gnu`echo ${UNAME_RELEASE}|sed -e 's,/.*$,,'` exit 0 ;; @@ -319,12 +337,16 @@ # The BFD linker knows what the default object file format is, so # first see if it will tell us. ld_help_string=`ld --help 2>&1` - if echo $ld_help_string | grep >/dev/null 2>&1 "supported emulations: elf_i[345]86"; then + if echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: elf_i[345]86"; then echo "${UNAME_MACHINE}-unknown-linux" ; exit 0 - elif echo $ld_help_string | grep >/dev/null 2>&1 "supported emulations: i[345]86linux"; then + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: i[345]86linux"; then echo "${UNAME_MACHINE}-unknown-linuxaout" ; exit 0 - elif echo $ld_help_string | grep >/dev/null 2>&1 "supported emulations: i[345]86coff"; then + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: i[345]86coff"; then echo "${UNAME_MACHINE}-unknown-linuxcoff" ; exit 0 + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: m68kelf"; then + echo "${UNAME_MACHINE}-unknown-linux" ; exit 0 + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: m68klinux"; then + echo "${UNAME_MACHINE}-unknown-linuxaout" ; exit 0 elif test "${UNAME_MACHINE}" = "alpha" ; then echo alpha-unknown-linux ; exit 0 else @@ -368,6 +390,8 @@ elif /bin/uname -X 2>/dev/null >/dev/null ; then UNAME_REL=`(/bin/uname -X|egrep Release|sed -e 's/.*= //')` (/bin/uname -X|egrep i80486 >/dev/null) && UNAME_MACHINE=i486 + (/bin/uname -X|egrep '^Machine.*Pentium' >/dev/null) \ + && UNAME_MACHINE=i586 echo ${UNAME_MACHINE}-unknown-sco$UNAME_REL else echo ${UNAME_MACHINE}-unknown-sysv32 @@ -424,6 +448,16 @@ echo ns32k-sni-sysv fi exit 0 ;; + mc68*:A/UX:*:*) + echo m68k-apple-aux${UNAME_RELEASE} + exit 0 ;; + R3000:*System_V*:*:*) + if [ -d /usr/nec ]; then + echo mips-nec-sysv${UNAME_RELEASE} + else + echo mips-unknown-sysv${UNAME_RELEASE} + fi + exit 0 ;; esac #echo '(No uname command or uname output not recognized.)' 1>&2 diff -ruN autoconf-2.7/configure autoconf-2.9/configure --- autoconf-2.7/configure Wed Nov 22 12:46:05 1995 +++ autoconf-2.9/configure Sat Mar 16 15:54:42 1996 @@ -1,8 +1,8 @@ #! /bin/sh # Guess values for system-dependent variables and create Makefiles. -# Generated automatically using autoconf version 2.7 -# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +# Generated automatically using autoconf version 2.9 +# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. # # This configure script is free software; the Free Software Foundation # gives unlimited permission to copy, distribute and modify it. @@ -330,7 +330,7 @@ verbose=yes ;; -version | --version | --versio | --versi | --vers) - echo "configure generated by autoconf version 2.7" + echo "configure generated by autoconf version 2.9" exit 0 ;; -with-* | --with-*) @@ -495,12 +495,9 @@ ac_ext=c # CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. -ac_cpp='echo $CPP $CPPFLAGS 1>&5; -$CPP $CPPFLAGS' -ac_compile='echo ${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5; -${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5 2>&5' -ac_link='echo ${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5; -${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5 2>&5' +ac_cpp='$CPP $CPPFLAGS' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' +ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. @@ -779,7 +776,7 @@ # Protect against shell expansion while executing Makefile rules. # Protect against Makefile macro expansion. cat > conftest.defs <<\EOF -s%#define \([A-Za-z_][A-Za-z0-9_]*\) \(.*\)%-D\1=\2%g +s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g s%\[%\\&%g s%\]%\\&%g @@ -814,7 +811,7 @@ echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; -version | --version | --versio | --versi | --vers | --ver | --ve | --v) - echo "$CONFIG_STATUS generated by autoconf version 2.7" + echo "$CONFIG_STATUS generated by autoconf version 2.9" exit 0 ;; -help | --help | --hel | --he | --h) echo "\$ac_cs_usage"; exit 0 ;; diff -ruN autoconf-2.7/install-sh autoconf-2.9/install-sh --- autoconf-2.7/install-sh Thu Jun 22 23:26:53 1995 +++ autoconf-2.9/install-sh Fri Jan 5 17:38:32 1996 @@ -29,7 +29,7 @@ rmprog="${RMPROG-rm}" mkdirprog="${MKDIRPROG-mkdir}" -tranformbasename="" +transformbasename="" transform_arg="" instcmd="$mvprog" chmodcmd="$chmodprog 0755" diff -ruN autoconf-2.7/make-stds.texi autoconf-2.9/make-stds.texi --- autoconf-2.7/make-stds.texi Sat Sep 2 19:01:55 1995 +++ autoconf-2.9/make-stds.texi Fri Mar 8 15:04:49 1996 @@ -8,14 +8,26 @@ @cindex conventions for makefiles @cindex standards for makefiles -This chapter describes conventions for writing the Makefiles for GNU programs. +This +@ifinfo +node +@end ifinfo +@iftex +@ifset CODESTD +section +@end ifset +@ifclear CODESTD +chapter +@end ifclear +@end iftex +describes conventions for writing the Makefiles for GNU programs. @menu -* Makefile Basics:: -* Utilities in Makefiles:: -* Standard Targets:: -* Command Variables:: -* Directory Variables:: +* Makefile Basics:: General Conventions for Makefiles +* Utilities in Makefiles:: Utilities in Makefiles +* Command Variables:: Variables for Specifying Commands +* Directory Variables:: Variables for Installation Directories +* Standard Targets:: Standard Targets for Users @end menu @node Makefile Basics @@ -51,7 +63,7 @@ make, please make sure that it uses @file{./} if the program is built as part of the make or @file{$(srcdir)/} if the file is an unchanging part of the source code. Without one of these prefixes, the current search -path is used. +path is used. The distinction between @file{./} and @file{$(srcdir)/} is important when using the @samp{--srcdir} option to @file{configure}. A rule of @@ -69,9 +81,9 @@ When using GNU @code{make}, relying on @samp{VPATH} to find the source file will work in the case where there is a single dependency file, -since the @file{make} automatic variable @samp{$<} will represent the +since the @code{make} automatic variable @samp{$<} will represent the source file wherever it is. (Many versions of @code{make} set @samp{$<} -only in implicit rules.) A makefile target like +only in implicit rules.) A Makefile target like @smallexample foo.o : bar.c @@ -97,6 +109,9 @@ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ @end smallexample +Try to make the build and installation targets, at least (and all their +subtargets) work correctly with a parallel @code{make}. + @node Utilities in Makefiles @section Utilities in Makefiles @@ -108,8 +123,8 @@ installation should not use any utilities directly except these: @example -cat cmp cp echo egrep expr grep -ln mkdir mv pwd rm rmdir sed test touch +cat cmp cp echo egrep expr false grep +ln mkdir mv pwd rm rmdir sed test touch true @end example Stick to the generally supported options for these programs. For @@ -137,226 +152,15 @@ the system does not have @code{ranlib}. Arrange to ignore an error from that command, and print a message before the command to tell the user that failure of the @code{ranlib} command does not mean a problem. +(The Autoconf @samp{AC_PROG_RANLIB} macro can help with this.) If you use symbolic links, you should implement a fallback for systems that don't have symbolic links. It is ok to use other utilities in Makefile portions (or scripts) -intended only for particular systems where you know those utilities to +intended only for particular systems where you know those utilities exist. -@node Standard Targets -@section Standard Targets for Users - -All GNU programs should have the following targets in their Makefiles: - -@table @samp -@item all -Compile the entire program. This should be the default target. This -target need not rebuild any documentation files; Info files should -normally be included in the distribution, and DVI files should be made -only when explicitly asked for. - -@item install -Compile the program and copy the executables, libraries, and so on to -the file names where they should reside for actual use. If there is a -simple test to verify that a program is properly installed, this target -should run that test. - -If possible, write the @code{install} target rule so that it does not -modify anything in the directory where the program was built, provided -@samp{make all} has just been done. This is convenient for building the -program under one user name and installing it under another. - -The commands should create all the directories in which files are to be -installed, if they don't already exist. This includes the directories -specified as the values of the variables @code{prefix} and -@code{exec_prefix}, as well as all subdirectories that are needed. -One way to do this is by means of an @code{installdirs} target -as described below. - -Use @samp{-} before any command for installing a man page, so that -@code{make} will ignore any errors. This is in case there are systems -that don't have the Unix man page documentation system installed. - -The way to install Info files is to copy them into @file{$(infodir)} -with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run -the @code{install-info} program if it is present. @code{install-info} -is a script that edits the Info @file{dir} file to add or update the -menu entry for the given Info file; it will be part of the Texinfo package. -Here is a sample rule to install an Info file: - -@comment This example has been carefully formatted for the Make manual. -@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. -@smallexample -$(infodir)/foo.info: foo.info -# There may be a newer info file in . than in srcdir. - -if test -f foo.info; then d=.; \ - else d=$(srcdir); fi; \ - $(INSTALL_DATA) $$d/foo.info $@@; \ -# Run install-info only if it exists. -# Use `if' instead of just prepending `-' to the -# line so we notice real errors from install-info. -# We use `$(SHELL) -c' because some shells do not -# fail gracefully when there is an unknown command. - if $(SHELL) -c 'install-info --version' \ - >/dev/null 2>&1; then \ - install-info --infodir=$(infodir) $$d/foo.info; \ - else true; fi -@end smallexample - -@item uninstall -Delete all the installed files that the @samp{install} target would -create (but not the noninstalled files such as @samp{make all} would -create). - -This rule should not modify the directories where compilation is done, -only the directories where files are installed. - -@comment The gratuitous blank line here is to make the table look better -@comment in the printed Make manual. Please leave it in. -@item clean - -Delete all files from the current directory that are normally created by -building the program. Don't delete the files that record the -configuration. Also preserve files that could be made by building, but -normally aren't because the distribution comes with them. - -Delete @file{.dvi} files here if they are not part of the distribution. - -@item distclean -Delete all files from the current directory that are created by -configuring or building the program. If you have unpacked the source -and built the program without creating any other files, @samp{make -distclean} should leave only the files that were in the distribution. - -@item mostlyclean -Like @samp{clean}, but may refrain from deleting a few files that people -normally don't want to recompile. For example, the @samp{mostlyclean} -target for GCC does not delete @file{libgcc.a}, because recompiling it -is rarely necessary and takes a lot of time. - -@item maintainer-clean -Delete almost everything from the current directory that can be -reconstructed with this Makefile. This typically includes everything -deleted by @code{distclean}, plus more: C source files produced by -Bison, tags tables, Info files, and so on. - -The reason we say ``almost everything'' is that running the command -@samp{make maintainer-clean} should not delete @file{configure} even if -it can be remade using a rule in the Makefile. More generally, -@samp{make maintainer-clean} should not delete anything that needs to -exist in order to run @file{configure} and then begin to build the -program. This is the only exception; @code{maintainer-clean} should -delete everything else that can be rebuilt. - -The @samp{maintainer-clean} is intended to be used by a maintainer of -the package, not by ordinary users. You may need special tools to -reconstruct some of the files that @samp{make maintainer-clean} deletes. -Since these files are normally included in the distribution, we don't -take care to make them easy to reconstruct. If you find you need to -unpack the full distribution again, don't blame us. - -To help make users aware of this, the commands for the special -@code{maintainer-clean} target should start with these two: - -@smallexample -@@echo "This command is intended for maintainers to use; it" -@@echo "deletes files that may require special tools to rebuild." -@end smallexample - -@item TAGS -Update a tags table for this program. - -@item info -Generate any Info files needed. The best way to write the rules is as -follows: - -@smallexample -info: foo.info - -foo.info: foo.texi chap1.texi chap2.texi - $(MAKEINFO) $(srcdir)/foo.texi -@end smallexample - -@noindent -You must define the variable @code{MAKEINFO} in the Makefile. It should -run the @code{makeinfo} program, which is part of the Texinfo -distribution. - -@item dvi -Generate DVI files for all TeXinfo documentation. -For example: - -@smallexample -dvi: foo.dvi - -foo.dvi: foo.texi chap1.texi chap2.texi - $(TEXI2DVI) $(srcdir)/foo.texi -@end smallexample - -@noindent -You must define the variable @code{TEXI2DVI} in the Makefile. It should -run the program @code{texi2dvi}, which is part of the Texinfo -distribution. Alternatively, write just the dependencies, and allow GNU -Make to provide the command. - -@item dist -Create a distribution tar file for this program. The tar file should be -set up so that the file names in the tar file start with a subdirectory -name which is the name of the package it is a distribution for. This -name can include the version number. - -For example, the distribution tar file of GCC version 1.40 unpacks into -a subdirectory named @file{gcc-1.40}. - -The easiest way to do this is to create a subdirectory appropriately -named, use @code{ln} or @code{cp} to install the proper files in it, and -then @code{tar} that subdirectory. - -The @code{dist} target should explicitly depend on all non-source files -that are in the distribution, to make sure they are up to date in the -distribution. -@xref{Releases, , Making Releases, standards, GNU Coding Standards}. - -@item check -Perform self-tests (if any). The user must build the program before -running the tests, but need not install the program; you should write -the self-tests so that they work when the program is built but not -installed. -@end table - -The following targets are suggested as conventional names, for programs -in which they are useful. - -@table @code -@item installcheck -Perform installation tests (if any). The user must build and install -the program before running the tests. You should not assume that -@file{$(bindir)} is in the search path. - -@item installdirs -It's useful to add a target named @samp{installdirs} to create the -directories where files are installed, and their parent directories. -There is a script called @file{mkinstalldirs} which is convenient for -this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs. -You can use a rule like this: - -@comment This has been carefully formatted to look decent in the Make manual. -@comment Please be sure not to make it extend any further to the right.--roland -@smallexample -# Make sure all installation directories (e.g. $(bindir)) -# actually exist by making them if necessary. -installdirs: mkinstalldirs - $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ - $(libdir) $(infodir) \ - $(mandir) -@end smallexample - -This rule should not modify the directories where compilation is done. -It should do nothing but create installation directories. -@end table - @node Command Variables @section Variables for Specifying Commands @@ -443,11 +247,13 @@ 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@@}.) @item 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)}. +(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) Generally, @code{$(exec_prefix)} is used for directories that contain machine-specific files (such as executables and subroutine libraries), @@ -461,18 +267,21 @@ 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 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 @file{$(exec_prefix)/sbin}. +(If you are using Autoconf, write it as @samp{@@sbindir@@}.) @item 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 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. +(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) @end table Data files used by the program during its execution are divided into @@ -491,18 +300,20 @@ @end itemize This makes for six different possibilities. However, we want to -discourage the use of architecture-dependent files, aside from of object +discourage the use of architecture-dependent files, aside from object files and libraries. It is much cleaner to make other data files architecture-independent, and it is generally not hard. -Therefore, here are the variables makefiles should use to specify +Therefore, here are the variables Makefiles should use to specify directories: @table @samp @item datadir The directory for installing read-only architecture independent data files. This should normally be @file{/usr/local/share}, but write it as -@file{$(prefix)/share}. As a special exception, see @file{$(infodir)} +@file{$(prefix)/share}. +(If you are using Autoconf, write it as @samp{@@datadir@@}.) +As a special exception, see @file{$(infodir)} and @file{$(includedir)} below. @item sysconfdir @@ -512,12 +323,13 @@ here. All the files in this directory should be ordinary ASCII text files. This directory should normally be @file{/usr/local/etc}, but write it as @file{$(prefix)/etc}. +(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) @c rewritten to avoid overfull hbox --tower Do not install executables @c here in this directory (they probably -belong in @file{$(libexecdir)} or @file{$(sbindir))}. Also do not +belong in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install files that are modified in the normal course of their use (programs whose purpose is to change the configuration of the system excluded). Those probably belong in @file{$(localstatedir)}. @@ -526,26 +338,30 @@ The directory for installing architecture-independent data files which the programs modify while they run. This should normally be @file{/usr/local/com}, but write it as @file{$(prefix)/com}. +(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) @item localstatedir The directory for installing data files which the programs modify while they run, and that pertain to one specific machine. Users should never need to modify files in this directory to configure the package's operation; put such configuration information in separate files that go -in @file{datadir} or @file{$(sysconfdir)}. @file{$(localstatedir)} +in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} should normally be @file{/usr/local/var}, but write it as @file{$(prefix)/var}. +(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) @item libdir The directory for object files and libraries of object code. Do not -install executables here, they probably belong in @file{$(libexecdir)} +install executables here, they probably ought to go in @file{$(libexecdir)} instead. The value of @code{libdir} should normally be @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. +(If you are using Autoconf, write it as @samp{@@libdir@@}.) @item infodir The directory for installing the Info files for this package. By default, it should be @file{/usr/local/info}, but it should be written as @file{$(prefix)/info}. +(If you are using Autoconf, write it as @samp{@@infodir@@}.) @item includedir @c rewritten to avoid overfull hbox --roland @@ -553,6 +369,7 @@ programs with the C @samp{#include} preprocessor directive. This should normally be @file{/usr/local/include}, but write it as @file{$(prefix)/include}. +(If you are using Autoconf, write it as @samp{@@includedir@@}.) Most compilers other than GCC do not look for header files in @file{/usr/local/include}. So installing the header files this way is @@ -565,6 +382,7 @@ @item oldincludedir The directory for installing @samp{#include} header files for use with compilers other than GCC. This should normally be @file{/usr/include}. +(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) The Makefile commands should check whether the value of @code{oldincludedir} is empty. If it is, they should not try to use @@ -578,7 +396,7 @@ package. To tell whether @file{foo.h} came from the Foo package, put a magic -string in the file---part of a comment---and grep for that string. +string in the file---part of a comment---and @code{grep} for that string. @end table Unix-style man pages are installed in one of the following: @@ -588,13 +406,14 @@ The top-level directory for installing the man pages (if any) for this package. It will normally be @file{/usr/local/man}, but you should write it as @file{$(prefix)/man}. +(If you are using Autoconf, write it as @samp{@@mandir@@}.) @item man1dir The directory for installing section 1 man pages. Write it as @file{$(mandir)/man1}. @item man2dir The directory for installing section 2 man pages. Write it as -@file{$(mandir)/man2}. +@file{$(mandir)/man2} @item @dots{} @strong{Don't make the primary documentation for any GNU software be a @@ -621,6 +440,7 @@ @item srcdir The directory for the sources being compiled. The value of this variable is normally inserted by the @code{configure} shell script. +(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) @end table For example: @@ -652,3 +472,248 @@ order for this to be useful, all the packages must be designed so that they will work sensibly when the user does so. +@node Standard Targets +@section Standard Targets for Users + +All GNU programs should have the following targets in their Makefiles: + +@table @samp +@item all +Compile the entire program. This should be the default target. This +target need not rebuild any documentation files; Info files should +normally be included in the distribution, and DVI files should be made +only when explicitly asked for. + +By default, the Make rules should compile and link with @samp{-g}, so +that executable programs have debugging symbols. Users who don't mind +being helpless can strip the executables later if they wish. + +@item install +Compile the program and copy the executables, libraries, and so on to +the file names where they should reside for actual use. If there is a +simple test to verify that a program is properly installed, this target +should run that test. + +Do not strip executables when installing them. Devil-may-care users can +use the @code{install-strip} target to do that. + +If possible, write the @code{install} target rule so that it does not +modify anything in the directory where the program was built, provided +@samp{make all} has just been done. This is convenient for building the +program under one user name and installing it under another. + +The commands should create all the directories in which files are to be +installed, if they don't already exist. This includes the directories +specified as the values of the variables @code{prefix} and +@code{exec_prefix}, as well as all subdirectories that are needed. +One way to do this is by means of an @code{installdirs} target +as described below. + +Use @samp{-} before any command for installing a man page, so that +@code{make} will ignore any errors. This is in case there are systems +that don't have the Unix man page documentation system installed. + +The way to install Info files is to copy them into @file{$(infodir)} +with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run +the @code{install-info} program if it is present. @code{install-info} +is a program that edits the Info @file{dir} file to add or update the +menu entry for the given Info file; it is part of the Texinfo package. +Here is a sample rule to install an Info file: + +@comment This example has been carefully formatted for the Make manual. +@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. +@smallexample +$(infodir)/foo.info: foo.info +# There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $@@; \ +# Run install-info only if it exists. +# Use `if' instead of just prepending `-' to the +# line so we notice real errors from install-info. +# We use `$(SHELL) -c' because some shells do not +# fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --dir-file=$(infodir)/dir \ + $(infodir)/foo.info; \ + else true; fi +@end smallexample + +@item uninstall +Delete all the installed files that the @samp{install} target would +create (but not the noninstalled files such as @samp{make all} would +create). + +This rule should not modify the directories where compilation is done, +only the directories where files are installed. + +@item install-strip +Like @code{install}, but strip the executable files while installing +them. The definition of this target can be very simple: + +@smallexample +install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install +@end smallexample + +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 +executable elsewhere in case there is a bug. + +@comment The gratuitous blank line here is to make the table look better +@comment in the printed Make manual. Please leave it in. +@item clean + +Delete all files from the current directory that are normally created by +building the program. Don't delete the files that record the +configuration. Also preserve files that could be made by building, but +normally aren't because the distribution comes with them. + +Delete @file{.dvi} files here if they are not part of the distribution. + +@item distclean +Delete all files from the current directory that are created by +configuring or building the program. If you have unpacked the source +and built the program without creating any other files, @samp{make +distclean} should leave only the files that were in the distribution. + +@item mostlyclean +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +target for GCC does not delete @file{libgcc.a}, because recompiling it +is rarely necessary and takes a lot of time. + +@item maintainer-clean +Delete almost everything from the current directory that can be +reconstructed with this Makefile. This typically includes everything +deleted by @code{distclean}, plus more: C source files produced by +Bison, tags tables, Info files, and so on. + +The reason we say ``almost everything'' is that running the command +@samp{make maintainer-clean} should not delete @file{configure} even if +@file{configure} can be remade using a rule in the Makefile. More generally, +@samp{make maintainer-clean} should not delete anything that needs to +exist in order to run @file{configure} and then begin to build the +program. This is the only exception; @code{maintainer-clean} should +delete everything else that can be rebuilt. + +The @samp{maintainer-clean} target is intended to be used by a maintainer of +the package, not by ordinary users. You may need special tools to +reconstruct some of the files that @samp{make maintainer-clean} deletes. +Since these files are normally included in the distribution, we don't +take care to make them easy to reconstruct. If you find you need to +unpack the full distribution again, don't blame us. + +To help make users aware of this, the commands for the special +@code{maintainer-clean} target should start with these two: + +@smallexample +@@echo 'This command is intended for maintainers to use; it' +@@echo 'deletes files that may need special tools to rebuild.' +@end smallexample + +@item TAGS +Update a tags table for this program. +@c ADR: how? + +@item info +Generate any Info files needed. The best way to write the rules is as +follows: + +@smallexample +info: foo.info + +foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. It should +run the @code{makeinfo} program, which is part of the Texinfo +distribution. + +@item dvi +Generate DVI files for all Texinfo documentation. +For example: + +@smallexample +dvi: foo.dvi + +foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{TEXI2DVI} in the Makefile. It should +run the program @code{texi2dvi}, which is part of the Texinfo +distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work +of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, +write just the dependencies, and allow GNU @code{make} to provide the command. + +@item dist +Create a distribution tar file for this program. The tar file should be +set up so that the file names in the tar file start with a subdirectory +name which is the name of the package it is a distribution for. This +name can include the version number. + +For example, the distribution tar file of GCC version 1.40 unpacks into +a subdirectory named @file{gcc-1.40}. + +The easiest way to do this is to create a subdirectory appropriately +named, use @code{ln} or @code{cp} to install the proper files in it, and +then @code{tar} that subdirectory. + +Compress the tar file file with @code{gzip}. For example, the actual +distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. + +The @code{dist} target should explicitly depend on all non-source files +that are in the distribution, to make sure they are up to date in the +distribution. +@ifset CODESTD +@xref{Releases, , Making Releases}. +@end ifset +@ifclear CODESTD +@xref{Releases, , Making Releases, standards, GNU Coding Standards}. +@end ifclear + +@item check +Perform self-tests (if any). The user must build the program before +running the tests, but need not install the program; you should write +the self-tests so that they work when the program is built but not +installed. +@end table + +The following targets are suggested as conventional names, for programs +in which they are useful. + +@table @code +@item installcheck +Perform installation tests (if any). The user must build and install +the program before running the tests. You should not assume that +@file{$(bindir)} is in the search path. + +@item installdirs +It's useful to add a target named @samp{installdirs} to create the +directories where files are installed, and their parent directories. +There is a script called @file{mkinstalldirs} which is convenient for +this; you can find it in the Texinfo package. +@c It's in /gd/gnu/lib/mkinstalldirs. +You can use a rule like this: + +@comment This has been carefully formatted to look decent in the Make manual. +@comment Please be sure not to make it extend any further to the right.--roland +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) +@end smallexample + +This rule should not modify the directories where compilation is done. +It should do nothing but create installation directories. +@end table diff -ruN autoconf-2.7/standards.texi autoconf-2.9/standards.texi --- autoconf-2.7/standards.texi Wed Jul 26 02:46:22 1995 +++ autoconf-2.9/standards.texi Wed Feb 28 04:21:15 1996 @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES! -@set lastupdate 24 July 1995 +@set lastupdate 27 February 1996 @c %**end of header @ifinfo @@ -14,11 +14,21 @@ @end format @end ifinfo +@c @setchapternewpage odd @setchapternewpage off +@c This is used by a cross ref in make-stds.texi +@set CODESTD 1 +@iftex +@set CHAPTER chapter +@end iftex +@ifinfo +@set CHAPTER node +@end ifinfo + @ifinfo GNU Coding Standards -Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -49,7 +59,7 @@ @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -75,26 +85,12 @@ @menu * Preface:: About the GNU Coding Standards -* Reading Non-Free Code:: Referring to Proprietary Programs -* Contributions:: Accepting Contributions -* Change Logs:: Recording Changes -* Compatibility:: Compatibility with Other Implementations -* Makefile Conventions:: Makefile Conventions -* Configuration:: How Configuration Should Work -* Source Language:: Using Languages Other Than C -* Formatting:: Formatting Your Source Code -* Comments:: Commenting Your Work -* Syntactic Conventions:: Clean Use of C Constructs -* Names:: Naming Variables, Functions and Files -* Using Extensions:: Using Non-standard Features -* System Functions:: Portability and ``standard'' library functions -* Semantics:: Program Behavior for All Programs -* Errors:: Formatting Error Messages -* Libraries:: Library Behavior -* Portability:: Portability As It Applies to GNU -* User Interfaces:: Standards for Command Line Interfaces +* Intellectual Property:: Keeping Free Software Free +* Design Advice:: General Program Design +* Program Behavior:: Program Behavior for All Programs +* Writing C:: Making The Best Use of C * Documentation:: Documenting Programs -* Releases:: Making Releases +* Managing Releases:: The Release Process @end menu @node Preface @@ -103,7 +99,7 @@ The GNU Coding Standards were written by Richard Stallman and other GNU Project volunteers. Their purpose is to make the GNU system clean, consistent, and easy to install. This document can also be read as a -guide to write portable, robust and reliable programs. It focuses on +guide to writing portable, robust and reliable programs. It focuses on programs written in C, but many of the rules and principles are useful even if you write in another programming language. The rules often state reasons for writing in a certain way. @@ -117,8 +113,19 @@ This release of the GNU Coding Standards was last updated @value{lastupdate}. +@node Intellectual Property +@chapter Keeping Free Software Free + +This @value{CHAPTER} discusses how you can make sure that GNU software +remains unencumbered. + +@menu +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions +@end menu + @node Reading Non-Free Code -@chapter Referring to Proprietary Programs +@section Referring to Proprietary Programs Don't in any circumstances refer to Unix source code for or during your work on GNU! (Or to any other proprietary programs.) @@ -152,7 +159,7 @@ @node Contributions -@chapter Accepting Contributions +@section Accepting Contributions If someone else sends you a piece of code to add to the program you are working on, we need legal papers to use it---the same sort of legal @@ -167,7 +174,7 @@ contribution. This applies both before you release the program and afterward. If -you receive diffs to fix a bug, and they make significant change, we +you receive diffs to fix a bug, and they make significant changes, we need legal papers for it. You don't need papers for changes of a few lines here or there, since @@ -176,7 +183,7 @@ which you use. For example, if you write a different solution to the problem, you don't need to get papers. -I know this is frustrating; it's frustrating for us as well. But if +We know this is frustrating; it's frustrating for us as well. But if you don't wait, you are going out on a limb---for example, what if the contributor's employer won't sign a disclaimer? You might have to take that code out again! @@ -185,102 +192,37 @@ contributor. We could be very embarrassed in court some day as a result. -@node Change Logs -@chapter Change Logs - -Keep a change log for each directory, describing the changes made to -source files in that directory. The purpose of this is so that people -investigating bugs in the future will know about the changes that -might have introduced the bug. Often a new bug can be found by -looking at what was recently changed. More importantly, change logs -can help eliminate conceptual inconsistencies between different parts -of a program; they can give you a history of how the conflicting -concepts arose. - -Use the Emacs command @kbd{M-x add-change-log-entry} to start a new -entry in the -change log. An entry should have an asterisk, the name of the changed -file, and then in parentheses the name of the changed functions, -variables or whatever, followed by a colon. Then describe the changes -you made to that function or variable. - -Separate unrelated entries with blank lines. When two entries -represent parts of the same change, so that they work together, then -don't put blank lines between them. Then you can omit the file name -and the asterisk when successive entries are in the same file. - -Here are some examples: - -@example -* register.el (insert-register): Return nil. -(jump-to-register): Likewise. - -* sort.el (sort-subr): Return nil. - -* tex-mode.el (tex-bibtex-file, tex-file, tex-region): -Restart the tex shell if process is gone or stopped. -(tex-shell-running): New function. - -* 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. -@end example - -It's important to name the changed function or variable in full. Don't -abbreviate them; don't combine them. Subsequent maintainers will often -search for a function name to find all the change log entries that -pertain to it; if you abbreviate the name, they won't find it when they -search. For example, some people are tempted to abbreviate groups of -function names by writing @samp{* register.el -(@{insert,jump-to@}-register)}; this is not a good idea, since searching -for @code{jump-to-register} or @code{insert-register} would not find the -entry. - -There's no need to describe the full purpose of the changes or how they -work together. It is better to put such explanations in comments in the -code. That's why just ``New function'' is enough; there is a comment -with the function in the source to explain what it does. - -However, sometimes it is useful to write one line to describe the -overall purpose of a large batch of changes. - -You can think of the change log as a conceptual ``undo list'' which -explains how earlier versions were different from the current version. -People can see the current version; they don't need the change log -to tell them what is in it. What they want from a change log is a -clear explanation of how the earlier version differed. - -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. Just write in -the entry for the function being called, ``All callers changed.'' +@node Design Advice +@chapter General Program Design -When you change just comments or doc strings, it is enough to write an -entry for the file, without mentioning the functions. Write just, -``Doc fix.'' There's no need to keep a change log for documentation -files. This is because documentation is not susceptible to bugs that -are hard to fix. Documentation does not consist of parts that must -interact in a precisely engineered fashion; to correct an error, you -need not know the history of the erroneous passage. +This @value{CHAPTER} discusses some of the issues you should take into +account when designing your program. +@menu +* Compatibility:: Compatibility with other implementations +* Using Extensions:: Using non-standard features +* ANSI C:: Using ANSI C features +* Source Language:: Using languages other than C +@end menu @node Compatibility -@chapter Compatibility with Other Implementations +@section Compatibility with Other Implementations -With certain exceptions, utility programs and libraries for GNU should -be upward compatible with those in Berkeley Unix, and upward compatible -with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward -compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior. +With occasional exceptions, utility programs and libraries for GNU +should be upward compatible with those in Berkeley Unix, and upward +compatible with @sc{ansi} C if @sc{ansi} 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. -@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel -free to make the extensions anyway, and include a @samp{--ansi} 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. Try to redesign its -interface. +@sc{ansi} 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. Try to +redesign its interface. Many GNU programs suppress extensions that conflict with POSIX if the environment variable @code{POSIXLY_CORRECT} is defined (even if it is @@ -290,2064 +232,2017 @@ When a feature is used only by users (not by programs or command files), and it is done poorly in Unix, feel free to replace it completely with something totally different and better. (For example, -vi is replaced with Emacs.) But it is nice to offer a compatible -feature as well. (There is a free vi clone, so we offer it.) +@code{vi} is replaced with Emacs.) But it is nice to offer a compatible +feature as well. (There is a free @code{vi} clone, so we offer it.) Additional useful features not in Berkeley Unix are welcome. Additional programs with no counterpart in Unix may be useful, but our first priority is usually to duplicate what Unix already has. -@comment The makefile standards are in a separate file that is also -@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. -@include make-stds.texi +@node Using Extensions +@section Using Non-standard Features -@node Configuration -@chapter How Configuration Should Work +Many GNU facilities that already exist support a number of convenient +extensions over the comparable Unix facilities. Whether to use these +extensions in implementing your program is a difficult question. -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. +On the one hand, using the extensions can make a cleaner program. +On the other hand, people will not be able to build the program +unless the other GNU tools are available. This might cause the +program to work on fewer kinds of machines. -The @code{configure} script must record the configuration options so -that they affect compilation. +With some extensions, it might be easy to provide both alternatives. +For example, you can define functions with a ``keyword'' @code{INLINE} +and define that as a macro to expand into either @code{inline} or +nothing, depending on the compiler. -One way to do this is to make a link from a standard name such as -@file{config.h} to the proper configuration file for the chosen system. -If you use this technique, the distribution should @emph{not} contain a -file named @file{config.h}. This is so that people won't be able to -build the program without configuring it first. +In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they +are a big improvement. -Another thing that @code{configure} can do is to edit the Makefile. If -you do this, the distribution should @emph{not} contain a file named -@file{Makefile}. Instead, include a file @file{Makefile.in} which -contains the input used for editing. Once again, this is so that people -won't be able to build the program without configuring it first. +An exception to this rule are the large, established programs (such as +Emacs) which run on a great variety of systems. Such programs would +be broken by use of GNU extensions. -If @code{configure} does write the @file{Makefile}, then @file{Makefile} -should have a target named @file{Makefile} which causes @code{configure} -to be rerun, setting up the same configuration that was set up last -time. The files that @code{configure} reads should be listed as -dependencies of @file{Makefile}. +Another exception is for programs that are used as part of +compilation: anything that must be compiled with other compilers in +order to bootstrap the GNU compilation facilities. If these require +the GNU compiler, then no one can compile them without having them +installed already. That would be no good. -All the files which are output from the @code{configure} script should -have comments at the beginning explaining that they were generated -automatically using @code{configure}. This is so that users won't think -of trying to edit them by hand. +@node ANSI C +@section @sc{ansi} C and pre-@sc{ansi} C -The @code{configure} script should write a file named @file{config.status} -which describes which configuration options were specified when the -program was last configured. This file should be a shell script which, -if run, will recreate the same configuration. +Do not ever use the ``trigraph'' feature of @sc{ansi} C. -The @code{configure} script should accept an option of the form -@samp{--srcdir=@var{dirname}} to specify the directory where sources are found -(if it is not the current directory). This makes it possible to build -the program in a separate directory, so that the actual source directory -is not modified. +@sc{ansi} C is widespread enough now that it is ok to write new programs +that use @sc{ansi} C features (and therefore will not work in +non-@sc{ansi} compilers). And if a program is already written in +@sc{ansi} C, there's no need to convert it to support non-@sc{ansi} +compilers. + +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, -If the user does not specify @samp{--srcdir}, then @code{configure} should -check both @file{.} and @file{..} to see if it can find the sources. If -it finds the sources in one of these places, it should use them from -there. Otherwise, it should report that it cannot find the sources, and -should exit with nonzero status. +@example +int +foo (int x, int y) +@dots{} +@end example -Usually the easy way to support @samp{--srcdir} is by editing a -definition of @code{VPATH} into the Makefile. Some rules may need to -refer explicitly to the specified source directory. To make this -possible, @code{configure} can add to the Makefile a variable named -@code{srcdir} whose value is precisely the specified directory. +@noindent +write the definition in pre-@sc{ansi} style like this, -The @code{configure} script should also take an argument which specifies the -type of system to build the program for. This argument should look like -this: +@example +int +foo (x, y) + int x, y; +@dots{} +@end example + +@noindent +and use a separate declaration to specify the argument prototype: @example -@var{cpu}-@var{company}-@var{system} +int foo (int, int); @end example -For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. +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. -The @code{configure} script needs to be able to decode all plausible -alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} -would be a valid alias. For many programs, @samp{vax-dec-ultrix} would -be an alias for @samp{vax-dec-bsd}, simply because the differences -between Ultrix and @sc{BSD} are rarely noticeable, but a few programs -might need to distinguish them. -@c Real 4.4BSD now runs on some Suns. +If you don't know non-@sc{ansi} C, there's no need to learn it; just +write in @sc{ansi} C. -There is a shell script called @file{config.sub} that you can use -as a subroutine to validate system types and canonicalize aliases. +@node Source Language +@section Using Languages Other Than C -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: +Using a language other than C is like using a non-standard feature: it +will cause trouble for users. Even if GCC supports the other language, +users may find it inconvenient to have to install the compiler for that +other language in order to build your program. So please write in C. -@table @samp -@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} -Configure the package to build and install an optional user-level -facility called @var{feature}. This allows users to choose which -optional features to include. Giving an optional @var{parameter} of -@samp{no} should omit @var{feature}, if it is built by default. +There are three exceptions for this rule: -No @samp{--enable} option should @strong{ever} cause one feature to -replace another. No @samp{--enable} option should ever substitute one -useful behavior for another useful behavior. The only proper use for -@samp{--enable} is for questions of whether to build part of the program -or exclude it. +@itemize @bullet +@item +It is okay to use a special language if the same program contains an +interpreter for that language. -@item --with-@var{package} -@c @r{[}=@var{parameter}@r{]} -The package @var{package} will be installed, so configure this package -to work with @var{package}. +For example, if your program links with GUILE, it is ok to write part of +the program in Scheme or another language supported by GUILE. -@c Giving an optional @var{parameter} of -@c @samp{no} should omit @var{package}, if it is used by default. +@item +It is okay to use another language in a tool specifically intended for +use with that language. -Possible values of @var{package} include @samp{x}, @samp{x-toolkit}, -@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and -@samp{gdb}. +This is okay because the only people who want to build the tool will be +those who have installed the other language anyway. -Do not use a @samp{--with} option to specify the file name to use to -find certain files. That is outside the scope of what @samp{--with} -options are for. +@item +If an application is not of extremely widespread interest, then perhaps +it's not important if the application is inconvenient to install. +@end itemize -@item --nfp -The target machine has no floating point processor. +@node Program Behavior +@chapter Program Behavior for All Programs -@item --gas -The target machine assembler is GAS, the GNU assembler. -This is obsolete; users should use @samp{--with-gnu-as} instead. +This @value{CHAPTER} describes how to write robust software. It also +describes general standards for error messages, the command line interface, +and how libraries should behave. -@item --x -The target machine has the X Window System installed. -This is obsolete; users should use @samp{--with-x} instead. -@end table +@menu +* Semantics:: Writing robust programs +* Libraries:: Library behavior +* Errors:: Formatting error messages +* User Interfaces:: Standards for command line interfaces +* Memory Usage:: When and how to care about memory needs +@end menu -All @code{configure} scripts should accept all of these ``detail'' -options, whether or not they make any difference to the particular -package at hand. In particular, they should accept any option that -starts with @samp{--with-} or @samp{--enable-}. This is so users will -be able to configure an entire GNU source tree at once with a single set -of options. +@node Semantics +@section Writing Robust Programs -You will note that the categories @samp{--with-} and @samp{--enable-} -are narrow: they @strong{do not} provide a place for any sort of option -you might think of. That is deliberate. We want to limit the possible -configuration options in GNU software. We do not want GNU programs to -have idiosyncratic configuration options. - -Packages that perform part of compilation may support cross-compilation. -In such a case, the host and target machines for the program may be -different. The @code{configure} script should normally treat the -specified type of system as both the host and the target, thus producing -a program which works for the same type of machine that it runs on. - -The way to build a cross-compiler, cross-assembler, or what have you, is -to specify the option @samp{--host=@var{hosttype}} when running -@code{configure}. This specifies the host system without changing the -type of target system. The syntax for @var{hosttype} is the same as -described above. - -Bootstrapping a cross-compiler requires compiling it on a machine other -than the host it will run on. Compilation packages accept a -configuration option @samp{--build=@var{hosttype}} for specifying the -configuration on which you will compile them, in case that is different -from the host. - -Programs for which cross-operation is not meaningful need not accept the -@samp{--host} option, because configuring an entire operating system for -cross-operation is not a meaningful thing. - -Some programs have ways of configuring themselves automatically. If -your program is set up to do this, your @code{configure} script can simply -ignore most of its arguments. - -@node Source Language -@chapter Using Languages Other Than C - -Using a language other than C is like using a non-standard feature: it -will cause trouble for users. Even if GCC supports the other language, -users may find it inconvenient to have to install the compiler for that -other language in order to build your program. So please write in C. - -There are three exceptions for this rule: - -@itemize @bullet -@item -It is okay to use a special language if the same program contains an -interpreter for that language. - -Thus, it is not a problem that GNU Emacs contains code written in Emacs -Lisp, because it comes with a Lisp interpreter. - -@item -It is okay to use another language in a tool specifically intended for -use with that language. - -This is okay because the only people who want to build the tool will be -those who have installed the other language anyway. - -@item -If an application is not of extremely widespread interest, then perhaps -it's not important if the application is inconvenient to install. -@end itemize +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. -@node Formatting -@chapter Formatting Your Source Code +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 for +interface to certain types of printers that can't handle those characters. -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 -for open-braces in column zero to find the beginnings of C functions. -These tools will not work on code not formatted that way. +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 +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. -It is also important for function definitions to start the name of the -function in column zero. This helps people to search for function -definitions, and may also help certain tools recognize them. Thus, -the proper format is this: +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, +@code{realloc} may get a different block if you ask for less space. -@example -static char * -concat (s1, s2) /* Name starts in column zero here */ - char *s1, *s2; -@{ /* Open brace in column zero here */ - @dots{} -@} -@end example +In Unix, @code{realloc} can destroy the storage block if it returns +zero. GNU @code{realloc} does not have this bug: if it fails, the +original block is unchanged. Feel free to assume the bug is fixed. If +you wish to run your program on Unix, and wish to avoid lossage in this +case, you can use the GNU @code{malloc}. -@noindent -or, if you want to use @sc{ANSI} C, format the definition like this: +You must expect @code{free} to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling @code{free}. -@example -static char * -concat (char *s1, char *s2) -@{ - @dots{} -@} -@end example +If @code{malloc} fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +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. -In @sc{ANSI} C, if the arguments don't fit nicely on one line, -split it like this: +Use @code{getopt_long} to decode arguments, unless the argument syntax +makes this unreasonable. -@example -int -lots_of_args (int an_integer, long a_long, short a_short, - double a_double, float a_float) -@dots{} -@end example +When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. +@c ADR: why? -For the body of the function, we prefer code formatted like this: +Try to avoid low-level interfaces to obscure Unix data structures (such +as file directories, utmp, or the layout of kernel memory), since these +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 will be supported compatibly by GNU. -@example -if (x < foo (y, z)) - haha = bar[4] + 5; -else - @{ - while (z) - @{ - haha += foo (z, z); - z--; - @} - return ++x + bar (); - @} -@end example +By default, the GNU system will provide the signal handling functions of +@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use +these. -We find it easier to read a program when it has spaces before the -open-parentheses and after the commas. Especially after the commas. +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 +to read the source code and run a debugger. So explain the problem with +comments in the source. The relevant data will be in variables, which +are easy to examine with the debugger, so there is no point moving them +elsewhere. -When you split an expression into multiple lines, split it -before an operator, not after one. Here is the right way: +Do not use a count of errors as the exit status for a program. +@emph{That does not work}, because exit status values are limited to 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. -@example -if (foo_this_is_long && bar > win (x, y, z) - && remaining_condition) -@end example +If you make temporary files, check the @code{TMPDIR} environment +variable; if that variable is defined, use the specified directory +instead of @file{/tmp}. -Try to avoid having two operators of different precedence at the same -level of indentation. For example, don't write this: +@node Libraries +@section Library Behavior -@example -mode = (inmode[j] == VOIDmode - || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) - ? outmode[j] : inmode[j]); -@end example +Try to make library functions reentrant. If they need to do dynamic +storage allocation, at least try to avoid any nonreentrancy aside from +that of @code{malloc} itself. -Instead, use extra parentheses so that the indentation shows the nesting: +Here are certain name conventions for libraries, to avoid name +conflicts. -@example -mode = ((inmode[j] == VOIDmode - || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) - ? outmode[j] : inmode[j]); -@end example +Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this +prefix. In addition, there should only be one of these in any given +library member. This usually means putting each one in a separate +source file. -Insert extra parentheses so that Emacs will indent the code properly. -For example, the following indentation looks nice if you do it by hand, -but Emacs would mess it up: +An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the +other; then they can both go in the same file. -@example -v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 - + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; -@end example +External symbols that are not documented entry points for the user +should have names beginning with @samp{_}. They should also contain +the chosen name prefix for the library, to prevent collisions with +other libraries. These can go in the same files with user entry +points if you like. -But adding a set of parentheses solves the problem: +Static functions and variables can be used as you like and need not +fit any naming convention. -@example -v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 - + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); -@end example +@node Errors +@section Formatting Error Messages -Format do-while statements like this: +Error messages from compilers should look like this: @example -do - @{ - a = foo (a); - @} -while (a > 0); +@var{source-file-name}:@var{lineno}: @var{message} @end example -Please use formfeed characters (control-L) to divide the program into -pages at logical places (but not within a function). It does not matter -just how long the pages are, since they do not have to fit on a printed -page. The formfeeds should appear alone on lines by themselves. - - -@node Comments -@chapter Commenting Your Work - -Every program should start with a comment saying briefly what it is for. -Example: @samp{fmt - filter for simple filling of text}. - -Please put a comment on each function saying what the function does, -what sorts of arguments it gets, and what the possible values of -arguments mean and are used for. It is not necessary to duplicate in -words the meaning of the C argument declarations, if a C type is being -used in its customary fashion. If there is anything nonstandard about -its use (such as an argument of type @code{char *} which is really the -address of the second character of a string, not the first), or any -possible values that would not work the way one would expect (such as, -that strings containing newlines are not guaranteed to work), be sure -to say so. - -Also explain the significance of the return value, if there is one. - -Please put two spaces after the end of a sentence in your comments, so -that the Emacs sentence commands will work. Also, please write -complete sentences and capitalize the first word. If a lower-case -identifier comes at the beginning of a sentence, don't capitalize it! -Changing the spelling makes it a different identifier. If you don't -like starting a sentence with a lower case letter, write the sentence -differently (e.g., ``The identifier lower-case is @dots{}''). - -The comment on a function is much clearer if you use the argument -names to speak about the argument values. The variable name itself -should be lower case, but write it in upper case when you are speaking -about the value rather than the variable itself. Thus, ``the inode -number NODE_NUM'' rather than ``an inode''. - -There is usually no purpose in restating the name of the function in -the comment before it, because the reader can see that for himself. -There might be an exception when the comment is so long that the function -itself would be off the bottom of the screen. - -There should be a comment on each static variable as well, like this: +Error messages from other noninteractive programs should look like this: @example -/* Nonzero means truncate lines in the display; - zero means continue them. */ -int truncate_lines; +@var{program}:@var{source-file-name}:@var{lineno}: @var{message} @end example -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 -its sense}. @samp{#else} should have a comment describing the condition -@emph{and sense} of the code that follows. For example: +@noindent +when there is an appropriate source file, or like this: @example -#ifdef foo - @dots{} -#else /* not foo */ - @dots{} -#endif /* not foo */ +@var{program}: @var{message} @end example @noindent -but, by contrast, write the comments this way for a @samp{#ifndef}: +when there is no relevant source file. -@example -#ifndef foo - @dots{} -#else /* foo */ - @dots{} -#endif /* foo */ -@end example +In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) +The string @var{message} should not begin with a capital letter when +it follows a program name and/or file name. Also, it should not end +with a period. -@node Syntactic Conventions -@chapter Clean Use of C Constructs +Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. -Please explicitly declare all arguments to functions. -Don't omit them just because they are @code{int}s. +@node User Interfaces +@section Standards for Command Line Interfaces -Declarations of external functions and functions to appear later in the -source file should all go in one place near the beginning of the file -(somewhere before the first function definition in the file), or else -should go in a header file. Don't put @code{extern} declarations inside -functions. +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. -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 -variable for each distinct purpose, and give it a name which is -meaningful. This not only makes programs easier to understand, it also -facilitates optimization by good compilers. You can also move the -declaration of each local variable into the smallest scope that includes -all its uses. This makes the program even cleaner. +Instead, use a run time option or a compilation switch or both +to select among the alternate behaviors. -Don't use local variables or parameters that shadow global identifiers. +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 to save someone from typing an option now and then. -Don't declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. For example, instead -of this: +If you think one behavior is most useful when the output is to a +terminal, and another is most useful when the output is a file or a +pipe, then it is usually best to make the default behavior the one that +is useful with output to a terminal, and have an option for the other +behavior. -@example -int foo, - bar; -@end example +Compatibility requires certain programs to depend on the type of output +device. It would be disastrous if @code{ls} or @code{sh} did not do so +in the way all users expect. In some of these cases, we supplement the +program with a preferred alternate version that does not depend on the +output device type. For example, we provide a @code{dir} program much +like @code{ls} except that its default output format is always +multi-column format. -@noindent -write either this: +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} +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. -@example -int foo, bar; -@end example +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 +@code{getopt_long}. -@noindent -or this: +One of the advantages of long-named options is that they can be +consistent from program to program. For example, users should be able +to expect the ``verbose'' option of any GNU program which has one, to be +spelled precisely @samp{--verbose}. To achieve this uniformity, look at +the table of common long-option names when you choose the option names +for your program. The table appears below. -@example -int foo; -int bar; -@end example +If you use names not already in the table, please send +@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we +can update the table. -@noindent -(If they are global variables, each should have a comment preceding it -anyway.) +It is usually a good idea for file names given as ordinary arguments +to be input files only; any output files would be specified using +options (preferably @samp{-o}). Even if you allow an output file name +as an ordinary argument for compatibility, try to provide a suitable +option as well. This will lead to more consistency among GNU +utilities, so that there are fewer idiosyncracies for users to +remember. -When you have an @code{if}-@code{else} statement nested in another -@code{if} statement, always put braces around the @code{if}-@code{else}. -Thus, never write like this: +Programs should support an option @samp{--version} which prints the +program's version number on standard output and exits successfully, and +an option @samp{--help} which prints option usage information on +standard output and exits successfully. These options should inhibit +the normal function of the command; they should do nothing except print +the requested information. -@example -if (foo) - if (bar) - win (); - else - lose (); -@end example +@c Please leave newlines between items in this table; it's much easier +@c to update when it isn't completely squashed together and unreadable. +@c When there is more than one short option for a long option name, put +@c a semicolon between the lists of the programs that use them, not a +@c period. --friedman -@noindent -always like this: +Here is the table of long options used by GNU programs. -@example -if (foo) - @{ - if (bar) - win (); - else - lose (); - @} -@end example +@table @samp -If you have an @code{if} statement nested inside of an @code{else} -statement, either write @code{else if} on one line, like this, +@item after-date +@samp{-N} in @code{tar}. -@example -if (foo) - @dots{} -else if (bar) - @dots{} -@end example +@item all +@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, +and @code{unexpand}. -@noindent -with its @code{then}-part indented like the preceding @code{then}-part, -or write the nested @code{if} within braces like this: +@item all-text +@samp{-a} in @code{diff}. -@example -if (foo) - @dots{} -else - @{ - if (bar) - @dots{} - @} -@end example +@item almost-all +@samp{-A} in @code{ls}. -Don't declare both a structure tag and variables or typedefs in the -same declaration. Instead, declare the structure tag separately -and then use it to declare the variables or typedefs. +@item append +@samp{-a} in @code{etags}, @code{tee}, @code{time}; +@samp{-r} in @code{tar}. -Try to avoid assignments inside @code{if}-conditions. For example, -don't write this: +@item archive +@samp{-a} in @code{cp}. -@example -if ((foo = (char *) malloc (sizeof *foo)) == 0) - fatal ("virtual memory exhausted"); -@end example +@item archive-name +@samp{-n} in @code{shar}. -@noindent -instead, write this: +@item arglength +@samp{-l} in @code{m4}. -@example -foo = (char *) malloc (sizeof *foo); -if (foo == 0) - fatal ("virtual memory exhausted"); -@end example +@item ascii +@samp{-a} in @code{diff}. -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. +@item assign +@samp{-v} in @code{gawk}. -@node Names -@chapter Naming Variables, Functions, and Files +@item assume-new +@samp{-W} in Make. -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 -that follow a uniform convention. +@item assume-old +@samp{-o} in Make. -For example, you should use names like @code{ignore_space_change_flag}; -don't use names like @code{iCantReadThis}. +@item auto-check +@samp{-a} in @code{recode}. -Variables that indicate whether command-line options have been -specified should be named after the meaning of the option, not after -the option-letter. A comment should state both the exact meaning of -the option and its letter. For example, +@item auto-pager +@samp{-a} in @code{wdiff}. -@example -/* Ignore changes in horizontal whitespace (-b). */ -int ignore_space_change_flag; -@end example +@item auto-reference +@samp{-A} in @code{ptx}. -When you want to define names with constant integer values, use -@code{enum} rather than @samp{#define}. GDB knows about enumeration -constants. +@item avoid-wraps +@samp{-n} in @code{wdiff}. -Use file names of 14 characters or less, to avoid creating gratuitous -problems on System V. You can use the program @code{doschk} to test for -this. @code{doschk} also tests for potential name conflicts if the -files were loaded onto an MS-DOS file system---something you may or may -not care about. +@item backward-search +@samp{-B} in @code{ctags}. -In general, use @samp{-} to separate words in file names, not @samp{_}. -Make all letters in file names be lower case, except when following -specific conventions that call for upper case in certain kinds of names. -Conventional occasions for using upper case letters in file names -include @file{Makefile}, @file{ChangeLog}, @file{COPYING} and -@file{README}. It is common to name other @file{README}-like -documentation files in all upper case just like @file{README}. +@item basename +@samp{-f} in @code{shar}. -@node Using Extensions -@chapter Using Non-standard Features +@item batch +Used in GDB. -Many GNU facilities that already exist support a number of convenient -extensions over the comparable Unix facilities. Whether to use these -extensions in implementing your program is a difficult question. +@item baud +Used in GDB. -On the one hand, using the extensions can make a cleaner program. -On the other hand, people will not be able to build the program -unless the other GNU tools are available. This might cause the -program to work on fewer kinds of machines. +@item before +@samp{-b} in @code{tac}. -With some extensions, it might be easy to provide both alternatives. -For example, you can define functions with a ``keyword'' @code{INLINE} -and define that as a macro to expand into either @code{inline} or -nothing, depending on the compiler. +@item binary +@samp{-b} in @code{cpio} and @code{diff}. -In general, perhaps it is best not to use the extensions if you can -straightforwardly do without them, but to use the extensions if they -are a big improvement. +@item bits-per-code +@samp{-b} in @code{shar}. -An exception to this rule are the large, established programs (such as -Emacs) which run on a great variety of systems. Such programs would -be broken by use of GNU extensions. +@item block-size +Used in @code{cpio} and @code{tar}. -Another exception is for programs that are used as part of -compilation: anything that must be compiled with other compilers in -order to bootstrap the GNU compilation facilities. If these require -the GNU compiler, then no one can compile them without having them -installed already. That would be no good. +@item blocks +@samp{-b} in @code{head} and @code{tail}. -Since most computer systems do not yet implement @sc{ANSI} C, using the -@sc{ANSI} C features is effectively using a GNU extension, so the -same considerations apply. (Except for @sc{ANSI} features that we -discourage, such as trigraphs---don't ever use them.) +@item break-file +@samp{-b} in @code{ptx}. +@item brief +Used in various programs to make output shorter. -@node System Functions -@chapter Calling System Functions +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. -C implementations differ substantially. ANSI C reduces but does not -eliminate the incompatibilities; meanwhile, many users wish to compile -GNU software with pre-ANSI compilers. This chapter gives -recommendations for how to use the more or less standard C library -functions to avoid unnecessary loss of portability. +@item c@t{++} +@samp{-C} in @code{etags}. -@itemize @bullet -@item -Don't use the value of @code{sprintf}. It returns the number of -characters written on some systems, but not on all systems. +@item catenate +@samp{-A} in @code{tar}. -@item -Don't declare system functions explicitly. +@item cd +Used in various programs to specify the directory to use. -Almost any declaration for a system function is wrong on some system. -To minimize conflicts, leave it to the system header files to declare -system functions. If the headers don't declare a function, let it -remain undeclared. +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. -While it may seem unclean to use a function without declaring it, in -practice this works fine for most system library functions on the -systems where this really happens. The problem is only theoretical. By -contrast, actual declarations have frequently caused actual conflicts. +@item classify +@samp{-F} in @code{ls}. -@item -If you must declare a system function, don't specify the argument types. -Use an old-style declaration, not an ANSI prototype. The more you -specify about the function, the more likely a conflict. +@item colons +@samp{-c} in @code{recode}. -@item -In particular, don't unconditionally declare @code{malloc} or -@code{realloc}. +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. -Most GNU programs use those functions just once, in functions -conventionally named @code{xmalloc} and @code{xrealloc}. These -functions call @code{malloc} and @code{realloc}, respectively, and -check the results. +@item compare +@samp{-d} in @code{tar}. -Because @code{xmalloc} and @code{xrealloc} are defined in your program, -you can declare them in other files without any risk of type conflict. +@item compat +Used in @code{gawk}. -On most systems, @code{int} is the same length as a pointer; thus, the -calls to @code{malloc} and @code{realloc} work fine. For the few -exceptional systems (mostly 64-bit machines), you can use -@strong{conditionalized} declarations of @code{malloc} and -@code{realloc}---or put these declarations in configuration files -specific to those systems. +@item compress +@samp{-Z} in @code{tar} and @code{shar}. -@item -The string functions require special treatment. Some Unix systems have -a header file @file{string.h}; other have @file{strings.h}. Neither -file name is portable. There are two things you can do: use Autoconf to -figure out which file to include, or don't include either file. +@item concatenate +@samp{-A} in @code{tar}. -@item -If you don't include either strings file, you can't get declarations for -the string functions from the header file in the usual way. +@item confirmation +@samp{-w} in @code{tar}. -That causes less of a problem than you might think. The newer ANSI -string functions are off-limits anyway because many systems still don't -support them. The string functions you can use are these: +@item context +Used in @code{diff}. -@example -strcpy strncpy strcat strncat -strlen strcmp strncmp -strchr strrchr -@end example +@item copyleft +@samp{-W copyleft} in @code{gawk}. -The copy and concatenate functions work fine without a declaration as -long as you don't use their values. Using their values without a -declaration fails on systems where the width of a pointer differs from -the width of @code{int}, and perhaps in other cases. It is trivial to -avoid using their values, so do that. +@item copyright +@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; +@samp{-W copyright} in @code{gawk}. -The compare functions and @code{strlen} work fine without a declaration -on most systems, possibly all the ones that GNU software runs on. -You may find it necessary to declare them @strong{conditionally} on a -few systems. +@item core +Used in GDB. -The search functions must be declared to return @code{char *}. Luckily, -there is no variation in the data type they return. But there is -variation in their names. Some systems give these functions the names -@code{index} and @code{rindex}; other systems use the names -@code{strchr} and @code{strrchr}. Some systems support both pairs of -names, but neither pair works on all systems. +@item count +@samp{-q} in @code{who}. -You should pick a single pair of names and use it throughout your -program. (Nowadays, it is better to choose @code{strchr} and -@code{strrchr}.) Declare both of those names as functions returning -@code{char *}. On systems which don't support those names, define them -as macros in terms of the other pair. For example, here is what to put -at the beginning of your file (or in a header) if you want to use the -names @code{strchr} and @code{strrchr} throughout: +@item count-links +@samp{-l} in @code{du}. -@example -#ifndef HAVE_STRCHR -#define strchr index -#endif -#ifndef HAVE_STRRCHR -#define strrchr rindex -#endif +@item create +Used in @code{tar} and @code{cpio}. -char *strchr (); -char *strrchr (); -@end example -@end itemize +@item cut-mark +@samp{-c} in @code{shar}. -Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are -macros defined in systems where the corresponding functions exist. -One way to get them properly defined is to use Autoconf. +@item cxref +@samp{-x} in @code{ctags}. -@node Semantics -@chapter Program Behavior for All Programs +@item date +@samp{-d} in @code{touch}. -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. +@item debug +@samp{-d} in Make and @code{m4}; +@samp{-t} in Bison. -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 for -interface to certain types of printers that can't handle those characters. +@item define +@samp{-D} in @code{m4}. -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 -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. +@item defines +@samp{-d} in Bison and @code{ctags}. -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, -@code{realloc} may get a different block if you ask for less space. +@item delete +@samp{-D} in @code{tar}. -In Unix, @code{realloc} can destroy the storage block if it returns -zero. GNU @code{realloc} does not have this bug: if it fails, the -original block is unchanged. Feel free to assume the bug is fixed. If -you wish to run your program on Unix, and wish to avoid lossage in this -case, you can use the GNU @code{malloc}. +@item dereference +@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, +@code{ls}, and @code{tar}. -You must expect @code{free} to alter the contents of the block that was -freed. Anything you want to fetch from the block, you must fetch before -calling @code{free}. +@item dereference-args +@samp{-D} in @code{du}. -If @code{malloc} fails in a noninteractive program, make that a fatal -error. In an interactive program (one that reads commands from the -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. +@item diacritics +@samp{-d} in @code{recode}. -Use @code{getopt_long} to decode arguments, unless the argument syntax -makes this unreasonable. +@item dictionary-order +@samp{-d} in @code{look}. -When static storage is to be written in during program execution, use -explicit C code to initialize it. Reserve C initialized declarations -for data that will not be changed. +@item diff +@samp{-d} in @code{tar}. -Try to avoid low-level interfaces to obscure Unix data structures (such -as file directories, utmp, or the layout of kernel memory), since these -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 will be supported compatibly by GNU. +@item digits +@samp{-n} in @code{csplit}. -By default, the GNU system will provide the signal handling functions of -@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use -these. +@item directory +Specify the directory to use, in various programs. In @code{ls}, it +means to show directories themselves rather than their contents. In +@code{rm} and @code{ln}, it means to not treat links to directories +specially. -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 -to read the source code and run a debugger. So explain the problem with -comments in the source. The relevant data will be in variables, which -are easy to examine with the debugger, so there is no point moving them -elsewhere. +@item discard-all +@samp{-x} in @code{strip}. -Do not use a count of errors as the exit status for a program. -@emph{That does not work}, because exit status values are limited to 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. +@item discard-locals +@samp{-X} in @code{strip}. -If you make temporary files, check the @code{TMPDIR} environment -variable; if that variable is defined, use the specified directory -instead of @file{/tmp}. +@item dry-run +@samp{-n} in Make. -@node Errors -@chapter Formatting Error Messages +@item ed +@samp{-e} in @code{diff}. -Error messages from compilers should look like this: +@item elide-empty-files +@samp{-z} in @code{csplit}. -@example -@var{source-file-name}:@var{lineno}: @var{message} -@end example +@item end-delete +@samp{-x} in @code{wdiff}. -Error messages from other noninteractive programs should look like this: +@item end-insert +@samp{-z} in @code{wdiff}. -@example -@var{program}:@var{source-file-name}:@var{lineno}: @var{message} -@end example +@item entire-new-file +@samp{-N} in @code{diff}. -@noindent -when there is an appropriate source file, or like this: +@item environment-overrides +@samp{-e} in Make. -@example -@var{program}: @var{message} -@end example +@item eof +@samp{-e} in @code{xargs}. -@noindent -when there is no relevant source file. +@item epoch +Used in GDB. -In an interactive program (one that is reading commands from a -terminal), it is better not to include the program name in an error -message. The place to indicate which program is running is in the -prompt or with the screen layout. (When the same program runs with -input from a source other than a terminal, it is not interactive and -would do best to print error messages using the noninteractive style.) +@item error-limit +Used in @code{makeinfo}. -The string @var{message} should not begin with a capital letter when -it follows a program name and/or file name. Also, it should not end -with a period. +@item error-output +@samp{-o} in @code{m4}. -Error messages from interactive programs, and other messages such as -usage messages, should start with a capital letter. But they should not -end with a period. +@item escape +@samp{-b} in @code{ls}. +@item exclude-from +@samp{-X} in @code{tar}. -@node Libraries -@chapter Library Behavior +@item exec +Used in GDB. -Try to make library functions reentrant. If they need to do dynamic -storage allocation, at least try to avoid any nonreentrancy aside from -that of @code{malloc} itself. +@item exit +@samp{-x} in @code{xargs}. -Here are certain name conventions for libraries, to avoid name -conflicts. +@item exit-0 +@samp{-e} in @code{unshar}. -Choose a name prefix for the library, more than two characters long. -All external function and variable names should start with this -prefix. In addition, there should only be one of these in any given -library member. This usually means putting each one in a separate -source file. +@item expand-tabs +@samp{-t} in @code{diff}. -An exception can be made when two external symbols are always used -together, so that no reasonable program could use one without the -other; then they can both go in the same file. +@item expression +@samp{-e} in @code{sed}. -External symbols that are not documented entry points for the user -should have names beginning with @samp{_}. They should also contain -the chosen name prefix for the library, to prevent collisions with -other libraries. These can go in the same files with user entry -points if you like. +@item extern-only +@samp{-g} in @code{nm}. -Static functions and variables can be used as you like and need not -fit any naming convention. +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. +@item faces +@samp{-f} in @code{finger}. -@node Portability -@chapter Portability As It Applies to GNU +@item fast +@samp{-f} in @code{su}. -Much of what is called ``portability'' in the Unix world refers to -porting to different Unix versions. This is a secondary consideration -for GNU software, because its primary purpose is to run on top of one -and only one kernel, the GNU kernel, compiled with one and only one C -compiler, the GNU C compiler. The amount and kinds of variation among -GNU systems on different cpu's will be like the variation among Berkeley -4.3 systems on different cpu's. - -All users today run GNU software on non-GNU systems. So supporting a -variety of non-GNU systems is desirable; simply not paramount. -The easiest way to achieve portability to a reasonable range of systems -is to use Autoconf. It's unlikely that your program needs to know more -information about the host machine than Autoconf can provide, simply -because most of the programs that need such knowledge have already been -written. +@item fatal-warnings +@samp{-E} in @code{m4}. -It is difficult to be sure exactly what facilities the GNU kernel -will provide, since it isn't finished yet. Therefore, assume you can -use anything in 4.3; just avoid using the format of semi-internal data -bases (e.g., directories) when there is a higher-level alternative -(@code{readdir}). - -You can freely assume any reasonably standard facilities in the C -language, libraries or kernel, because we will find it necessary to -support these facilities in the full GNU system, whether or not we -have already done so. The fact that there may exist kernels or C -compilers that lack these facilities is irrelevant as long as the GNU -kernel and C compiler support them. - -It remains necessary to worry about differences among cpu types, such -as the difference in byte ordering and alignment restrictions. It's -unlikely that 16-bit machines will ever be supported by GNU, so there -is no point in spending any time to consider the possibility that an -int will be less than 32 bits. - -You can assume that all pointers have the same format, regardless -of the type they point to, and that this is really an integer. -There are some weird machines where this isn't true, but they aren't -important; don't waste time catering to them. Besides, eventually -we will put function prototypes into all GNU programs, and that will -probably make your program work even on weird machines. - -Since some important machines (including the 68000) are big-endian, -it is important not to assume that the address of an @code{int} object -is also the address of its least-significant byte. Thus, don't -make the following mistake: +@item file +@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar}; +@samp{-n} in @code{sed}; +@samp{-r} in @code{touch}. -@example -int c; -@dots{} -while ((c = getchar()) != EOF) - write(file_descriptor, &c, 1); -@end example +@item field-separator +@samp{-F} in @code{gawk}. -You can assume that it is reasonable to use a meg of memory. Don't -strain to reduce memory usage unless it can get to that level. If -your program creates complicated data structures, just make them in -core and give a fatal error if malloc returns zero. +@item file-prefix +@samp{-b} in Bison. -If a program works by lines and could be applied to arbitrary -user-supplied input files, it should keep only a line in memory, because -this is not very hard and users will want to be able to operate on input -files that are bigger than will fit in core all at once. +@item file-type +@samp{-F} in @code{ls}. +@item files-from +@samp{-T} in @code{tar}. -@node User Interfaces -@chapter Standards for Command Line Interfaces +@item fill-column +Used in @code{makeinfo}. -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. +@item flag-truncation +@samp{-F} in @code{ptx}. -Instead, use a run time option or a compilation switch or both -to select among the alternate behaviors. +@item fixed-output-files +@samp{-y} in Bison. -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 to save someone from typing an option now and then. +@item follow +@samp{-f} in @code{tail}. -If you think one behavior is most useful when the output is to a -terminal, and another is most useful when the output is a file or a -pipe, then it is usually best to make the default behavior the one that -is useful with output to a terminal, and have an option for the other -behavior. +@item footnote-style +Used in @code{makeinfo}. -Compatibility requires certain programs to depend on the type of output -device. It would be disastrous if @code{ls} or @code{sh} did not do so -in the way all users expect. In some of these cases, we supplement the -program with a preferred alternate version that does not depend on the -output device type. For example, we provide a @code{dir} program much -like @code{ls} except that its default output format is always -multi-column format. +@item force +@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. -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} -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. +@item force-prefix +@samp{-F} in @code{shar}. -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 -@code{getopt_long}. +@item format +Used in @code{ls}, @code{time}, and @code{ptx}. -One of the advantages of long-named options is that they can be -consistent from program to program. For example, users should be able -to expect the ``verbose'' option of any GNU program which has one, to be -spelled precisely @samp{--verbose}. To achieve this uniformity, look at -the table of common long-option names when you choose the option names -for your program. The table appears below. +@item freeze-state +@samp{-F} in @code{m4}. -If you use names not already in the table, please send -@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we -can update the table. +@item fullname +Used in GDB. -It is usually a good idea for file names given as ordinary arguments -to be input files only; any output files would be specified using -options (preferably @samp{-o}). Even if you allow an output file name -as an ordinary argument for compatibility, try to provide a suitable -option as well. This will lead to more consistency among GNU -utilities, so that there are fewer idiosyncracies for users to -remember. +@item gap-size +@samp{-g} in @code{ptx}. -Programs should support an option @samp{--version} which prints the -program's version number on standard output and exits successfully, and -an option @samp{--help} which prints option usage information on -standard output and exits successfully. These options should inhibit -the normal function of the command; they should do nothing except print -the requested information. +@item get +@samp{-x} in @code{tar}. -@c longopts begin here (keyword for isearch) -@c Please leave newlines between items in this table; it's much easier -@c to update when it isn't completely squashed together and unreadable. -@c When there is more than one short option for a long option name, put -@c a semicolon between the lists of the programs that use them, not a -@c period. --friedman +@item graphic +@samp{-i} in @code{ul}. -@table @samp +@item graphics +@samp{-g} in @code{recode}. + +@item group +@samp{-g} in @code{install}. -@item after-date -@samp{-N} in @code{tar}. +@item gzip +@samp{-z} in @code{tar} and @code{shar}. -@item all -@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, -and @code{unexpand}. +@item hashsize +@samp{-H} in @code{m4}. -@item all-text -@samp{-a} in @code{diff}. +@item header +@samp{-h} in @code{objdump} and @code{recode} -@item almost-all -@samp{-A} in @code{ls}. +@item heading +@samp{-H} in @code{who}. -@item append -@samp{-a} in @code{etags}, @code{tee}, @code{time}; -@samp{-r} in @code{tar}. +@item help +Used to ask for brief usage information. -@item archive -@samp{-a} in @code{cp}. +@item here-delimiter +@samp{-d} in @code{shar}. -@item archive-name -@samp{-n} in @code{shar}. +@item hide-control-chars +@samp{-q} in @code{ls}. -@item arglength -@samp{-l} in @code{m4}. +@item idle +@samp{-u} in @code{who}. -@item ascii -@samp{-a} in @code{diff}. +@item ifdef +@samp{-D} in @code{diff}. -@item assign -@samp{-v} in Gawk. +@item ignore +@samp{-I} in @code{ls}; +@samp{-x} in @code{recode}. -@item assume-new -@samp{-W} in Make. +@item ignore-all-space +@samp{-w} in @code{diff}. -@item assume-old -@samp{-o} in Make. +@item ignore-backups +@samp{-B} in @code{ls}. -@item auto-check -@samp{-a} in @code{recode}. +@item ignore-blank-lines +@samp{-B} in @code{diff}. -@item auto-pager -@samp{-a} in @code{wdiff}. +@item ignore-case +@samp{-f} in @code{look} and @code{ptx}; +@samp{-i} in @code{diff} and @code{wdiff}. -@item auto-reference -@samp{-A} in @code{ptx}. +@item ignore-errors +@samp{-i} in Make. -@item avoid-wraps -@samp{-n} in @code{wdiff}. +@item ignore-file +@samp{-i} in @code{ptx}. -@item backward-search -@samp{-B} in @code{ctags}. +@item ignore-indentation +@samp{-I} in @code{etags}. -@item basename -@samp{-f} in @code{shar}. +@item ignore-init-file +@samp{-f} in Oleo. -@item batch -Used in GDB. +@item ignore-interrupts +@samp{-i} in @code{tee}. -@item baud -Used in GDB. +@item ignore-matching-lines +@samp{-I} in @code{diff}. -@item before -@samp{-b} in @code{tac}. +@item ignore-space-change +@samp{-b} in @code{diff}. -@item binary -@samp{-b} in @code{cpio} and @code{diff}. +@item ignore-zeros +@samp{-i} in @code{tar}. -@item bits-per-code -@samp{-b} in @code{shar}. +@item include +@samp{-i} in @code{etags}; +@samp{-I} in @code{m4}. -@item block-size -Used in @code{cpio} and @code{tar}. +@item include-dir +@samp{-I} in Make. -@item blocks -@samp{-b} in @code{head} and @code{tail}. +@item incremental +@samp{-G} in @code{tar}. -@item break-file -@samp{-b} in @code{ptx}. +@item info +@samp{-i}, @samp{-l}, and @samp{-m} in Finger. -@item brief -Used in various programs to make output shorter. +@item initial +@samp{-i} in @code{expand}. -@item bytes -@samp{-c} in @code{head}, @code{split}, and @code{tail}. +@item initial-tab +@samp{-T} in @code{diff}. -@item c@t{++} -@samp{-C} in @code{etags}. +@item inode +@samp{-i} in @code{ls}. -@item catenate -@samp{-A} in @code{tar}. +@item interactive +@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; +@samp{-e} in @code{m4}; +@samp{-p} in @code{xargs}; +@samp{-w} in @code{tar}. -@item cd -Used in various programs to specify the directory to use. +@item intermix-type +@samp{-p} in @code{shar}. -@item changes -@samp{-c} in @code{chgrp} and @code{chown}. +@item jobs +@samp{-j} in Make. -@item classify -@samp{-F} in @code{ls}. +@item just-print +@samp{-n} in Make. -@item colons -@samp{-c} in @code{recode}. +@item keep-going +@samp{-k} in Make. -@item command -@samp{-c} in @code{su}; -@samp{-x} in GDB. +@item keep-files +@samp{-k} in @code{csplit}. -@item compare -@samp{-d} in @code{tar}. +@item kilobytes +@samp{-k} in @code{du} and @code{ls}. -@item compat -Used in gawk (no corresponding single-letter option). +@item language +@samp{-l} in @code{etags}. -@item compress -@samp{-Z} in @code{tar} and @code{shar}. +@item less-mode +@samp{-l} in @code{wdiff}. -@item concatenate -@samp{-A} in @code{tar}. +@item level-for-gzip +@samp{-g} in @code{shar}. -@item confirmation -@samp{-w} in @code{tar}. +@item line-bytes +@samp{-C} in @code{split}. -@item context -Used in @code{diff}. +@item lines +Used in @code{split}, @code{head}, and @code{tail}. -@item copyleft -Used in gawk (no corresponding single-letter option). +@item link +@samp{-l} in @code{cpio}. -@item copyright -@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}. -Also used in gawk (no corresponding single-letter option). +@item lint +@itemx lint-old +Used in @code{gawk}. -@item core -Used in GDB. +@item list +@samp{-t} in @code{cpio}; +@samp{-l} in @code{recode}. -@item count -@samp{-q} in @code{who}. +@item list +@samp{-t} in @code{tar}. -@item count-links -@samp{-l} in @code{du}. +@item literal +@samp{-N} in @code{ls}. -@item create -Used in @code{tar} and @code{cpio}. +@item load-average +@samp{-l} in Make. -@item cut-mark -@samp{-c} in @code{shar}. +@item login +Used in @code{su}. -@item cxref -@samp{-x} in @code{ctags}. +@item machine +No listing of which programs already use this; +someone should check to +see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. -@item date -@samp{-d} in @code{touch}. +@item macro-name +@samp{-M} in @code{ptx}. -@item debug -@samp{-d} in Make and @code{m4}; -@samp{-t} in Bison. +@item mail +@samp{-m} in @code{hello} and @code{uname}. -@item define -@samp{-D} in @code{m4}. +@item make-directories +@samp{-d} in @code{cpio}. -@item defines -@samp{-d} in Bison and @code{ctags}. +@item makefile +@samp{-f} in Make. -@item delete -@samp{-D} in @code{tar}. +@item mapped +Used in GDB. -@item dereference -@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, -@code{ls}, and @code{tar}. +@item max-args +@samp{-n} in @code{xargs}. -@item dereference-args -@samp{-D} in @code{du}. +@item max-chars +@samp{-n} in @code{xargs}. -@item diacritics -@samp{-d} in @code{recode}. +@item max-lines +@samp{-l} in @code{xargs}. -@item dictionary-order -@samp{-d} in @code{look}. +@item max-load +@samp{-l} in Make. -@item diff -@samp{-d} in @code{tar}. +@item max-procs +@samp{-P} in @code{xargs}. -@item digits -@samp{-n} in @code{csplit}. +@item mesg +@samp{-T} in @code{who}. -@item directory -Specify the directory to use, in various programs. In @code{ls}, it -means to show directories themselves rather than their contents. In -@code{rm} and @code{ln}, it means to not treat links to directories -specially. +@item message +@samp{-T} in @code{who}. -@item discard-all -@samp{-x} in @code{strip}. +@item minimal +@samp{-d} in @code{diff}. -@item discard-locals -@samp{-X} in @code{strip}. +@item mixed-uuencode +@samp{-M} in @code{shar}. -@item dry-run -@samp{-n} in Make. +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. -@item ed -@samp{-e} in @code{diff}. +@item modification-time +@samp{-m} in @code{tar}. -@item elide-empty-files -@samp{-z} in @code{csplit}. +@item multi-volume +@samp{-M} in @code{tar}. -@item end-delete -@samp{-x} in @code{wdiff}. +@item name-prefix +@samp{-a} in Bison. -@item end-insert -@samp{-z} in @code{wdiff}. +@item nesting-limit +@samp{-L} in @code{m4}. -@item entire-new-file -@samp{-N} in @code{diff}. +@item net-headers +@samp{-a} in @code{shar}. -@item environment-overrides -@samp{-e} in Make. +@item new-file +@samp{-W} in Make. -@item eof -@samp{-e} in @code{xargs}. +@item no-builtin-rules +@samp{-r} in Make. -@item epoch -Used in GDB. +@item no-character-count +@samp{-w} in @code{shar}. -@item error-limit -Used in Makeinfo. +@item no-check-existing +@samp{-x} in @code{shar}. -@item error-output -@samp{-o} in @code{m4}. +@item no-common +@samp{-3} in @code{wdiff}. -@item escape -@samp{-b} in @code{ls}. +@item no-create +@samp{-c} in @code{touch}. -@item exclude-from -@samp{-X} in @code{tar}. +@item no-defines +@samp{-D} in @code{etags}. -@item exec -Used in GDB. +@item no-deleted +@samp{-1} in @code{wdiff}. -@item exit -@samp{-x} in @code{xargs}. +@item no-dereference +@samp{-d} in @code{cp}. -@item exit-0 -@samp{-e} in @code{unshar}. +@item no-inserted +@samp{-2} in @code{wdiff}. -@item expand-tabs -@samp{-t} in @code{diff}. +@item no-keep-going +@samp{-S} in Make. -@item expression -@samp{-e} in @code{sed}. +@item no-lines +@samp{-l} in Bison. -@item extern-only -@samp{-g} in @code{nm}. +@item no-piping +@samp{-P} in @code{shar}. -@item extract -@samp{-i} in @code{cpio}; -@samp{-x} in @code{tar}. +@item no-prof +@samp{-e} in @code{gprof}. -@item faces -@samp{-f} in @code{finger}. +@item no-regex +@samp{-R} in @code{etags}. -@item fast -@samp{-f} in @code{su}. +@item no-sort +@samp{-p} in @code{nm}. -@item fatal-warnings -@samp{-E} in @code{m4}. +@item no-split +Used in @code{makeinfo}. -@item field-separator -p@samp{-F} in Gawk. +@item no-static +@samp{-a} in @code{gprof}. -@item file -@samp{-f} in Gawk, @code{info}, Make, @code{mt}, and @code{tar}; -@samp{-n} in @code{sed}; -@samp{-r} in @code{touch}. +@item no-time +@samp{-E} in @code{gprof}. -@item file-prefix -@samp{-b} in Bison. +@item no-timestamp +@samp{-m} in @code{shar}. -@item file-type -@samp{-F} in @code{ls}. +@item no-validate +Used in @code{makeinfo}. -@item files-from -@samp{-T} in @code{tar}. +@item no-warn +Used in various programs to inhibit warnings. -@item fill-column -Used in Makeinfo. +@item node +@samp{-n} in @code{info}. -@item flag-truncation -@samp{-F} in @code{ptx}. +@item nodename +@samp{-n} in @code{uname}. -@item fixed-output-files -@samp{-y} in Bison. +@item nonmatching +@samp{-f} in @code{cpio}. -@item follow -@samp{-f} in @code{tail}. +@item nstuff +@samp{-n} in @code{objdump}. -@item footnote-style -Used in Makeinfo. +@item null +@samp{-0} in @code{xargs}. -@item force -@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. +@item number +@samp{-n} in @code{cat}. -@item force-prefix -@samp{-F} in @code{shar}. +@item number-nonblank +@samp{-b} in @code{cat}. -@item format -Used in @code{ls}, @code{time}, and @code{ptx}. +@item numeric-sort +@samp{-n} in @code{nm}. -@item freeze-state -@samp{-F} in @code{m4}. +@item numeric-uid-gid +@samp{-n} in @code{cpio} and @code{ls}. -@item fullname +@item nx Used in GDB. -@item gap-size -@samp{-g} in @code{ptx}. +@item old-archive +@samp{-o} in @code{tar}. -@item get -@samp{-x} in @code{tar}. +@item old-file +@samp{-o} in Make. -@item graphic -@samp{-i} in @code{ul}. +@item one-file-system +@samp{-l} in @code{tar}, @code{cp}, and @code{du}. -@item graphics -@samp{-g} in @code{recode}. +@item only-file +@samp{-o} in @code{ptx}. -@item group -@samp{-g} in @code{install}. +@item only-prof +@samp{-f} in @code{gprof}. -@item gzip -@samp{-z} in @code{tar} and @code{shar}. +@item only-time +@samp{-F} in @code{gprof}. -@item hashsize -@samp{-H} in @code{m4}. +@item output +In various programs, specify the output file name. -@item header -@samp{-h} in @code{objdump} and @code{recode} +@item output-prefix +@samp{-o} in @code{shar}. -@item heading -@samp{-H} in @code{who}. +@item override +@samp{-o} in @code{rm}. -@item help -Used to ask for brief usage information. +@item overwrite +@samp{-c} in @code{unshar}. -@item here-delimiter -@samp{-d} in @code{shar}. +@item owner +@samp{-o} in @code{install}. -@item hide-control-chars -@samp{-q} in @code{ls}. +@item paginate +@samp{-l} in @code{diff}. -@item idle -@samp{-u} in @code{who}. +@item paragraph-indent +Used in @code{makeinfo}. -@item ifdef -@samp{-D} in @code{diff}. +@item parents +@samp{-p} in @code{mkdir} and @code{rmdir}. -@item ignore -@samp{-I} in @code{ls}; -@samp{-x} in @code{recode}. +@item pass-all +@samp{-p} in @code{ul}. -@item ignore-all-space -@samp{-w} in @code{diff}. +@item pass-through +@samp{-p} in @code{cpio}. -@item ignore-backups -@samp{-B} in @code{ls}. +@item port +@samp{-P} in @code{finger}. -@item ignore-blank-lines -@samp{-B} in @code{diff}. +@item portability +@samp{-c} in @code{cpio} and @code{tar}. -@item ignore-case -@samp{-f} in @code{look} and @code{ptx}; -@samp{-i} in @code{diff} and @code{wdiff}. +@item posix +Used in @code{gawk}. -@item ignore-errors -@samp{-i} in Make. +@item prefix-builtins +@samp{-P} in @code{m4}. -@item ignore-file -@samp{-i} in @code{ptx}. +@item prefix +@samp{-f} in @code{csplit}. -@item ignore-indentation -@samp{-I} in @code{etags}. +@item preserve +Used in @code{tar} and @code{cp}. -@item ignore-init-file -@samp{-f} in Oleo. +@item preserve-environment +@samp{-p} in @code{su}. + +@item preserve-modification-time +@samp{-m} in @code{cpio}. + +@item preserve-order +@samp{-s} in @code{tar}. + +@item preserve-permissions +@samp{-p} in @code{tar}. + +@item print +@samp{-l} in @code{diff}. -@item ignore-interrupts -@samp{-i} in @code{tee}. +@item print-chars +@samp{-L} in @code{cmp}. -@item ignore-matching-lines -@samp{-I} in @code{diff}. +@item print-data-base +@samp{-p} in Make. -@item ignore-space-change -@samp{-b} in @code{diff}. +@item print-directory +@samp{-w} in Make. -@item ignore-zeros -@samp{-i} in @code{tar}. +@item print-file-name +@samp{-o} in @code{nm}. -@item include -@samp{-i} in @code{etags}; -@samp{-I} in @code{m4}. +@item print-symdefs +@samp{-s} in @code{nm}. -@item include-dir -@samp{-I} in Make. +@item printer +@samp{-p} in @code{wdiff}. -@item incremental -@samp{-G} in @code{tar}. +@item prompt +@samp{-p} in @code{ed}. -@item info -@samp{-i}, @samp{-l}, and @samp{-m} in Finger. +@item query-user +@samp{-X} in @code{shar}. -@item initial -@samp{-i} in @code{expand}. +@item question +@samp{-q} in Make. -@item initial-tab -@samp{-T} in @code{diff}. +@item quiet +Used in many programs to inhibit the usual output. @strong{Note:} every +program accepting @samp{--quiet} should accept @samp{--silent} as a +synonym. -@item inode -@samp{-i} in @code{ls}. +@item quiet-unshar +@samp{-Q} in @code{shar} -@item interactive -@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; -@samp{-e} in @code{m4}; -@samp{-p} in @code{xargs}; -@samp{-w} in @code{tar}. +@item quote-name +@samp{-Q} in @code{ls}. -@item intermix-type -@samp{-p} in @code{shar}. +@item rcs +@samp{-n} in @code{diff}. -@item jobs -@samp{-j} in Make. +@item re-interval +Used in @code{gawk}. -@item just-print -@samp{-n} in Make. +@item read-full-blocks +@samp{-B} in @code{tar}. -@item keep-going -@samp{-k} in Make. +@item readnow +Used in GDB. -@item keep-files -@samp{-k} in @code{csplit}. +@item recon +@samp{-n} in Make. -@item kilobytes -@samp{-k} in @code{du} and @code{ls}. +@item record-number +@samp{-R} in @code{tar}. -@item language -@samp{-l} in @code{etags}. +@item recursive +Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, +and @code{rm}. -@item less-mode -@samp{-l} in @code{wdiff}. +@item reference-limit +Used in @code{makeinfo}. -@item level-for-gzip -@samp{-g} in @code{shar}. +@item references +@samp{-r} in @code{ptx}. -@item line-bytes -@samp{-C} in @code{split}. +@item regex +@samp{-r} in @code{tac} and @code{etags}. -@item lines -Used in @code{split}, @code{head}, and @code{tail}. +@item release +@samp{-r} in @code{uname}. -@item link -@samp{-l} in @code{cpio}. +@item reload-state +@samp{-R} in @code{m4}. -@item lint -Used in gawk (no corresponding single-letter option). +@item relocation +@samp{-r} in @code{objdump}. -@item list -@samp{-t} in @code{cpio}; -@samp{-l} in @code{recode}. +@item rename +@samp{-r} in @code{cpio}. -@item list -@samp{-t} in @code{tar}. +@item replace +@samp{-i} in @code{xargs}. -@item literal -@samp{-N} in @code{ls}. +@item report-identical-files +@samp{-s} in @code{diff}. -@item load-average -@samp{-l} in Make. +@item reset-access-time +@samp{-a} in @code{cpio}. -@item login -Used in @code{su}. +@item reverse +@samp{-r} in @code{ls} and @code{nm}. -@item machine -No listing of which programs already use this; -someone should check to -see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. +@item reversed-ed +@samp{-f} in @code{diff}. -@item macro-name -@samp{-M} in @code{ptx}. +@item right-side-defs +@samp{-R} in @code{ptx}. -@item mail -@samp{-m} in @code{hello} and @code{uname}. +@item same-order +@samp{-s} in @code{tar}. -@item make-directories -@samp{-d} in @code{cpio}. +@item same-permissions +@samp{-p} in @code{tar}. -@item makefile -@samp{-f} in Make. +@item save +@samp{-g} in @code{stty}. -@item mapped +@item se Used in GDB. -@item max-args -@samp{-n} in @code{xargs}. - -@item max-chars -@samp{-n} in @code{xargs}. +@item sentence-regexp +@samp{-S} in @code{ptx}. -@item max-lines -@samp{-l} in @code{xargs}. +@item separate-dirs +@samp{-S} in @code{du}. -@item max-load -@samp{-l} in Make. +@item separator +@samp{-s} in @code{tac}. -@item max-procs -@samp{-P} in @code{xargs}. +@item sequence +Used by @code{recode} to chose files or pipes for sequencing passes. -@item mesg -@samp{-T} in @code{who}. +@item shell +@samp{-s} in @code{su}. -@item message -@samp{-T} in @code{who}. +@item show-all +@samp{-A} in @code{cat}. -@item minimal -@samp{-d} in @code{diff}. +@item show-c-function +@samp{-p} in @code{diff}. -@item mixed-uuencode -@samp{-M} in @code{shar}. +@item show-ends +@samp{-E} in @code{cat}. -@item mode -@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. +@item show-function-line +@samp{-F} in @code{diff}. -@item modification-time -@samp{-m} in @code{tar}. +@item show-tabs +@samp{-T} in @code{cat}. -@item multi-volume -@samp{-M} in @code{tar}. +@item silent +Used in many programs to inhibit the usual output. +@strong{Note:} every program accepting +@samp{--silent} should accept @samp{--quiet} as a synonym. -@item name-prefix -@samp{-a} in Bison. +@item size +@samp{-s} in @code{ls}. -@item nesting-limit -@samp{-L} in @code{m4}. +@item sort +Used in @code{ls}. -@item net-headers -@samp{-a} in @code{shar}. +@item source +@samp{-W source} in @code{gawk}. -@item new-file -@samp{-W} in Make. +@item sparse +@samp{-S} in @code{tar}. -@item no-builtin-rules -@samp{-r} in Make. +@item speed-large-files +@samp{-H} in @code{diff}. -@item no-character-count -@samp{-w} in @code{shar}. +@item split-at +@samp{-E} in @code{unshar}. -@item no-check-existing -@samp{-x} in @code{shar}. +@item split-size-limit +@samp{-L} in @code{shar}. -@item no-common -@samp{-3} in @code{wdiff}. +@item squeeze-blank +@samp{-s} in @code{cat}. -@item no-create -@samp{-c} in @code{touch}. +@item start-delete +@samp{-w} in @code{wdiff}. -@item no-defines -@samp{-D} in @code{etags}. +@item start-insert +@samp{-y} in @code{wdiff}. -@item no-deleted -@samp{-1} in @code{wdiff}. +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. -@item no-dereference -@samp{-d} in @code{cp}. +@item statistics +@samp{-s} in @code{wdiff}. -@item no-inserted -@samp{-2} in @code{wdiff}. +@item stdin-file-list +@samp{-S} in @code{shar}. -@item no-keep-going +@item stop @samp{-S} in Make. -@item no-lines -@samp{-l} in Bison. +@item strict +@samp{-s} in @code{recode}. -@item no-piping -@samp{-P} in @code{shar}. +@item strip +@samp{-s} in @code{install}. -@item no-prof -@samp{-e} in @code{gprof}. +@item strip-all +@samp{-s} in @code{strip}. -@item no-regex -@samp{-R} in @code{etags}. +@item strip-debug +@samp{-S} in @code{strip}. -@item no-sort -@samp{-p} in @code{nm}. +@item submitter +@samp{-s} in @code{shar}. -@item no-split -Used in Makeinfo. +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. -@item no-static -@samp{-a} in @code{gprof}. +@item suffix-format +@samp{-b} in @code{csplit}. -@item no-time -@samp{-E} in @code{gprof}. +@item sum +@samp{-s} in @code{gprof}. -@item no-timestamp -@samp{-m} in @code{shar}. +@item summarize +@samp{-s} in @code{du}. -@item no-validate -Used in Makeinfo. +@item symbolic +@samp{-s} in @code{ln}. -@item no-warn -Used in various programs to inhibit warnings. +@item symbols +Used in GDB and @code{objdump}. -@item node -@samp{-n} in @code{info}. +@item synclines +@samp{-s} in @code{m4}. -@item nodename -@samp{-n} in @code{uname}. +@item sysname +@samp{-s} in @code{uname}. -@item nonmatching -@samp{-f} in @code{cpio}. +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. -@item nstuff -@samp{-n} in @code{objdump}. +@item tabsize +@samp{-T} in @code{ls}. -@item null -@samp{-0} in @code{xargs}. +@item terminal +@samp{-T} in @code{tput} and @code{ul}. +@samp{-t} in @code{wdiff}. -@item number -@samp{-n} in @code{cat}. +@item text +@samp{-a} in @code{diff}. -@item number-nonblank -@samp{-b} in @code{cat}. +@item text-files +@samp{-T} in @code{shar}. -@item numeric-sort -@samp{-n} in @code{nm}. +@item time +Used in @code{ls} and @code{touch}. -@item numeric-uid-gid -@samp{-n} in @code{cpio} and @code{ls}. +@item to-stdout +@samp{-O} in @code{tar}. -@item nx -Used in GDB. +@item total +@samp{-c} in @code{du}. -@item old-archive -@samp{-o} in @code{tar}. +@item touch +@samp{-t} in Make, @code{ranlib}, and @code{recode}. -@item old-file -@samp{-o} in Make. +@item trace +@samp{-t} in @code{m4}. -@item one-file-system -@samp{-l} in @code{tar}, @code{cp}, and @code{du}. +@item traditional +@samp{-t} in @code{hello}; +@samp{-W traditional} in @code{gawk}; +@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. -@item only-file -@samp{-o} in @code{ptx}. +@item tty +Used in GDB. -@item only-prof -@samp{-f} in @code{gprof}. +@item typedefs +@samp{-t} in @code{ctags}. -@item only-time -@samp{-F} in @code{gprof}. +@item typedefs-and-c++ +@samp{-T} in @code{ctags}. -@item output -In various programs, specify the output file name. +@item typeset-mode +@samp{-t} in @code{ptx}. -@item output-prefix -@samp{-o} in @code{shar}. +@item uncompress +@samp{-z} in @code{tar}. -@item override -@samp{-o} in @code{rm}. +@item unconditional +@samp{-u} in @code{cpio}. -@item overwrite -@samp{-c} in @code{unshar}. +@item undefine +@samp{-U} in @code{m4}. -@item owner -@samp{-o} in @code{install}. +@item undefined-only +@samp{-u} in @code{nm}. -@item paginate -@samp{-l} in @code{diff}. +@item update +@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. -@item paragraph-indent -Used in Makeinfo. +@item usage +Used in @code{gawk}; same as @samp{--help}. -@item parents -@samp{-p} in @code{mkdir} and @code{rmdir}. +@item uuencode +@samp{-B} in @code{shar}. -@item pass-all -@samp{-p} in @code{ul}. +@item vanilla-operation +@samp{-V} in @code{shar}. -@item pass-through -@samp{-p} in @code{cpio}. +@item verbose +Print more information about progress. Many programs support this. -@item port -@samp{-P} in @code{finger}. +@item verify +@samp{-W} in @code{tar}. -@item portability -@samp{-c} in @code{cpio} and @code{tar}. +@item version +Print the version number. -@item posix -Used in gawk (no corresponding single-letter option). +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. -@item prefix-builtins -@samp{-P} in @code{m4}. +@item vgrind +@samp{-v} in @code{ctags}. -@item prefix -@samp{-f} in @code{csplit}. +@item volume +@samp{-V} in @code{tar}. -@item preserve -Used in @code{tar} and @code{cp}. +@item what-if +@samp{-W} in Make. -@item preserve-environment -@samp{-p} in @code{su}. +@item whole-size-limit +@samp{-l} in @code{shar}. -@item preserve-modification-time -@samp{-m} in @code{cpio}. +@item width +@samp{-w} in @code{ls} and @code{ptx}. -@item preserve-order -@samp{-s} in @code{tar}. +@item word-regexp +@samp{-W} in @code{ptx}. -@item preserve-permissions -@samp{-p} in @code{tar}. +@item writable +@samp{-T} in @code{who}. -@item print -@samp{-l} in @code{diff}. +@item zeros +@samp{-z} in @code{gprof}. +@end table -@item print-chars -@samp{-L} in @code{cmp}. +@node Memory Usage +@section Memory Usage -@item print-data-base -@samp{-p} in Make. +If it 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. + +However, for programs such as @code{cat} or @code{tail}, that can +usefully operate on very large files, it is important to avoid using a +technique that would artificially limit the size of files it can handle. +If a program works by lines and could be applied to arbitrary +user-supplied input files, it should keep only a line in memory, because +this is not very hard and users will want to be able to operate on input +files that are bigger than will fit in core all at once. -@item print-directory -@samp{-w} in Make. +If your program creates complicated data structures, just make them in +core and give a fatal error if @code{malloc} returns zero. -@item print-file-name -@samp{-o} in @code{nm}. +@node Writing C +@chapter Making The Best Use of C -@item print-symdefs -@samp{-s} in @code{nm}. +This @value{CHAPTER} provides advice on how best to use the C language +when writing GNU software. -@item printer -@samp{-p} in @code{wdiff}. +@menu +* Formatting:: Formatting Your Source Code +* Comments:: Commenting Your Work +* Syntactic Conventions:: Clean Use of C Constructs +* Names:: Naming Variables and Functions +* System Portability:: Portability between different operating systems +* CPU Portability:: Supporting the range of CPU types +* System Functions:: Portability and ``standard'' library functions +@end menu -@item prompt -@samp{-p} in @code{ed}. +@node Formatting +@section Formatting Your Source Code -@item query-user -@samp{-X} in @code{shar}. +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 +for open-braces in column zero to find the beginnings of C functions. +These tools will not work on code not formatted that way. -@item question -@samp{-q} in Make. +It is also important for function definitions to start the name of the +function in column zero. This helps people to search for function +definitions, and may also help certain tools recognize them. Thus, +the proper format is this: -@item quiet -Used in many programs to inhibit the usual output. @strong{Note:} every -program accepting @samp{--quiet} should accept @samp{--silent} as a -synonym. +@example +static char * +concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; +@{ /* Open brace in column zero here */ + @dots{} +@} +@end example -@item quiet-unshar -@samp{-Q} in @code{shar} +@noindent +or, if you want to use @sc{ansi} C, format the definition like this: -@item quote-name -@samp{-Q} in @code{ls}. +@example +static char * +concat (char *s1, char *s2) +@{ + @dots{} +@} +@end example -@item rcs -@samp{-n} in @code{diff}. +In @sc{ansi} C, if the arguments don't fit nicely on one line, +split it like this: -@item read-full-blocks -@samp{-B} in @code{tar}. +@example +int +lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) +@dots{} +@end example -@item readnow -Used in GDB. +For the body of the function, we prefer code formatted like this: -@item recon -@samp{-n} in Make. +@example +if (x < foo (y, z)) + haha = bar[4] + 5; +else + @{ + while (z) + @{ + haha += foo (z, z); + z--; + @} + return ++x + bar (); + @} +@end example -@item record-number -@samp{-R} in @code{tar}. +We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. -@item recursive -Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, -and @code{rm}. +When you split an expression into multiple lines, split it +before an operator, not after one. Here is the right way: -@item reference-limit -Used in Makeinfo. +@example +if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) +@end example -@item references -@samp{-r} in @code{ptx}. +Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: -@item regex -@samp{-r} in @code{tac} and @code{etags}. +@example +mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); +@end example -@item release -@samp{-r} in @code{uname}. +Instead, use extra parentheses so that the indentation shows the nesting: -@item reload-state -@samp{-R} in @code{m4}. +@example +mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); +@end example -@item relocation -@samp{-r} in @code{objdump}. +Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, +but Emacs would mess it up: -@item rename -@samp{-r} in @code{cpio}. +@example +v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; +@end example -@item replace -@samp{-i} in @code{xargs}. +But adding a set of parentheses solves the problem: -@item report-identical-files -@samp{-s} in @code{diff}. +@example +v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); +@end example -@item reset-access-time -@samp{-a} in @code{cpio}. +Format do-while statements like this: -@item reverse -@samp{-r} in @code{ls} and @code{nm}. +@example +do + @{ + a = foo (a); + @} +while (a > 0); +@end example -@item reversed-ed -@samp{-f} in @code{diff}. +Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. -@item right-side-defs -@samp{-R} in @code{ptx}. -@item same-order -@samp{-s} in @code{tar}. +@node Comments +@section Commenting Your Work -@item same-permissions -@samp{-p} in @code{tar}. +Every program should start with a comment saying briefly what it is for. +Example: @samp{fmt - filter for simple filling of text}. -@item save -@samp{-g} in @code{stty}. +Please put a comment on each function saying what the function does, +what sorts of arguments it gets, and what the possible values of +arguments mean and are used for. It is not necessary to duplicate in +words the meaning of the C argument declarations, if a C type is being +used in its customary fashion. If there is anything nonstandard about +its use (such as an argument of type @code{char *} which is really the +address of the second character of a string, not the first), or any +possible values that would not work the way one would expect (such as, +that strings containing newlines are not guaranteed to work), be sure +to say so. -@item se -Used in GDB. +Also explain the significance of the return value, if there is one. -@item sentence-regexp -@samp{-S} in @code{ptx}. +Please put two spaces after the end of a sentence in your comments, so +that the Emacs sentence commands will work. Also, please write +complete sentences and capitalize the first word. If a lower-case +identifier comes at the beginning of a sentence, don't capitalize it! +Changing the spelling makes it a different identifier. If you don't +like starting a sentence with a lower case letter, write the sentence +differently (e.g., ``The identifier lower-case is @dots{}''). -@item separate-dirs -@samp{-S} in @code{du}. +The comment on a function is much clearer if you use the argument +names to speak about the argument values. The variable name itself +should be lower case, but write it in upper case when you are speaking +about the value rather than the variable itself. Thus, ``the inode +number NODE_NUM'' rather than ``an inode''. -@item separator -@samp{-s} in @code{tac}. +There is usually no purpose in restating the name of the function in +the comment before it, because the reader can see that for himself. +There might be an exception when the comment is so long that the function +itself would be off the bottom of the screen. -@item sequence -Used by @code{recode} to chose files or pipes for sequencing passes. +There should be a comment on each static variable as well, like this: -@item shell -@samp{-s} in @code{su}. +@example +/* Nonzero means truncate lines in the display; + zero means continue them. */ +int truncate_lines; +@end example -@item show-all -@samp{-A} in @code{cat}. +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 +its sense}. @samp{#else} should have a comment describing the condition +@emph{and sense} of the code that follows. For example: -@item show-c-function -@samp{-p} in @code{diff}. +@example +@group +#ifdef foo + @dots{} +#else /* not foo */ + @dots{} +#endif /* not foo */ +@end group +@end example -@item show-ends -@samp{-E} in @code{cat}. +@noindent +but, by contrast, write the comments this way for a @samp{#ifndef}: -@item show-function-line -@samp{-F} in @code{diff}. +@example +@group +#ifndef foo + @dots{} +#else /* foo */ + @dots{} +#endif /* foo */ +@end group +@end example -@item show-tabs -@samp{-T} in @code{cat}. -@item silent -Used in many programs to inhibit the usual output. -@strong{Note:} every program accepting -@samp{--silent} should accept @samp{--quiet} as a synonym. +@node Syntactic Conventions +@section Clean Use of C Constructs -@item size -@samp{-s} in @code{ls}. +Please explicitly declare all arguments to functions. +Don't omit them just because they are @code{int}s. -@item sort -Used in @code{ls}. +Declarations of external functions and functions to appear later in the +source file should all go in one place near the beginning of the file +(somewhere before the first function definition in the file), or else +should go in a header file. Don't put @code{extern} declarations inside +functions. -@item source -Used in gawk (no corresponding single-letter option). +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 +variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. -@item sparse -@samp{-S} in @code{tar}. +Don't use local variables or parameters that shadow global identifiers. -@item speed-large-files -@samp{-H} in @code{diff}. +Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead +of this: -@item split-at -@samp{-E} in @code{unshar}. +@example +@group +int foo, + bar; +@end group +@end example -@item split-size-limit -@samp{-L} in @code{shar}. +@noindent +write either this: -@item squeeze-blank -@samp{-s} in @code{cat}. +@example +int foo, bar; +@end example -@item start-delete -@samp{-w} in @code{wdiff}. +@noindent +or this: -@item start-insert -@samp{-y} in @code{wdiff}. +@example +int foo; +int bar; +@end example -@item starting-file -Used in @code{tar} and @code{diff} to specify which file within -a directory to start processing with. +@noindent +(If they are global variables, each should have a comment preceding it +anyway.) -@item statistics -@samp{-s} in @code{wdiff}. +When you have an @code{if}-@code{else} statement nested in another +@code{if} statement, always put braces around the @code{if}-@code{else}. +Thus, never write like this: -@item stdin-file-list -@samp{-S} in @code{shar}. +@example +if (foo) + if (bar) + win (); + else + lose (); +@end example -@item stop -@samp{-S} in Make. +@noindent +always like this: -@item strict -@samp{-s} in @code{recode}. +@example +if (foo) + @{ + if (bar) + win (); + else + lose (); + @} +@end example -@item strip -@samp{-s} in @code{install}. +If you have an @code{if} statement nested inside of an @code{else} +statement, either write @code{else if} on one line, like this, -@item strip-all -@samp{-s} in @code{strip}. +@example +if (foo) + @dots{} +else if (bar) + @dots{} +@end example -@item strip-debug -@samp{-S} in @code{strip}. +@noindent +with its @code{then}-part indented like the preceding @code{then}-part, +or write the nested @code{if} within braces like this: -@item submitter -@samp{-s} in @code{shar}. +@example +if (foo) + @dots{} +else + @{ + if (bar) + @dots{} + @} +@end example -@item suffix -@samp{-S} in @code{cp}, @code{ln}, @code{mv}. +Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately +and then use it to declare the variables or typedefs. -@item suffix-format -@samp{-b} in @code{csplit}. +Try to avoid assignments inside @code{if}-conditions. For example, +don't write this: -@item sum -@samp{-s} in @code{gprof}. +@example +if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); +@end example -@item summarize -@samp{-s} in @code{du}. +@noindent +instead, write this: -@item symbolic -@samp{-s} in @code{ln}. +@example +foo = (char *) malloc (sizeof *foo); +if (foo == 0) + fatal ("virtual memory exhausted"); +@end example -@item symbols -Used in GDB and @code{objdump}. +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. -@item synclines -@samp{-s} in @code{m4}. +@node Names +@section Naming Variables and Functions -@item sysname -@samp{-s} in @code{uname}. +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 +that follow a uniform convention. -@item tabs -@samp{-t} in @code{expand} and @code{unexpand}. +For example, you should use names like @code{ignore_space_change_flag}; +don't use names like @code{iCantReadThis}. -@item tabsize -@samp{-T} in @code{ls}. +Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after +the option-letter. A comment should state both the exact meaning of +the option and its letter. For example, -@item terminal -@samp{-T} in @code{tput} and @code{ul}. -@samp{-t} in @code{wdiff}. +@example +@group +/* Ignore changes in horizontal whitespace (-b). */ +int ignore_space_change_flag; +@end group +@end example -@item text -@samp{-a} in @code{diff}. +When you want to define names with constant integer values, use +@code{enum} rather than @samp{#define}. GDB knows about enumeration +constants. -@item text-files -@samp{-T} in @code{shar}. +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 name conflicts if the +files were loaded onto an MS-DOS file system---something you may or may +not care about. -@item time -Used in @code{ls} and @code{touch}. +@node System Portability +@section Portability between System Types -@item to-stdout -@samp{-O} in @code{tar}. +In the Unix world, ``portability'' refers to porting to different Unix +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, +compiled with the GNU C compiler, on various types of @sc{cpu}. The +amount and kinds of variation among GNU systems on different @sc{cpu}s +will be comparable to the variation among Linux-based GNU systems or +among BSD systems today. So the kinds of portability that are absolutely +necessary are quite limited. + +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. + +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 +because most of the programs that need such knowledge have already been +written. -@item total -@samp{-c} in @code{du}. +Avoid using the format of semi-internal data bases (e.g., directories) +when there is a higher-level alternative (@code{readdir}). -@item touch -@samp{-t} in Make, @code{ranlib}, and @code{recode}. +As for systems that are not like Unix, such as MSDOS, Windows, the +Macintosh, VMS, and MVS, supporting them is usually so much work that it +is better if you don't. + +The planned GNU kernel is not finished yet, but you can tell which +facilities it will provide by looking at the GNU C Library Manual. The +GNU kernel is based on Mach, so the features of Mach will also be +available. However, if you use Mach features, you'll probably have +trouble debugging your program today. + +@node CPU Portability +@section Portability between @sc{cpu}s + +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. +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. + +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: -@item trace -@samp{-t} in @code{m4}. +@example +int c; +@dots{} +while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); +@end example -@item traditional -@samp{-t} in @code{hello}; -@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. +When calling functions, you need not worry about the difference between +pointers of various types, or between pointers an integers. On most +machines, there's no difference anyway. As for the few machines where +there is a difference, all of them support @sc{ansi} C, so you can use +prototypes (conditionalized to be active only in @sc{ansi} C) to make +the code work on those systems. -@item tty -Used in GDB. +In certain cases, it is ok to pass integer and pointer arguments +indiscriminately to the same function, and use no prototype on any +system. For example, many GNU programs have error-reporting functions +that pass their arguments along to @code{printf} and friends: -@item typedefs -@samp{-t} in @code{ctags}. +@example +error (s, a1, a2, a3) + char *s; + int a1, a2, a3; +@{ + fprintf (stderr, "error: "); + fprintf (stderr, s, a1, a2, a3); +@} +@end example -@item typedefs-and-c++ -@samp{-T} in @code{ctags}. +@noindent +In practice, this works on all machines, and it is much simpler than any +``correct'' alternative. -@item typeset-mode -@samp{-t} in @code{ptx}. +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. -@item uncompress -@samp{-z} in @code{tar}. +@node System Functions +@section Calling System Functions -@item unconditional -@samp{-u} in @code{cpio}. +C implementations differ substantially. @sc{ansi} C reduces but does not +eliminate the incompatibilities; meanwhile, many users wish to compile +GNU software with pre-@sc{ansi} compilers. This chapter gives +recommendations for how to use the more or less standard C library +functions to avoid unnecessary loss of portability. -@item undefine -@samp{-U} in @code{m4}. +@itemize @bullet +@item +Don't use the value of @code{sprintf}. It returns the number of +characters written on some systems, but not on all systems. -@item undefined-only -@samp{-u} in @code{nm}. +@item +Don't declare system functions explicitly. -@item update -@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. +Almost any declaration for a system function is wrong on some system. +To minimize conflicts, leave it to the system header files to declare +system functions. If the headers don't declare a function, let it +remain undeclared. -@item usage -Used in gawk (no corresponding single-letter option). +While it may seem unclean to use a function without declaring it, in +practice this works fine for most system library functions on the +systems where this really happens; thus, the disadvantage is only +theoretical. By contrast, actual declarations have frequently caused +actual conflicts. -@item uuencode -@samp{-B} in @code{shar}. +@item +If you must declare a system function, don't specify the argument types. +Use an old-style declaration, not an @sc{ansi} prototype. The more you +specify about the function, the more likely a conflict. -@item vanilla-operation -@samp{-V} in @code{shar}. +@item +In particular, don't unconditionally declare @code{malloc} or +@code{realloc}. -@item verbose -Print more information about progress. Many programs support this. +Most GNU programs use those functions just once, in functions +conventionally named @code{xmalloc} and @code{xrealloc}. These +functions call @code{malloc} and @code{realloc}, respectively, and +check the results. -@item verify -@samp{-W} in @code{tar}. +Because @code{xmalloc} and @code{xrealloc} are defined in your program, +you can declare them in other files without any risk of type conflict. -@item version -Print the version number. +On most systems, @code{int} is the same length as a pointer; thus, the +calls to @code{malloc} and @code{realloc} work fine. For the few +exceptional systems (mostly 64-bit machines), you can use +@strong{conditionalized} declarations of @code{malloc} and +@code{realloc}---or put these declarations in configuration files +specific to those systems. -@item version-control -@samp{-V} in @code{cp}, @code{ln}, @code{mv}. +@item +The string functions require special treatment. Some Unix systems have +a header file @file{string.h}; others have @file{strings.h}. Neither +file name is portable. There are two things you can do: use Autoconf to +figure out which file to include, or don't include either file. -@item vgrind -@samp{-v} in @code{ctags}. +@item +If you don't include either strings file, you can't get declarations for +the string functions from the header file in the usual way. -@item volume -@samp{-V} in @code{tar}. +That causes less of a problem than you might think. The newer @sc{ansi} +string functions should be avoided anyway because many systems still +don't support them. The string functions you can use are these: -@item what-if -@samp{-W} in Make. +@example +strcpy strncpy strcat strncat +strlen strcmp strncmp +strchr strrchr +@end example -@item whole-size-limit -@samp{-l} in @code{shar}. +The copy and concatenate functions work fine without a declaration as +long as you don't use their values. Using their values without a +declaration fails on systems where the width of a pointer differs from +the width of @code{int}, and perhaps in other cases. It is trivial to +avoid using their values, so do that. -@item width -@samp{-w} in @code{ls} and @code{ptx}. +The compare functions and @code{strlen} work fine without a declaration +on most systems, possibly all the ones that GNU software runs on. +You may find it necessary to declare them @strong{conditionally} on a +few systems. -@item word-regexp -@samp{-W} in @code{ptx}. +The search functions must be declared to return @code{char *}. Luckily, +there is no variation in the data type they return. But there is +variation in their names. Some systems give these functions the names +@code{index} and @code{rindex}; other systems use the names +@code{strchr} and @code{strrchr}. Some systems support both pairs of +names, but neither pair works on all systems. -@item writable -@samp{-T} in @code{who}. +You should pick a single pair of names and use it throughout your +program. (Nowadays, it is better to choose @code{strchr} and +@code{strrchr} for new programs, since those are the standard @sc{ansi} +names.) Declare both of those names as functions returning @code{char +*}. On systems which don't support those names, define them as macros +in terms of the other pair. For example, here is what to put at the +beginning of your file (or in a header) if you want to use the names +@code{strchr} and @code{strrchr} throughout: -@item zeros -@samp{-z} in @code{gprof}. +@example +#ifndef HAVE_STRCHR +#define strchr index +#endif +#ifndef HAVE_STRRCHR +#define strrchr rindex +#endif -@end table -@c longopts end here (keyword for isearch) +char *strchr (); +char *strrchr (); +@end example +@end itemize + +Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are +macros defined in systems where the corresponding functions exist. +One way to get them properly defined is to use Autoconf. @node Documentation @chapter Documenting Programs @@ -2356,9 +2251,10 @@ * GNU Manuals:: Writing proper manuals. * Manual Structure Details:: Specific structure conventions. * NEWS File:: NEWS files supplement manuals. +* Change Logs:: Recording Changes * Man Pages:: Man pages are secondary. * Reading other Manuals:: How far you can go in learning - from other manuals. + from other manuals. @end menu @node GNU Manuals @@ -2366,8 +2262,8 @@ 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 version in the Emacs Info subsystem (@kbd{C-h -i}). +either the hardcopy, or the on-line version available through +@code{info} or the Emacs Info subsystem (@kbd{C-h i}). The manual 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 @@ -2381,7 +2277,7 @@ should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. -That is not as hard as it sounds at first. Arrange each chapter as a +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 text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a @@ -2404,7 +2300,7 @@ @section Manual Structure Details The title page of the manual should state the version of the program -which the manual applies to. The Top node of the manual should also +to which the manual applies. The Top node of the manual should also contain this information. If the manual is changing more frequently than or independent of the program, also state a version number for the manual in both of these places. @@ -2442,27 +2338,114 @@ into a file named @file{ONEWS} and put a note at the end referring the user to that file. +@node Change Logs +@section Change Logs + +Keep a change log for each directory, describing the changes made to +source files in that directory. The purpose of this is so that people +investigating bugs in the future will know about the changes that +might have introduced the bug. Often a new bug can be found by +looking at what was recently changed. More importantly, change logs +can help eliminate conceptual inconsistencies between different parts +of a program; they can give you a history of how the conflicting +concepts arose. + +Use the Emacs command @kbd{M-x add-change-log-entry} to start a new +entry in the +change log. An entry should have an asterisk, the name of the changed +file, and then in parentheses the name of the changed functions, +variables or whatever, followed by a colon. Then describe the changes +you made to that function or variable. + +Separate unrelated entries with blank lines. When two entries +represent parts of the same change, so that they work together, then +don't put blank lines between them. Then you can omit the file name +and the asterisk when successive entries are in the same file. + +Here are some examples: + +@example +* register.el (insert-register): Return nil. +(jump-to-register): Likewise. + +* sort.el (sort-subr): Return nil. + +* tex-mode.el (tex-bibtex-file, tex-file, tex-region): +Restart the tex shell if process is gone or stopped. +(tex-shell-running): New function. + +* 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. +@end example + +It's important to name the changed function or variable in full. Don't +abbreviate function or variable names, and don't combine them. +Subsequent maintainers will often +search for a function name to find all the change log entries that +pertain to it; if you abbreviate the name, they won't find it when they +search. For example, some people are tempted to abbreviate groups of +function names by writing @samp{* register.el +(@{insert,jump-to@}-register)}; this is not a good idea, since searching +for @code{jump-to-register} or @code{insert-register} would not find the +entry. + +There's no need to describe the full purpose of the changes or how they +work together. It is better to put such explanations in comments in the +code. That's why just ``New function'' is enough; there is a comment +with the function in the source to explain what it does. + +However, sometimes it is useful to write one line to describe the +overall purpose of a large batch of changes. + +You can think of the change log as a conceptual ``undo list'' which +explains how earlier versions were different from the current version. +People can see the current version; they don't need the change log +to tell them what is in it. What they want from a change log is a +clear explanation of how the earlier version differed. + +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. Just write in +the entry for the function being called, ``All callers changed.'' + +When you change just comments or doc strings, it is enough to write an +entry for the file, without mentioning the functions. Write just, +``Doc fix.'' There's no need to keep a change log for documentation +files. This is because documentation is not susceptible to bugs that +are hard to fix. Documentation does not consist of parts that must +interact in a precisely engineered fashion; to correct an error, you +need not know the history of the erroneous passage. + @node Man Pages @section Man Pages -It is ok to supply a man page for the program as well as a Texinfo -manual if you wish to. But keep in mind that supporting a man page -requires continual effort, each time the program is changed. Any time -you spend on the man page is time taken away from more useful things you -could contribute. - -Thus, even if a user volunteers to donate a man page, you may find this -gift costly to accept. Unless you have time on your hands, it may be -better to refuse the man page unless the same volunteer agrees to take -full responsibility for maintaining it---so that you can wash your hands -of it entirely. If the volunteer ceases to do the job, then don't feel -obliged to pick it up yourself; it may be better to withdraw the man -page until another volunteer offers to carry on with it. - -Alternatively, if you expect the discrepancies to be small enough that -the man page remains useful, put a prominent note near the beginning of -the man page explaining that you don't maintain it and that the Texinfo -manual is more authoritative, and describing how to access the Texinfo +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. +It's your choice whether to include a man page in your program. + +When you make this decision, consider that supporting a man page +requires continual effort each time the program is changed. The time +you spend on the man page is time taken away from more useful work. + +For a simple program which changes little, updating the man page may be +a small job. Then there is little reason not to include a man page, if +you have one. + +For a large program that changes a great deal, updating a man page may +be a substantial burden. If a user offers to donate a man page, you may +find this gift costly to accept. It may be better to refuse the man +page unless the same person agrees to take full responsibility for +maintaining it---so that you can wash your hands of it entirely. If +this volunteer later ceases to do the job, then don't feel obliged to +pick it up yourself; it may be better to withdraw the man page from the +distribution until someone else agrees to update it. + +When a program changes only a little, you may feel that the +discrepancies are small enough that the man page remains useful without +updating. If so, put a prominent note near the beginning of the man +page explaining that you don't maintain it and that the Texinfo manual +is more authoritative. The note should say how to access the Texinfo documentation. @node Reading other Manuals @@ -2480,8 +2463,193 @@ documentation. Copying from free documentation may be ok; please check with the FSF about the individual case. +@node Managing Releases +@chapter The Release Process + +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 +that it can be configured to run on a variety of systems. Your Makefile +should conform to the GNU standards described below, and your directory +layout should also conform to the standards discussed below. Doing so +makes it easy to include your package into the larger framework of +all GNU software. + +@menu +* Configuration:: How Configuration Should Work +* Makefile Conventions:: Makefile Conventions +* Releases:: Making Releases +@end menu + +@node Configuration +@section How Configuration Should Work + +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. + +The @code{configure} script must record the configuration options so +that they affect compilation. + +One way to do this is to make a link from a standard name such as +@file{config.h} to the proper configuration file for the chosen system. +If you use this technique, the distribution should @emph{not} contain a +file named @file{config.h}. This is so that people won't be able to +build the program without configuring it first. + +Another thing that @code{configure} can do is to edit the Makefile. If +you do this, the distribution should @emph{not} contain a file named +@file{Makefile}. Instead, it should include a file @file{Makefile.in} which +contains the input used for editing. Once again, this is so that people +won't be able to build the program without configuring it first. + +If @code{configure} does write the @file{Makefile}, then @file{Makefile} +should have a target named @file{Makefile} which causes @code{configure} +to be rerun, setting up the same configuration that was set up last +time. The files that @code{configure} reads should be listed as +dependencies of @file{Makefile}. + +All the files which are output from the @code{configure} script should +have comments at the beginning explaining that they were generated +automatically using @code{configure}. This is so that users won't think +of trying to edit them by hand. + +The @code{configure} script should write a file named @file{config.status} +which describes which configuration options were specified when the +program was last configured. This file should be a shell script which, +if run, will recreate the same configuration. + +The @code{configure} script should accept an option of the form +@samp{--srcdir=@var{dirname}} to specify the directory where sources are found +(if it is not the current directory). This makes it possible to build +the program in a separate directory, so that the actual source directory +is not modified. + +If the user does not specify @samp{--srcdir}, then @code{configure} should +check both @file{.} and @file{..} to see if it can find the sources. If +it finds the sources in one of these places, it should use them from +there. Otherwise, it should report that it cannot find the sources, and +should exit with nonzero status. + +Usually the easy way to support @samp{--srcdir} is by editing a +definition of @code{VPATH} into the Makefile. Some rules may need to +refer explicitly to the specified source directory. To make this +possible, @code{configure} can add to the Makefile a variable named +@code{srcdir} whose value is precisely the specified directory. + +The @code{configure} script should also take an argument which specifies the +type of system to build the program for. This argument should look like +this: + +@example +@var{cpu}-@var{company}-@var{system} +@end example + +For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. + +The @code{configure} script needs to be able to decode all plausible +alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} +would be a valid alias. For many programs, @samp{vax-dec-ultrix} would +be an alias for @samp{vax-dec-bsd}, simply because the differences +between Ultrix and @sc{BSD} are rarely noticeable, but a few programs +might need to distinguish them. +@c Real 4.4BSD now runs on some Suns. + +There is a shell script called @file{config.sub} that you can use +as a subroutine to validate system types and canonicalize aliases. + +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: + +@table @samp +@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} +Configure the package to build and install an optional user-level +facility called @var{feature}. This allows users to choose which +optional features to include. Giving an optional @var{parameter} of +@samp{no} should omit @var{feature}, if it is built by default. + +No @samp{--enable} option should @strong{ever} cause one feature to +replace another. No @samp{--enable} option should ever substitute one +useful behavior for another useful behavior. The only proper use for +@samp{--enable} is for questions of whether to build part of the program +or exclude it. + +@item --with-@var{package} +@c @r{[}=@var{parameter}@r{]} +The package @var{package} will be installed, so configure this package +to work with @var{package}. + +@c Giving an optional @var{parameter} of +@c @samp{no} should omit @var{package}, if it is used by default. + +Possible values of @var{package} include @samp{x}, @samp{x-toolkit}, +@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and +@samp{gdb}. + +Do not use a @samp{--with} option to specify the file name to use to +find certain files. That is outside the scope of what @samp{--with} +options are for. + +@item --nfp +The target machine has no floating point processor. + +@item --gas +The target machine assembler is GAS, the GNU assembler. +This is obsolete; users should use @samp{--with-gnu-as} instead. + +@item --x +The target machine has the X Window System installed. +This is obsolete; users should use @samp{--with-x} instead. +@end table + +All @code{configure} scripts should accept all of these ``detail'' +options, whether or not they make any difference to the particular +package at hand. In particular, they should accept any option that +starts with @samp{--with-} or @samp{--enable-}. This is so users will +be able to configure an entire GNU source tree at once with a single set +of options. + +You will note that the categories @samp{--with-} and @samp{--enable-} +are narrow: they @strong{do not} provide a place for any sort of option +you might think of. That is deliberate. We want to limit the possible +configuration options in GNU software. We do not want GNU programs to +have idiosyncratic configuration options. + +Packages that perform part of the compilation process may support cross-compilation. +In such a case, the host and target machines for the program may be +different. The @code{configure} script should normally treat the +specified type of system as both the host and the target, thus producing +a program which works for the same type of machine that it runs on. + +The way to build a cross-compiler, cross-assembler, or what have you, is +to specify the option @samp{--host=@var{hosttype}} when running +@code{configure}. This specifies the host system without changing the +type of target system. The syntax for @var{hosttype} is the same as +described above. + +Bootstrapping a cross-compiler requires compiling it on a machine other +than the host it will run on. Compilation packages accept a +configuration option @samp{--build=@var{hosttype}} for specifying the +configuration on which you will compile them, in case that is different +from the host. + +Programs for which cross-operation is not meaningful need not accept the +@samp{--host} option, because configuring an entire operating system for +cross-operation is not a meaningful thing. + +Some programs have ways of configuring themselves automatically. If +your program is set up to do this, your @code{configure} script can simply +ignore most of its arguments. + +@comment The makefile standards are in a separate file that is also +@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. +@comment For this document, turn chapters into sections, etc. +@lowersections +@include make-stds.texi +@raisesections + @node Releases -@chapter Making Releases +@section Making Releases Package the distribution of Foo version 69.96 in a gzipped tar file named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory @@ -2498,7 +2666,7 @@ to include non-source files in the distribution, provided they are up-to-date and machine-independent, so that building the distribution normally will never modify them. We commonly include non-source files -produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid +produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid unnecessary dependencies between our distributions, so that users can install whichever packages they want to install. @@ -2529,16 +2697,16 @@ systems cannot handle this and that prevents unpacking the distribution. -Try to make sure that all the file names will be unique on MS-DOG. A -name on MS-DOG consists of up to 8 characters, optionally followed by a -period and up to three characters. MS-DOG will truncate extra +Try to make sure that all the file names will be unique on MS-DOS. A +name on MS-DOS consists of up to 8 characters, optionally followed by a +period and up to three characters. MS-DOS will truncate extra characters both before and after the period. Thus, @file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they are truncated to @file{foobarha.c} and @file{foobarha.o}, which are distinct. Include in your distribution a copy of the @file{texinfo.tex} you used -to test print any @file{*.texinfo} files. +to test print any @file{*.texinfo} or @file{*.texi} files. Likewise, if your program uses small GNU software packages like regex, getopt, obstack, or termcap, include them in the distribution file. diff -ruN autoconf-2.7/texinfo.tex autoconf-2.9/texinfo.tex --- autoconf-2.7/texinfo.tex Fri Nov 17 15:16:47 1995 +++ autoconf-2.9/texinfo.tex Sat Mar 16 15:54:29 1996 @@ -1,6 +1,7 @@ %% TeX macros to handle texinfo files -% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 1994 Free Software Foundation, Inc. +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, +% 94, 95, 1996 Free Software Foundation, Inc. %This texinfo.tex file is free software; you can redistribute it and/or %modify it under the terms of the GNU General Public License as @@ -14,8 +15,8 @@ %You should have received a copy of the GNU General Public License %along with this texinfo.tex file; see the file COPYING. If not, write -%to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, -%USA. +%to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +%Boston, MA 02111-1307, USA. %In other words, you are welcome to use, share and improve this program. @@ -34,7 +35,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 2.150 $ +\deftexinfoversion$Revision: 2.170 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -69,7 +70,7 @@ % Avoid using \@M directly, because that causes trouble % if the definition is written into an index file. \global\let\tiepenalty = \@M - \gdef\tie{\lvvmode\penalty\tiepenalty\ } + \gdef\tie{\leavevmode\penalty\tiepenalty\ } } \let\~ = \tie % And make it available as @~. @@ -536,17 +537,34 @@ \def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount \leftline{\hskip\leftskip{\rm#1}}}} +% @inmargin{TEXT} puts TEXT in the margin next to the current paragraph. + +\def\inmargin#1{% +\strut\vadjust{\nobreak\kern-\strutdepth + \vtop to \strutdepth{\baselineskip\strutdepth\vss + \llap{\rightskip=\inmarginspacing \vbox{\noindent #1}}\null}}} +\newskip\inmarginspacing \inmarginspacing=1cm +\def\strutdepth{\dp\strutbox} + %\hbox{{\rm#1}}\hfil\break}} % @include file insert text of that file as input. - -\def\include{\parsearg\includezzz} -%Use \input\thisfile to avoid blank after \input, which may be an active -%char (in which case the blank would become the \input argument). -%The grouping keeps the value of \thisfile correct even when @include -%is nested. -\def\includezzz #1{\begingroup -\def\thisfile{#1}\input\thisfile +% Allow normal characters that we make active in the argument (a file name). +\def\include{\begingroup + \catcode`\\=12 + \catcode`~=12 + \catcode`^=12 + \catcode`_=12 + \catcode`|=12 + \catcode`<=12 + \catcode`>=12 + \catcode`+=12 + \parsearg\includezzz} +% Restore active chars for included file. +\def\includezzz#1{\endgroup\begingroup + % Read the included file in a group so nested @include's work. + \def\thisfile{#1}% + \input\thisfile \endgroup} \def\thisfile{} @@ -631,6 +649,15 @@ \let\printindex = \relax \let\pxref = \relax \let\settitle = \relax + \let\setchapternewpage = \relax + \let\setchapterstyle = \relax + \let\everyheading = \relax + \let\evenheading = \relax + \let\oddheading = \relax + \let\everyfooting = \relax + \let\evenfooting = \relax + \let\oddfooting = \relax + \let\headings = \relax \let\include = \relax \let\lowersections = \relax \let\down = \relax @@ -654,6 +681,11 @@ \def\menu{\doignore{menu}} \def\direntry{\doignore{direntry}} +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. + +\def\dircategory{\comment} + % Ignore text until a line `@end #1'. % \def\doignore#1{\begingroup @@ -689,7 +721,7 @@ \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} \immediate\write16{ to use a workaround.} \immediate\write16{} - \warnedobstrue + \global\warnedobstrue \fi } @@ -765,15 +797,17 @@ % Since we want to separate VAR from REST-OF-LINE (which might be % empty), we can't just use \parsearg; we have to insert a space of our % own to delimit the rest of the line, and then take it out again if we -% didn't need it. +% didn't need it. Make sure the catcode of space is correct to avoid +% losing inside @example, for instance. % -\def\set{\parsearg\setxxx} +\def\set{\begingroup\catcode` =10 \parsearg\setxxx} \def\setxxx#1{\setyyy#1 \endsetyyy} \def\setyyy#1 #2\endsetyyy{% \def\temp{#2}% \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. \fi + \endgroup } % Can't use \xdef to pre-expand #2 and save some time, since \temp or % \next or other control sequences that we've defined might get us into @@ -920,12 +954,16 @@ \def\sf{\fam=\sffam \tensf} \let\li = \sf % Sometimes we call it \li, not \sf. +% We don't need math for this one. +\def\ttsl{\tenttsl} + %% Try out Computer Modern fonts at \magstephalf \let\mainmagstep=\magstephalf % Set the font macro #1 to the font named #2, adding on the % specified font prefix (normally `cm'). -\def\setfont#1#2{\font#1=\fontprefix#2} +% #3 is the font's design size, #4 is a scale factor +\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} % Use cm as the default font prefix. % To specify the font prefix, you must define \fontprefix @@ -933,29 +971,46 @@ \ifx\fontprefix\undefined \def\fontprefix{cm} \fi +% Support font families that don't use the same naming scheme as CM. +\def\rmshape{r} +\def\rmbshape{bx} %where the normal face is bold +\def\bfshape{b} +\def\bxshape{bx} +\def\ttshape{tt} +\def\ttbshape{tt} +\def\ttslshape{sltt} +\def\itshape{ti} +\def\itbshape{bxti} +\def\slshape{sl} +\def\slbshape{bxsl} +\def\sfshape{ss} +\def\sfbshape{ss} +\def\scshape{csc} +\def\scbshape{csc} \ifx\bigger\relax \let\mainmagstep=\magstep1 -\setfont\textrm{r12} -\setfont\texttt{tt12} +\setfont\textrm\rmshape{12}{1000} +\setfont\texttt\ttshape{12}{1000} \else -\setfont\textrm{r10 scaled \mainmagstep} -\setfont\texttt{tt10 scaled \mainmagstep} +\setfont\textrm\rmshape{10}{\mainmagstep} +\setfont\texttt\ttshape{10}{\mainmagstep} \fi % Instead of cmb10, you many want to use cmbx10. % cmbx10 is a prettier font on its own, but cmb10 % looks better when embedded in a line with cmr10. -\setfont\textbf{b10 scaled \mainmagstep} -\setfont\textit{ti10 scaled \mainmagstep} -\setfont\textsl{sl10 scaled \mainmagstep} -\setfont\textsf{ss10 scaled \mainmagstep} -\setfont\textsc{csc10 scaled \mainmagstep} +\setfont\textbf\bfshape{10}{\mainmagstep} +\setfont\textit\itshape{10}{\mainmagstep} +\setfont\textsl\slshape{10}{\mainmagstep} +\setfont\textsf\sfshape{10}{\mainmagstep} +\setfont\textsc\scshape{10}{\mainmagstep} +\setfont\textttsl\ttslshape{10}{\mainmagstep} \font\texti=cmmi10 scaled \mainmagstep \font\textsy=cmsy10 scaled \mainmagstep % A few fonts for @defun, etc. -\setfont\defbf{bx10 scaled \magstep1} %was 1314 -\setfont\deftt{tt10 scaled \magstep1} +\setfont\defbf\bxshape{10}{\magstep1} %was 1314 +\setfont\deftt\ttshape{10}{\magstep1} \def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} % Fonts for indices and small examples. @@ -963,66 +1018,70 @@ % because texinfo normally uses the slanted fonts for that. % Do not make many font distinctions in general in the index, since they % aren't very useful. -\setfont\ninett{tt9} -\setfont\indrm{r9} -\setfont\indit{sl9} +\setfont\ninett\ttshape{9}{1000} +\setfont\indrm\rmshape{9}{1000} +\setfont\indit\slshape{9}{1000} \let\indsl=\indit \let\indtt=\ninett +\let\indttsl=\ninett \let\indsf=\indrm \let\indbf=\indrm -\setfont\indsc{csc10 at 9pt} +\setfont\indsc\scshape{10}{900} \font\indi=cmmi9 \font\indsy=cmsy9 % Fonts for headings -\setfont\chaprm{bx12 scaled \magstep2} -\setfont\chapit{ti12 scaled \magstep2} -\setfont\chapsl{sl12 scaled \magstep2} -\setfont\chaptt{tt12 scaled \magstep2} -\setfont\chapsf{ss12 scaled \magstep2} +\setfont\chaprm\rmbshape{12}{\magstep2} +\setfont\chapit\itbshape{10}{\magstep3} +\setfont\chapsl\slbshape{10}{\magstep3} +\setfont\chaptt\ttbshape{12}{\magstep2} +\setfont\chapttsl\ttslshape{10}{\magstep3} +\setfont\chapsf\sfbshape{12}{\magstep2} \let\chapbf=\chaprm -\setfont\chapsc{csc10 scaled\magstep3} +\setfont\chapsc\scbshape{10}{\magstep3} \font\chapi=cmmi12 scaled \magstep2 \font\chapsy=cmsy10 scaled \magstep3 -\setfont\secrm{bx12 scaled \magstep1} -\setfont\secit{ti12 scaled \magstep1} -\setfont\secsl{sl12 scaled \magstep1} -\setfont\sectt{tt12 scaled \magstep1} -\setfont\secsf{ss12 scaled \magstep1} -\setfont\secbf{bx12 scaled \magstep1} -\setfont\secsc{csc10 scaled\magstep2} +\setfont\secrm\rmbshape{12}{\magstep1} +\setfont\secit\itbshape{10}{\magstep2} +\setfont\secsl\slbshape{10}{\magstep2} +\setfont\sectt\ttbshape{12}{\magstep1} +\setfont\secttsl\ttslshape{10}{\magstep2} +\setfont\secsf\sfbshape{12}{\magstep1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2} \font\seci=cmmi12 scaled \magstep1 \font\secsy=cmsy10 scaled \magstep2 -% \setfont\ssecrm{bx10 scaled \magstep1} % This size an font looked bad. -% \setfont\ssecit{cmti10 scaled \magstep1} % The letters were too crowded. -% \setfont\ssecsl{sl10 scaled \magstep1} -% \setfont\ssectt{tt10 scaled \magstep1} -% \setfont\ssecsf{ss10 scaled \magstep1} - -%\setfont\ssecrm{b10 scaled 1315} % Note the use of cmb rather than cmbx. -%\setfont\ssecit{ti10 scaled 1315} % Also, the size is a little larger than -%\setfont\ssecsl{sl10 scaled 1315} % being scaled magstep1. -%\setfont\ssectt{tt10 scaled 1315} -%\setfont\ssecsf{ss10 scaled 1315} +% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad. +% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded. +% \setfont\ssecsl\slshape{10}{\magstep1} +% \setfont\ssectt\ttshape{10}{\magstep1} +% \setfont\ssecsf\sfshape{10}{\magstep1} + +%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than +%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1. +%\setfont\ssectt\ttshape{10}{1315} +%\setfont\ssecsf\sfshape{10}{1315} %\let\ssecbf=\ssecrm -\setfont\ssecrm{bx12 scaled \magstephalf} -\setfont\ssecit{ti12 scaled \magstephalf} -\setfont\ssecsl{sl12 scaled \magstephalf} -\setfont\ssectt{tt12 scaled \magstephalf} -\setfont\ssecsf{ss12 scaled \magstephalf} -\setfont\ssecbf{bx12 scaled \magstephalf} -\setfont\ssecsc{csc10 scaled \magstep1} +\setfont\ssecrm\rmbshape{12}{\magstephalf} +\setfont\ssecit\itbshape{10}{1315} +\setfont\ssecsl\slbshape{10}{1315} +\setfont\ssectt\ttbshape{12}{\magstephalf} +\setfont\ssecttsl\ttslshape{10}{\magstep1} +\setfont\ssecsf\sfbshape{12}{\magstephalf} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{\magstep1} \font\sseci=cmmi12 scaled \magstephalf \font\ssecsy=cmsy10 scaled \magstep1 % The smallcaps and symbol fonts should actually be scaled \magstep1.5, % but that is not a standard magnification. % Fonts for title page: -\setfont\titlerm{bx12 scaled \magstep3} +\setfont\titlerm\rmbshape{12}{\magstep3} \let\authorrm = \secrm % In order for the font changes to affect most math symbols and letters, @@ -1041,33 +1100,33 @@ % The font-changing commands redefine the meanings of \tenSTYLE, instead % of just \STYLE. We do this so that font changes will continue to work % in math mode, where it is the current \fam that is relevant in most -% cases, not the current. Plain TeX does, for example, -% \def\bf{\fam=\bffam \tenbf} By redefining \tenbf, we obviate the need -% to redefine \bf itself. +% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam +% \tenbf}, for example. By redefining \tenbf, we obviate the need to +% redefine \bf itself. \def\textfonts{% \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl \resetmathfonts} \def\chapfonts{% \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl \resetmathfonts} \def\secfonts{% \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl \resetmathfonts} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl \resetmathfonts} \def\indexfonts{% \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc - \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy \let\tenttsl=\indttsl \resetmathfonts} % Set up the default fonts, so we can use them for creating boxes. @@ -1078,9 +1137,9 @@ \newcount\fontdepth \fontdepth=0 % Fonts for short table of contents. -\setfont\shortcontrm{r12} -\setfont\shortcontbf{bx12} -\setfont\shortcontsl{sl12} +\setfont\shortcontrm\rmshape{12}{1000} +\setfont\shortcontbf\bxshape{12}{1000} +\setfont\shortcontsl\slshape{12}{1000} %% Add scribe-like font environments, plus @l for inline lisp (usually sans %% serif) and @ii for TeX italic @@ -1112,7 +1171,7 @@ } \let\ttfont=\t \def\samp #1{`\tclose{#1}'\null} -\def\key #1{{\tt \nohyphenation \uppercase{#1}}\null} +\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} \def\ctrl #1{{\tt \rawbackslash \hat}#1} \let\file=\samp @@ -1141,7 +1200,7 @@ } % We *must* turn on hyphenation at `-' and `_' in \code. -% Otherwise, it is too hard to avoid overful hboxes +% Otherwise, it is too hard to avoid overfull hboxes % in the Emacs manual, the Library manual, etc. % Unfortunately, TeX uses one parameter (\hyphenchar) to control @@ -1170,12 +1229,19 @@ % @kbd is like @code, except that if the argument is just one @key command, % then @kbd has no effect. - +% \def\xkey{\key} \def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% \ifx\one\xkey\ifx\threex\three \key{#2}% -\else\tclose{\look}\fi -\else\tclose{\look}\fi} +\else{\tclose{\ttsl\look}}\fi +\else{\tclose{\ttsl\look}}\fi} + +% Check if we are currently using a typewriter font. Since all the +% Computer Modern typewriter fonts have zero interword stretch (and +% shrink), and it is reasonable to expect all typewriter fonts to have +% this property, we can check that font parameter. +% +\def\ifmonospace{\ifdim\fontdimen3\font=0pt } % Typeset a dimension, e.g., `in' or `pt'. The only reason for the % argument is to make the input look right: @dmn{pt} instead of @@ -1440,7 +1506,7 @@ \newif\ifitemxneedsnegativevskip -\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} +\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} \def\internalBitem{\smallbreak \parsearg\itemzzz} \def\internalBitemx{\itemxpar \parsearg\itemzzz} @@ -1711,10 +1777,10 @@ \flushcr} % @multitable macros -% Amy Hendrickson, 8/18/94 +% Amy Hendrickson, 8/18/94, 3/6/96 % -% @multitable ... @endmultitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width +% @multitable ... @end multitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width % can be specified either with sample text given in a template line, % or in percent of \hsize, the current width of text on page. @@ -1723,10 +1789,10 @@ % To make preamble: % % Either define widths of columns in terms of percent of \hsize: -% @multitable @percentofhsize .2 .3 .5 +% @multitable @columnfractions .25 .3 .45 % @item ... % -% Numbers following @percentofhsize are the percent of the total +% Numbers following @columnfractions are the percent of the total % current hsize to be used for each column. You may use as many % columns as desired. @@ -1734,7 +1800,16 @@ % @multitable {Column 1 template} {Column 2 template} {Column 3 template} % @item ... % using the widest term desired in each column. - +% +% For those who want to use more than one line's worth of words in +% the preamble, break the line within one argument and it +% will parse correctly, i.e., +% +% @multitable {Column 1 template} {Column 2 template} {Column 3 +% template} +% Not: +% @multitable {Column 1 template} {Column 2 template} +% {Column 3 template} % Each new table line starts with @item, each subsequent new column % starts with @tab. Empty columns may be produced by supplying @tab's @@ -1759,71 +1834,84 @@ % % They will wrap at the width determined by the template. % @item@tab@tab This will be in third column. -% @endmultitable +% @end multitable % Default dimensions may be reset by user. -% @intableparskip will set vertical space between paragraphs in table. -% @intableparindent will set paragraph indent in table. -% @spacebetweencols will set horizontal space to be left between columns. -% @spacebetweenlines will set vertical space to be left between lines. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items; +% 0 means it depends on current normal line spacing. %%%% % Dimensions -\newdimen\intableparskip -\newdimen\intableparindent -\newdimen\spacebetweencols -\newdimen\spacebetweenlines -\intableparskip=0pt -\intableparindent=6pt -\spacebetweencols=12pt -\spacebetweenlines=12pt +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt %%%% % Macros used to set up halign preamble: \let\endsetuptable\relax \def\xendsetuptable{\endsetuptable} -\let\percentofhsize\relax -\def\xpercentofhsize{\percentofhsize} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} \newif\ifsetpercent +%% 2/1/96, to allow fractions to be given with more than one digit. +\def\pickupwholefraction#1 {\global\advance\colcount by1 % +\expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% +\setuptable} + \newcount\colcount \def\setuptable#1{\def\firstarg{#1}% \ifx\firstarg\xendsetuptable\let\go\relax% \else - \ifx\firstarg\xpercentofhsize\global\setpercenttrue% + \ifx\firstarg\xcolumnfractions\global\setpercenttrue% \else \ifsetpercent - \if#1.\else% - \global\advance\colcount by1 % - \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% - \fi + \let\go\pickupwholefraction % In this case arg of setuptable + % is the decimal point before the + % number given in percent of hsize. + % We don't need this so we don't use it. \else \global\advance\colcount by1 \setbox0=\hbox{#1}% \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% \fi% \fi% - \let\go\setuptable% +\ifx\go\pickupwholefraction\else\let\go\setuptable\fi% \fi\go} + %%%% % multitable syntax -\def\tab{&} +\def\tab{&\hskip1sp\relax} % 2/2/96 + % tiny skip here makes sure this column space is + % maintained, even if it is never used. + %%%% -% @multitable ... @endmultitable definitions: +% @multitable ... @end multitable definitions: + +\def\multitable{\parsearg\dotable} -\def\multitable#1\item{\bgroup +\def\dotable#1{\bgroup \let\item\cr \tolerance=9500 \hbadness=9500 -\parskip=\intableparskip -\parindent=\intableparindent +\setmultitablespacing +\parskip=\multitableparskip +\parindent=\multitableparindent \overfullrule=0pt \global\colcount=0\relax% \def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% % To parse everything between @multitable and @item : -\def\one{#1}\expandafter\setuptable\one\endsetuptable +\setuptable#1 \endsetuptable % Need to reset this to 0 after \setuptable. \global\colcount=0\relax% % @@ -1834,9 +1922,9 @@ \halign\bgroup&\global\advance\colcount by 1\relax% \vtop{\hsize=\expandafter\csname col\the\colcount\endcsname % In order to keep entries from bumping into each other - % we will add a \leftskip of \spacebetweencols to all columns after + % we will add a \leftskip of \multitablecolspace to all columns after % the first one. - % If a template has been used, we will add \spacebetweencols + % If a template has been used, we will add \multitablecolspace % to the width of each template entry. % If user has set preamble in terms of percent of \hsize % we will use that dimension as the width of the column, and @@ -1848,21 +1936,42 @@ \ifsetpercent \else % If user has set preamble in terms of percent of \hsize - % we will advance \hsize by \spacebetweencols - \advance\hsize by \spacebetweencols + % we will advance \hsize by \multitablecolspace + \advance\hsize by \multitablecolspace \fi - % In either case we will make \leftskip=\spacebetweencols: -\leftskip=\spacebetweencols + % In either case we will make \leftskip=\multitablecolspace: +\leftskip=\multitablecolspace \fi -\noindent##}\cr% +\noindent##%\par +%\vskip\multitablelinespace +}\cr% % \everycr will reset column counter, \colcount, at the end of % each line. Every column entry will cause \colcount to advance by one. % The table preamble % looks at the current \colcount to find the correct column width. -\global\everycr{\noalign{\nointerlineskip\vskip\spacebetweenlines +\global\everycr{\noalign{\nointerlineskip\vskip\multitablelinespace \filbreak%% keeps underfull box messages off when table breaks over pages. \global\colcount=0\relax}}} +\def\setmultitablespacing{% test to see if user has set \multitablelinespace. +% If so, do nothing. If not, give it an appropriate dimension based on +% current baselineskip. +\ifdim\multitablelinespace=0pt +\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip +\global\advance\multitablelinespace by-\ht0\fi +%% Test to see if parskip is larger than space between lines of +%% table. If not, do nothing. +%% If so, set to same dimension as multitablelinespace. +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi} \message{indexing,} % Index generation facilities @@ -3847,7 +3956,7 @@ \setbox0=\hbox{\printednodename}% \ifdim \wd0 = 0pt % No printed node name was explicitly given. - \ifx\SETxref-automatic-section-title\thisisundefined + \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax % Use the node name inside the square brackets. \def\printednodename{\ignorespaces #1}% \else @@ -4250,11 +4359,13 @@ } % Allow control of the text dimensions. Parameters in order: textheight; -% textwidth; \voffset; \hoffset (!); binding offset. All require a dimension; +% textwidth; voffset; hoffset; binding offset; topskip. +% All require a dimension; % header is additional; added length extends the bottom of the page. -\def\changepagesizes#1#2#3#4#5{ +\def\changepagesizes#1#2#3#4#5#6{ \global\vsize= #1 + \global\topskip= #6 \advance\vsize by \topskip \global\voffset= #3 \global\hsize= #2 @@ -4267,13 +4378,20 @@ \global\normaloffset= #4 \global\bindingoffset= #5} -% This layout is compatible with Latex on A4 paper. - -\def\afourlatex{\changepagesizes{22cm}{15cm}{7mm}{4.6mm}{5mm}} +% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin +% 29mm, hence bottom margin 28mm, nominal side margin 3cm. +\def\afourlatex + {\global\tolerance=700 + \global\hfuzz=1pt + \setleading{12pt} + \global\parskip 15pt plus 1pt + \advance\baselineskip by 1.6pt + \changepagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm} + } % Use @afourwide to print on European A4 paper in wide format. \def\afourwide{\afourpaper -\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}} +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}} % Define macros to output various characters with catcode for normal text. \catcode`\"=\other @@ -4322,14 +4440,7 @@ \catcode`\_=\active \def_{\ifusingtt\normalunderscore\_} % Subroutine for the previous macro. -\def\_{\lvvmode \kern.06em \vbox{\hrule width.3em height.1ex}} - -% \lvvmode is equivalent in function to \leavevmode. -% Using \leavevmode runs into trouble when written out to -% an index file due to the expansion of \leavevmode into ``\unhbox -% \voidb@x'' ---which looks to TeX like ``\unhbox \voidb\x'' due to our -% magic tricks with @. -\def\lvvmode{\vbox to 0pt{}} +\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}} \catcode`\|=\active \def|{{\tt \char '174}}