+++ /dev/null
-#! /bin/sh
-
-# Guess values for system-dependent variables and create Makefiles.
-# Generated automatically using autoconf version 2.12.1
-# 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.
-
-# Defaults:
-ac_help=
-ac_default_prefix=/usr/local
-# Any additions from configure.in:
-
-# Initialize some variables set by options.
-# The variables have the same names as the options, with
-# dashes changed to underlines.
-build=NONE
-cache_file=./config.cache
-exec_prefix=NONE
-host=NONE
-no_create=
-nonopt=NONE
-no_recursion=
-prefix=NONE
-program_prefix=NONE
-program_suffix=NONE
-program_transform_name=s,x,x,
-silent=
-site=
-srcdir=
-target=NONE
-verbose=
-x_includes=NONE
-x_libraries=NONE
-bindir='${exec_prefix}/bin'
-sbindir='${exec_prefix}/sbin'
-libexecdir='${exec_prefix}/libexec'
-datadir='${prefix}/share'
-sysconfdir='${prefix}/etc'
-sharedstatedir='${prefix}/com'
-localstatedir='${prefix}/var'
-libdir='${exec_prefix}/lib'
-includedir='${prefix}/include'
-oldincludedir='/usr/include'
-infodir='${prefix}/info'
-mandir='${prefix}/man'
-
-# Initialize some other variables.
-subdirs=
-MFLAGS= MAKEFLAGS=
-SHELL=${CONFIG_SHELL-/bin/sh}
-# Maximum number of lines to put in a shell here document.
-ac_max_here_lines=12
-
-ac_prev=
-for ac_option
-do
-
- # If the previous option needs an argument, assign it.
- if test -n "$ac_prev"; then
- eval "$ac_prev=\$ac_option"
- ac_prev=
- continue
- fi
-
- case "$ac_option" in
- -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
- *) ac_optarg= ;;
- esac
-
- # Accept the important Cygnus configure options, so we can diagnose typos.
-
- case "$ac_option" in
-
- -bindir | --bindir | --bindi | --bind | --bin | --bi)
- ac_prev=bindir ;;
- -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
- bindir="$ac_optarg" ;;
-
- -build | --build | --buil | --bui | --bu)
- ac_prev=build ;;
- -build=* | --build=* | --buil=* | --bui=* | --bu=*)
- build="$ac_optarg" ;;
-
- -cache-file | --cache-file | --cache-fil | --cache-fi \
- | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
- ac_prev=cache_file ;;
- -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
- | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
- cache_file="$ac_optarg" ;;
-
- -datadir | --datadir | --datadi | --datad | --data | --dat | --da)
- ac_prev=datadir ;;
- -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
- | --da=*)
- datadir="$ac_optarg" ;;
-
- -disable-* | --disable-*)
- ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
- { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
- fi
- ac_feature=`echo $ac_feature| sed 's/-/_/g'`
- eval "enable_${ac_feature}=no" ;;
-
- -enable-* | --enable-*)
- ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
- { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
- fi
- ac_feature=`echo $ac_feature| sed 's/-/_/g'`
- case "$ac_option" in
- *=*) ;;
- *) ac_optarg=yes ;;
- esac
- eval "enable_${ac_feature}='$ac_optarg'" ;;
-
- -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
- | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
- | --exec | --exe | --ex)
- ac_prev=exec_prefix ;;
- -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
- | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
- | --exec=* | --exe=* | --ex=*)
- exec_prefix="$ac_optarg" ;;
-
- -gas | --gas | --ga | --g)
- # Obsolete; use --with-gas.
- with_gas=yes ;;
-
- -help | --help | --hel | --he)
- # Omit some internal or obsolete options to make the list less imposing.
- # This message is too long to be a string in the A/UX 3.1 sh.
- cat << EOF
-Usage: configure [options] [host]
-Options: [defaults in brackets after descriptions]
-Configuration:
- --cache-file=FILE cache test results in FILE
- --help print this message
- --no-create do not create output files
- --quiet, --silent do not print \`checking...' messages
- --version print the version of autoconf that created configure
-Directory and file names:
- --prefix=PREFIX install architecture-independent files in PREFIX
- [$ac_default_prefix]
- --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
- [same as prefix]
- --bindir=DIR user executables in DIR [EPREFIX/bin]
- --sbindir=DIR system admin executables in DIR [EPREFIX/sbin]
- --libexecdir=DIR program executables in DIR [EPREFIX/libexec]
- --datadir=DIR read-only architecture-independent data in DIR
- [PREFIX/share]
- --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc]
- --sharedstatedir=DIR modifiable architecture-independent data in DIR
- [PREFIX/com]
- --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var]
- --libdir=DIR object code libraries in DIR [EPREFIX/lib]
- --includedir=DIR C header files in DIR [PREFIX/include]
- --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include]
- --infodir=DIR info documentation in DIR [PREFIX/info]
- --mandir=DIR man documentation in DIR [PREFIX/man]
- --srcdir=DIR find the sources in DIR [configure dir or ..]
- --program-prefix=PREFIX prepend PREFIX to installed program names
- --program-suffix=SUFFIX append SUFFIX to installed program names
- --program-transform-name=PROGRAM
- run sed PROGRAM on installed program names
-EOF
- cat << EOF
-Host type:
- --build=BUILD configure for building on BUILD [BUILD=HOST]
- --host=HOST configure for HOST [guessed]
- --target=TARGET configure for TARGET [TARGET=HOST]
-Features and packages:
- --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
- --enable-FEATURE[=ARG] include FEATURE [ARG=yes]
- --with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
- --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
- --x-includes=DIR X include files are in DIR
- --x-libraries=DIR X library files are in DIR
-EOF
- if test -n "$ac_help"; then
- echo "--enable and --with options recognized:$ac_help"
- fi
- exit 0 ;;
-
- -host | --host | --hos | --ho)
- ac_prev=host ;;
- -host=* | --host=* | --hos=* | --ho=*)
- host="$ac_optarg" ;;
-
- -includedir | --includedir | --includedi | --included | --include \
- | --includ | --inclu | --incl | --inc)
- ac_prev=includedir ;;
- -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
- | --includ=* | --inclu=* | --incl=* | --inc=*)
- includedir="$ac_optarg" ;;
-
- -infodir | --infodir | --infodi | --infod | --info | --inf)
- ac_prev=infodir ;;
- -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
- infodir="$ac_optarg" ;;
-
- -libdir | --libdir | --libdi | --libd)
- ac_prev=libdir ;;
- -libdir=* | --libdir=* | --libdi=* | --libd=*)
- libdir="$ac_optarg" ;;
-
- -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
- | --libexe | --libex | --libe)
- ac_prev=libexecdir ;;
- -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
- | --libexe=* | --libex=* | --libe=*)
- libexecdir="$ac_optarg" ;;
-
- -localstatedir | --localstatedir | --localstatedi | --localstated \
- | --localstate | --localstat | --localsta | --localst \
- | --locals | --local | --loca | --loc | --lo)
- ac_prev=localstatedir ;;
- -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
- | --localstate=* | --localstat=* | --localsta=* | --localst=* \
- | --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
- localstatedir="$ac_optarg" ;;
-
- -mandir | --mandir | --mandi | --mand | --man | --ma | --m)
- ac_prev=mandir ;;
- -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
- mandir="$ac_optarg" ;;
-
- -nfp | --nfp | --nf)
- # Obsolete; use --without-fp.
- with_fp=no ;;
-
- -no-create | --no-create | --no-creat | --no-crea | --no-cre \
- | --no-cr | --no-c)
- no_create=yes ;;
-
- -no-recursion | --no-recursion | --no-recursio | --no-recursi \
- | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
- no_recursion=yes ;;
-
- -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
- | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
- | --oldin | --oldi | --old | --ol | --o)
- ac_prev=oldincludedir ;;
- -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
- | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
- | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
- oldincludedir="$ac_optarg" ;;
-
- -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
- ac_prev=prefix ;;
- -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
- prefix="$ac_optarg" ;;
-
- -program-prefix | --program-prefix | --program-prefi | --program-pref \
- | --program-pre | --program-pr | --program-p)
- ac_prev=program_prefix ;;
- -program-prefix=* | --program-prefix=* | --program-prefi=* \
- | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
- program_prefix="$ac_optarg" ;;
-
- -program-suffix | --program-suffix | --program-suffi | --program-suff \
- | --program-suf | --program-su | --program-s)
- ac_prev=program_suffix ;;
- -program-suffix=* | --program-suffix=* | --program-suffi=* \
- | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
- program_suffix="$ac_optarg" ;;
-
- -program-transform-name | --program-transform-name \
- | --program-transform-nam | --program-transform-na \
- | --program-transform-n | --program-transform- \
- | --program-transform | --program-transfor \
- | --program-transfo | --program-transf \
- | --program-trans | --program-tran \
- | --progr-tra | --program-tr | --program-t)
- ac_prev=program_transform_name ;;
- -program-transform-name=* | --program-transform-name=* \
- | --program-transform-nam=* | --program-transform-na=* \
- | --program-transform-n=* | --program-transform-=* \
- | --program-transform=* | --program-transfor=* \
- | --program-transfo=* | --program-transf=* \
- | --program-trans=* | --program-tran=* \
- | --progr-tra=* | --program-tr=* | --program-t=*)
- program_transform_name="$ac_optarg" ;;
-
- -q | -quiet | --quiet | --quie | --qui | --qu | --q \
- | -silent | --silent | --silen | --sile | --sil)
- silent=yes ;;
-
- -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
- ac_prev=sbindir ;;
- -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
- | --sbi=* | --sb=*)
- sbindir="$ac_optarg" ;;
-
- -sharedstatedir | --sharedstatedir | --sharedstatedi \
- | --sharedstated | --sharedstate | --sharedstat | --sharedsta \
- | --sharedst | --shareds | --shared | --share | --shar \
- | --sha | --sh)
- ac_prev=sharedstatedir ;;
- -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
- | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
- | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
- | --sha=* | --sh=*)
- sharedstatedir="$ac_optarg" ;;
-
- -site | --site | --sit)
- ac_prev=site ;;
- -site=* | --site=* | --sit=*)
- site="$ac_optarg" ;;
-
- -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
- ac_prev=srcdir ;;
- -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
- srcdir="$ac_optarg" ;;
-
- -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
- | --syscon | --sysco | --sysc | --sys | --sy)
- ac_prev=sysconfdir ;;
- -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
- | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
- sysconfdir="$ac_optarg" ;;
-
- -target | --target | --targe | --targ | --tar | --ta | --t)
- ac_prev=target ;;
- -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
- target="$ac_optarg" ;;
-
- -v | -verbose | --verbose | --verbos | --verbo | --verb)
- verbose=yes ;;
-
- -version | --version | --versio | --versi | --vers)
- echo "configure generated by autoconf version 2.12.1"
- exit 0 ;;
-
- -with-* | --with-*)
- ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
- { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
- fi
- ac_package=`echo $ac_package| sed 's/-/_/g'`
- case "$ac_option" in
- *=*) ;;
- *) ac_optarg=yes ;;
- esac
- eval "with_${ac_package}='$ac_optarg'" ;;
-
- -without-* | --without-*)
- ac_package=`echo $ac_option|sed -e 's/-*without-//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
- { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
- fi
- ac_package=`echo $ac_package| sed 's/-/_/g'`
- eval "with_${ac_package}=no" ;;
-
- --x)
- # Obsolete; use --with-x.
- with_x=yes ;;
-
- -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
- | --x-incl | --x-inc | --x-in | --x-i)
- ac_prev=x_includes ;;
- -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
- | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
- x_includes="$ac_optarg" ;;
-
- -x-libraries | --x-libraries | --x-librarie | --x-librari \
- | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
- ac_prev=x_libraries ;;
- -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
- | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
- x_libraries="$ac_optarg" ;;
-
- -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
- ;;
-
- *)
- if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
- echo "configure: warning: $ac_option: invalid host type" 1>&2
- fi
- if test "x$nonopt" != xNONE; then
- { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
- fi
- nonopt="$ac_option"
- ;;
-
- esac
-done
-
-if test -n "$ac_prev"; then
- { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
-fi
-
-trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
-
-# File descriptor usage:
-# 0 standard input
-# 1 file creation
-# 2 errors and warnings
-# 3 some systems may open it to /dev/tty
-# 4 used on the Kubota Titan
-# 6 checking for... messages and results
-# 5 compiler messages saved in config.log
-if test "$silent" = yes; then
- exec 6>/dev/null
-else
- exec 6>&1
-fi
-exec 5>./config.log
-
-echo "\
-This file contains any messages produced by compilers while
-running configure, to aid debugging if configure makes a mistake.
-" 1>&5
-
-# Strip out --no-create and --no-recursion so they do not pile up.
-# Also quote any args containing shell metacharacters.
-ac_configure_args=
-for ac_arg
-do
- case "$ac_arg" in
- -no-create | --no-create | --no-creat | --no-crea | --no-cre \
- | --no-cr | --no-c) ;;
- -no-recursion | --no-recursion | --no-recursio | --no-recursi \
- | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
- *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
- ac_configure_args="$ac_configure_args '$ac_arg'" ;;
- *) ac_configure_args="$ac_configure_args $ac_arg" ;;
- esac
-done
-
-# NLS nuisances.
-# Only set these to C if already set. These must not be set unconditionally
-# because not all systems understand e.g. LANG=C (notably SCO).
-# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
-# Non-C LC_CTYPE values break the ctype check.
-if test "${LANG+set}" = set; then LANG=C; export LANG; fi
-if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
-if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
-if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi
-
-# confdefs.h avoids OS command line length limits that DEFS can exceed.
-rm -rf conftest* confdefs.h
-# AIX cpp loses on an empty file, so make sure it contains at least a newline.
-echo > confdefs.h
-
-# A filename unique to this package, relative to the directory that
-# configure is in, which we can look for to find out if srcdir is correct.
-ac_unique_file=Makefile.in
-
-# Find the source files, if location was not specified.
-if test -z "$srcdir"; then
- ac_srcdir_defaulted=yes
- # Try the directory containing this script, then its parent.
- ac_prog=$0
- ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
- test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
- srcdir=$ac_confdir
- if test ! -r $srcdir/$ac_unique_file; then
- srcdir=..
- fi
-else
- ac_srcdir_defaulted=no
-fi
-if test ! -r $srcdir/$ac_unique_file; then
- if test "$ac_srcdir_defaulted" = yes; then
- { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
- else
- { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
- fi
-fi
-srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
-
-# Prefer explicitly selected file to automatically selected ones.
-if test -z "$CONFIG_SITE"; then
- if test "x$prefix" != xNONE; then
- CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
- else
- CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
- fi
-fi
-for ac_site_file in $CONFIG_SITE; do
- if test -r "$ac_site_file"; then
- echo "loading site script $ac_site_file"
- . "$ac_site_file"
- fi
-done
-
-if test -r "$cache_file"; then
- echo "loading cache $cache_file"
- . $cache_file
-else
- echo "creating cache $cache_file"
- > $cache_file
-fi
-
-ac_ext=c
-# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
-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'
-cross_compiling=$ac_cv_prog_cc_cross
-
-if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
- # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
- if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
- ac_n= ac_c='
-' ac_t=' '
- else
- ac_n=-n ac_c= ac_t=
- fi
-else
- ac_n= ac_c='\c' ac_t=
-fi
-
-
-
-ac_aux_dir=
-for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do
- if test -f $ac_dir/install-sh; then
- ac_aux_dir=$ac_dir
- ac_install_sh="$ac_aux_dir/install-sh -c"
- break
- elif test -f $ac_dir/install.sh; then
- ac_aux_dir=$ac_dir
- ac_install_sh="$ac_aux_dir/install.sh -c"
- break
- fi
-done
-if test -z "$ac_aux_dir"; then
- { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; }
-fi
-ac_config_guess=$ac_aux_dir/config.guess
-ac_config_sub=$ac_aux_dir/config.sub
-ac_configure=$ac_aux_dir/configure # This should be Cygnus configure.
-
-# Find a good install program. We prefer a C program (faster),
-# so one script is as good as another. But avoid the broken or
-# incompatible versions:
-# SysV /etc/install, /usr/sbin/install
-# SunOS /usr/etc/install
-# IRIX /sbin/install
-# AIX /bin/install
-# AFS /usr/afsws/bin/install, which mishandles nonexistent args
-# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
-# ./install, which can be erroneously created by make from ./install.sh.
-echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
-echo "configure:554: checking for a BSD compatible install" >&5
-if test -z "$INSTALL"; then
-if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then
- echo $ac_n "(cached) $ac_c" 1>&6
-else
- IFS="${IFS= }"; ac_save_IFS="$IFS"; IFS="${IFS}:"
- for ac_dir in $PATH; do
- # Account for people who put trailing slashes in PATH elements.
- case "$ac_dir/" in
- /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;;
- *)
- # OSF1 and SCO ODT 3.0 have their own names for install.
- for ac_prog in ginstall scoinst install; do
- if test -f $ac_dir/$ac_prog; then
- if test $ac_prog = install &&
- grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
- # AIX install. It has an incompatible calling convention.
- # OSF/1 installbsd also uses dspmsg, but is usable.
- :
- else
- ac_cv_path_install="$ac_dir/$ac_prog -c"
- break 2
- fi
- fi
- done
- ;;
- esac
- done
- IFS="$ac_save_IFS"
-
-fi
- if test "${ac_cv_path_install+set}" = set; then
- INSTALL="$ac_cv_path_install"
- else
- # As a last resort, use the slow shell script. We don't cache a
- # path for INSTALL within a source directory, because that will
- # break other packages using the cache if that directory is
- # removed, or if the path is relative.
- INSTALL="$ac_install_sh"
- fi
-fi
-echo "$ac_t""$INSTALL" 1>&6
-
-# Use test -z because SunOS4 sh mishandles braces in ${var-val}.
-# It thinks the first close brace ends the variable substitution.
-test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}'
-
-test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644'
-
-
-trap '' 1 2 15
-cat > confcache <<\EOF
-# This file is a shell script that caches the results of configure
-# tests run on this system so they can be shared between configure
-# scripts and configure runs. It is not useful on other systems.
-# If it contains results you don't want to keep, you may remove or edit it.
-#
-# By default, configure uses ./config.cache as the cache file,
-# creating it if it does not exist already. You can give configure
-# the --cache-file=FILE option to use a different cache file; that is
-# what configure does when it calls configure scripts in
-# subdirectories, so they share the cache.
-# Giving --cache-file=/dev/null disables caching, for debugging configure.
-# config.status only pays attention to the cache file if you give it the
-# --recheck option to rerun configure.
-#
-EOF
-# The following way of writing the cache mishandles newlines in values,
-# but we know of no workaround that is simple, portable, and efficient.
-# So, don't put newlines in cache variables' values.
-# Ultrix sh set writes to stderr and can't be redirected directly,
-# and sets the high bit in the cache file unless we assign to the vars.
-(set) 2>&1 |
- case `(ac_space=' '; set) 2>&1 | grep ac_space` in
- *ac_space=\ *)
- # `set' does not quote correctly, so add quotes (double-quote substitution
- # turns \\\\ into \\, and sed turns \\ into \).
- sed -n \
- -e "s/'/'\\\\''/g" \
- -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
- ;;
- *)
- # `set' quotes correctly as required by POSIX, so do not add quotes.
- sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
- ;;
- esac >> confcache
-if cmp -s $cache_file confcache; then
- :
-else
- if test -w $cache_file; then
- echo "updating cache $cache_file"
- cat confcache > $cache_file
- else
- echo "not updating unwritable cache $cache_file"
- fi
-fi
-rm -f confcache
-
-trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
-
-test "x$prefix" = xNONE && prefix=$ac_default_prefix
-# Let make expand exec_prefix.
-test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
-
-# Any assignment to VPATH causes Sun make to only execute
-# the first set of double-colon rules, so remove it if not needed.
-# If there is a colon in the path, we need to keep it.
-if test "x$srcdir" = x.; then
- ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d'
-fi
-
-trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
-
-# Transform confdefs.h into DEFS.
-# 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%[ `~#$^&*(){}\\|;'"<>?]%\\&%g
-s%\[%\\&%g
-s%\]%\\&%g
-s%\$%$$%g
-EOF
-DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
-rm -f conftest.defs
-
-
-# Without the "./", some shells look in PATH for config.status.
-: ${CONFIG_STATUS=./config.status}
-
-echo creating $CONFIG_STATUS
-rm -f $CONFIG_STATUS
-cat > $CONFIG_STATUS <<EOF
-#! /bin/sh
-# Generated automatically by configure.
-# Run this file to recreate the current configuration.
-# This directory was configured as follows,
-# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
-#
-# $0 $ac_configure_args
-#
-# Compiler output produced by configure, useful for debugging
-# configure, is in ./config.log if it exists.
-
-ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
-for ac_option
-do
- case "\$ac_option" in
- -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
- 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.12.1"
- exit 0 ;;
- -help | --help | --hel | --he | --h)
- echo "\$ac_cs_usage"; exit 0 ;;
- *) echo "\$ac_cs_usage"; exit 1 ;;
- esac
-done
-
-ac_given_srcdir=$srcdir
-
-trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
-EOF
-cat >> $CONFIG_STATUS <<EOF
-
-# Protect against being on the right side of a sed subst in config.status.
-sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
- s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
-$ac_vpsub
-$extrasub
-s%@SHELL@%$SHELL%g
-s%@CFLAGS@%$CFLAGS%g
-s%@CPPFLAGS@%$CPPFLAGS%g
-s%@CXXFLAGS@%$CXXFLAGS%g
-s%@DEFS@%$DEFS%g
-s%@LDFLAGS@%$LDFLAGS%g
-s%@LIBS@%$LIBS%g
-s%@exec_prefix@%$exec_prefix%g
-s%@prefix@%$prefix%g
-s%@program_transform_name@%$program_transform_name%g
-s%@bindir@%$bindir%g
-s%@sbindir@%$sbindir%g
-s%@libexecdir@%$libexecdir%g
-s%@datadir@%$datadir%g
-s%@sysconfdir@%$sysconfdir%g
-s%@sharedstatedir@%$sharedstatedir%g
-s%@localstatedir@%$localstatedir%g
-s%@libdir@%$libdir%g
-s%@includedir@%$includedir%g
-s%@oldincludedir@%$oldincludedir%g
-s%@infodir@%$infodir%g
-s%@mandir@%$mandir%g
-s%@INSTALL@%$INSTALL%g
-s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g
-s%@INSTALL_DATA@%$INSTALL_DATA%g
-
-CEOF
-EOF
-
-cat >> $CONFIG_STATUS <<\EOF
-
-# Split the substitutions into bite-sized pieces for seds with
-# small command number limits, like on Digital OSF/1 and HP-UX.
-ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
-ac_file=1 # Number of current file.
-ac_beg=1 # First line for current file.
-ac_end=$ac_max_sed_cmds # Line after last line for current file.
-ac_more_lines=:
-ac_sed_cmds=""
-while $ac_more_lines; do
- if test $ac_beg -gt 1; then
- sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
- else
- sed "${ac_end}q" conftest.subs > conftest.s$ac_file
- fi
- if test ! -s conftest.s$ac_file; then
- ac_more_lines=false
- rm -f conftest.s$ac_file
- else
- if test -z "$ac_sed_cmds"; then
- ac_sed_cmds="sed -f conftest.s$ac_file"
- else
- ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
- fi
- ac_file=`expr $ac_file + 1`
- ac_beg=$ac_end
- ac_end=`expr $ac_end + $ac_max_sed_cmds`
- fi
-done
-if test -z "$ac_sed_cmds"; then
- ac_sed_cmds=cat
-fi
-EOF
-
-cat >> $CONFIG_STATUS <<EOF
-
-CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
-EOF
-cat >> $CONFIG_STATUS <<\EOF
-for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
- # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
- case "$ac_file" in
- *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
- ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
- *) ac_file_in="${ac_file}.in" ;;
- esac
-
- # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
-
- # Remove last slash and all that follows it. Not all systems have dirname.
- ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
- if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
- # The file is in a subdirectory.
- test ! -d "$ac_dir" && mkdir "$ac_dir"
- ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
- # A "../" for each directory in $ac_dir_suffix.
- ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
- else
- ac_dir_suffix= ac_dots=
- fi
-
- case "$ac_given_srcdir" in
- .) srcdir=.
- if test -z "$ac_dots"; then top_srcdir=.
- else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
- /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
- *) # Relative path.
- srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
- top_srcdir="$ac_dots$ac_given_srcdir" ;;
- esac
-
-
- echo creating "$ac_file"
- rm -f "$ac_file"
- configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
- case "$ac_file" in
- *Makefile*) ac_comsub="1i\\
-# $configure_input" ;;
- *) ac_comsub= ;;
- esac
-
- ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
- sed -e "$ac_comsub
-s%@configure_input@%$configure_input%g
-s%@srcdir@%$srcdir%g
-s%@top_srcdir@%$top_srcdir%g
-" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
-fi; done
-rm -f conftest.s*
-
-EOF
-cat >> $CONFIG_STATUS <<EOF
-
-EOF
-cat >> $CONFIG_STATUS <<\EOF
-
-exit 0
-EOF
-chmod +x $CONFIG_STATUS
-rm -fr confdefs* $ac_clean_files
-test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
-
+++ /dev/null
-@comment This file is included by both standards.texi and make.texinfo.
-@comment It was broken out of standards.texi on 1/6/93 by roland.
-
-@node Makefile Conventions
-@chapter Makefile Conventions
-@comment standards.texi does not print an index, but make.texinfo does.
-@cindex makefile, conventions for
-@cindex conventions for makefiles
-@cindex standards for makefiles
-
-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.
-Using Automake will help you write a Makefile that follows these
-conventions.
-
-@menu
-* 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
-* Install Command Categories:: Three categories of commands in the `install'
- rule: normal, pre-install and post-install.
-@end menu
-
-@node Makefile Basics
-@section General Conventions for Makefiles
-
-Every Makefile should contain this line:
-
-@example
-SHELL = /bin/sh
-@end example
-
-@noindent
-to avoid trouble on systems where the @code{SHELL} variable might be
-inherited from the environment. (This is never a problem with GNU
-@code{make}.)
-
-Different @code{make} programs have incompatible suffix lists and
-implicit rules, and this sometimes creates confusion or misbehavior. So
-it is a good idea to set the suffix list explicitly using only the
-suffixes you need in the particular Makefile, like this:
-
-@example
-.SUFFIXES:
-.SUFFIXES: .c .o
-@end example
-
-@noindent
-The first line clears out the suffix list, the second introduces all
-suffixes which may be subject to implicit rules in this Makefile.
-
-Don't assume that @file{.} is in the path for command execution. When
-you need to run programs that are a part of your package during the
-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.
-
-The distinction between @file{./} (the @dfn{build directory}) and
-@file{$(srcdir)/} (the @dfn{source directory}) is important because
-users can build in a separate directory using the @samp{--srcdir} option
-to @file{configure}. A rule of the form:
-
-@smallexample
-foo.1 : foo.man sedscript
- sed -e sedscript foo.man > foo.1
-@end smallexample
-
-@noindent
-will fail when the build directory is not the source directory, because
-@file{foo.man} and @file{sedscript} are in the source directory.
-
-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 @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
-
-@smallexample
-foo.o : bar.c
- $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
-@end smallexample
-
-@noindent
-should instead be written as
-
-@smallexample
-foo.o : bar.c
- $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
-@end smallexample
-
-@noindent
-in order to allow @samp{VPATH} to work correctly. When the target has
-multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
-way to make the rule work well. For example, the target above for
-@file{foo.1} is best written as:
-
-@smallexample
-foo.1 : foo.man sedscript
- sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
-@end smallexample
-
-GNU distributions usually contain some files which are not source
-files---for example, Info files, and the output from Autoconf, Automake,
-Bison or Flex. Since these files normally appear in the source
-directory, they should always appear in the source directory, not in the
-build directory. So Makefile rules to update them should put the
-updated files in the source directory.
-
-However, if a file does not appear in the distribution, then the
-Makefile should not put it in the source directory, because building a
-program in ordinary circumstances should not modify the source directory
-in any way.
-
-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
-
-Write the Makefile commands (and any shell scripts, such as
-@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any
-special features of @code{ksh} or @code{bash}.
-
-The @code{configure} script and the Makefile rules for building and
-installation should not use any utilities directly except these:
-
-@c dd find
-@c gunzip gzip md5sum
-@c mkfifo mknod tee uname
-
-@example
-cat cmp cp diff echo egrep expr false grep install-info
-ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
-@end example
-
-The compression program @code{gzip} can be used in the @code{dist} rule.
-
-Stick to the generally supported options for these programs. For
-example, don't use @samp{mkdir -p}, convenient as it may be, because
-most systems don't support it.
-
-It is a good idea to avoid creating symbolic links in makefiles, since a
-few systems don't support them.
-
-The Makefile rules for building and installation can also use compilers
-and related programs, but should do so via @code{make} variables so that the
-user can substitute alternatives. Here are some of the programs we
-mean:
-
-@example
-ar bison cc flex install ld ldconfig lex
-make makeinfo ranlib texi2dvi yacc
-@end example
-
-Use the following @code{make} variables to run those programs:
-
-@example
-$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
-$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
-@end example
-
-When you use @code{ranlib} or @code{ldconfig}, you should make sure
-nothing bad happens if the system does not have the program in question.
-Arrange to ignore an error from that command, and print a message before
-the command to tell the user that failure of this 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.
-
-Additional utilities that can be used via Make variables are:
-
-@example
-chgrp chmod chown mknod
-@end example
-
-It is ok to use other utilities in Makefile portions (or scripts)
-intended only for particular systems where you know those utilities
-exist.
-
-@node Command Variables
-@section Variables for Specifying Commands
-
-Makefiles should provide variables for overriding certain commands, options,
-and so on.
-
-In particular, you should run most utility programs via variables.
-Thus, if you use Bison, have a variable named @code{BISON} whose default
-value is set with @samp{BISON = bison}, and refer to it with
-@code{$(BISON)} whenever you need to use Bison.
-
-File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
-so on, need not be referred to through variables in this way, since users
-don't need to replace them with other programs.
-
-Each program-name variable should come with an options variable that is
-used to supply options to the program. Append @samp{FLAGS} to the
-program-name variable name to get the options variable name---for
-example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C
-compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
-exceptions to this rule, but we keep them because they are standard.)
-Use @code{CPPFLAGS} in any compilation command that runs the
-preprocessor, and use @code{LDFLAGS} in any compilation command that
-does linking as well as in any direct use of @code{ld}.
-
-If there are C compiler options that @emph{must} be used for proper
-compilation of certain files, do not include them in @code{CFLAGS}.
-Users expect to be able to specify @code{CFLAGS} freely themselves.
-Instead, arrange to pass the necessary options to the C compiler
-independently of @code{CFLAGS}, by writing them explicitly in the
-compilation commands or by defining an implicit rule, like this:
-
-@smallexample
-CFLAGS = -g
-ALL_CFLAGS = -I. $(CFLAGS)
-.c.o:
- $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
-@end smallexample
-
-Do include the @samp{-g} option in @code{CFLAGS}, because that is not
-@emph{required} for proper compilation. You can consider it a default
-that is only recommended. If the package is set up so that it is
-compiled with GCC by default, then you might as well include @samp{-O}
-in the default value of @code{CFLAGS} as well.
-
-Put @code{CFLAGS} last in the compilation command, after other variables
-containing compiler options, so the user can use @code{CFLAGS} to
-override the others.
-
-@code{CFLAGS} should be used in every invocation of the C compiler,
-both those which do compilation and those which do linking.
-
-Every Makefile should define the variable @code{INSTALL}, which is the
-basic command for installing a file into the system.
-
-Every Makefile should also define the variables @code{INSTALL_PROGRAM}
-and @code{INSTALL_DATA}. (The default for each of these should be
-@code{$(INSTALL)}.) Then it should use those variables as the commands
-for actual installation, for executables and nonexecutables
-respectively. Use these variables as follows:
-
-@example
-$(INSTALL_PROGRAM) foo $(bindir)/foo
-$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
-@end example
-
-Optionally, you may prepend the value of @code{DESTDIR} to the target
-filename. Doing this allows the installer to create a snapshot of the
-installation to be copied onto the real target filesystem later. Do not
-set the value of @code{DESTDIR} in your Makefile, and do not include it
-in any installed files. With support for @code{DESTDIR}, the above
-examples become:
-
-@example
-$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
-$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
-@end example
-
-@noindent
-Always use a file name, not a directory name, as the second argument of
-the installation commands. Use a separate command for each file to be
-installed.
-
-@node Directory Variables
-@section Variables for Installation Directories
-
-Installation directories should always be named by variables, so it is
-easy to install in a nonstandard place. The standard names for these
-variables are described below. They are based on a standard filesystem
-layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
-and other modern operating systems.
-
-These two variables set the root for the installation. All the other
-installation directories should be subdirectories of one of these two,
-and nothing should be directly installed into these two directories.
-
-@table @samp
-@item prefix
-A prefix used in constructing the default values of the variables listed
-below. The default value of @code{prefix} should be @file{/usr/local}.
-When building the complete GNU system, the prefix will be empty and
-@file{/usr} will be a symbolic link to @file{/}.
-(If you are using Autoconf, write it as @samp{@@prefix@@}.)
-
-Running @samp{make install} with a different value of @code{prefix}
-from the one used to build the program should @var{not} recompile
-the program.
-
-@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),
-while @code{$(prefix)} is used directly for other directories.
-
-Running @samp{make install} with a different value of @code{exec_prefix}
-from the one used to build the program should @var{not} recompile the
-program.
-@end table
-
-Executable programs are installed in one of the following directories.
-
-@table @samp
-@item bindir
-The directory for installing executable programs that users can run.
-This should normally be @file{/usr/local/bin}, but write it as
-@file{$(exec_prefix)/bin}.
-(If you are using Autoconf, write it as @samp{@@bindir@@}.)
-
-@item sbindir
-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
-categories in two ways.
-
-@itemize @bullet
-@item
-Some files are normally modified by programs; others are never normally
-modified (though users may edit some of these).
-
-@item
-Some files are architecture-independent and can be shared by all
-machines at a site; some are architecture-dependent and can be shared
-only by machines of the same kind and operating system; others may never
-be shared between two machines.
-@end itemize
-
-This makes for six different possibilities. However, we want to
-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
-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}.
-(If you are using Autoconf, write it as @samp{@@datadir@@}.)
-As a special exception, see @file{$(infodir)}
-and @file{$(includedir)} below.
-
-@item sysconfdir
-The directory for installing read-only data files that pertain to a
-single machine--that is to say, files for configuring a host. Mailer
-and network configuration files, @file{/etc/passwd}, and so forth belong
-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@@}.)
-
-Do not install executables here in this directory (they probably 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)}.
-
-@item sharedstatedir
-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)}
-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 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 lispdir
-The directory for installing any Emacs Lisp files in this package. By
-default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
-should be written as @file{$(prefix)/share/emacs/site-lisp}.
-
-If you are using Autoconf, write the default as @samp{@@lispdir@@}.
-In order to make @samp{@@lispdir@@} work, you need the following lines
-in your @file{configure.in} file:
-
-@example
-lispdir='$@{datadir@}/emacs/site-lisp'
-AC_SUBST(lispdir)
-@end example
-
-@item includedir
-@c rewritten to avoid overfull hbox --roland
-The directory for installing header files to be included by user
-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 directory
-@file{/usr/local/include}. So installing the header files this way is
-only useful with GCC. Sometimes this is not a problem because some
-libraries are only really intended to work with GCC. But some libraries
-are intended to work with other compilers. They should install their
-header files in two places, one specified by @code{includedir} and one
-specified by @code{oldincludedir}.
-
-@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
-it; they should cancel the second installation of the header files.
-
-A package should not replace an existing header in this directory unless
-the header came from the same package. Thus, if your Foo package
-provides a header file @file{foo.h}, then it should install the header
-file in the @code{oldincludedir} directory if either (1) there is no
-@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
-package.
-
-To tell whether @file{foo.h} came from the Foo package, put a magic
-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:
-
-@table @samp
-@item mandir
-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}
-@item @dots{}
-
-@strong{Don't make the primary documentation for any GNU software be a
-man page. Write a manual in Texinfo instead. Man pages are just for
-the sake of people running GNU software on Unix, which is a secondary
-application only.}
-
-@item manext
-The file name extension for the installed man page. This should contain
-a period followed by the appropriate digit; it should normally be @samp{.1}.
-
-@item man1ext
-The file name extension for installed section 1 man pages.
-@item man2ext
-The file name extension for installed section 2 man pages.
-@item @dots{}
-Use these names instead of @samp{manext} if the package needs to install man
-pages in more than one section of the manual.
-@end table
-
-And finally, you should set the following variable:
-
-@table @samp
-@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:
-
-@smallexample
-@c I have changed some of the comments here slightly to fix an overfull
-@c hbox, so the make manual can format correctly. --roland
-# Common prefix for installation directories.
-# NOTE: This directory must exist when you start the install.
-prefix = /usr/local
-exec_prefix = $(prefix)
-# Where to put the executable for the command `gcc'.
-bindir = $(exec_prefix)/bin
-# Where to put the directories used by the compiler.
-libexecdir = $(exec_prefix)/libexec
-# Where to put the Info files.
-infodir = $(prefix)/info
-@end smallexample
-
-If your program installs a large number of files into one of the
-standard user-specified directories, it might be useful to group them
-into a subdirectory particular to that program. If you do this, you
-should write the @code{install} rule to create these subdirectories.
-
-Do not expect the user to include the subdirectory name in the value of
-any of the variables listed above. The idea of having a uniform set of
-variable names for installation directories is to enable the user to
-specify the exact same values for several different GNU packages. In
-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
-$(DESTDIR)$(infodir)/foo.info: foo.info
- $(POST_INSTALL)
-# 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 $(DESTDIR)$@@; \
-# 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=$(DESTDIR)$(infodir)/dir \
- $(DESTDIR)$(infodir)/foo.info; \
- else true; fi
-@end smallexample
-
-When writing the @code{install} target, you must classify all the
-commands into three categories: normal ones, @dfn{pre-installation}
-commands and @dfn{post-installation} commands. @xref{Install Command
-Categories}.
-
-@item uninstall
-Delete all the installed files---the copies that the @samp{install}
-target creates.
-
-This rule should not modify the directories where compilation is done,
-only the directories where files are installed.
-
-The uninstallation commands are divided into three categories, just like
-the installation commands. @xref{Install Command Categories}.
-
-@item install-strip
-Like @code{install}, but strip the executable files while installing
-them. In many cases, the definition of this target can be very simple:
-
-@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.
-
-Normally a GNU distribution comes with Info files, and that means the
-Info files are present in the source directory. Therefore, the Make
-rule for an info file should update it in the source directory. When
-users build the package, ordinarily Make will not update the Info files
-because they will already be up to date.
-
-@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 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
-
-@node Install Command Categories
-@section Install Command Categories
-
-@cindex pre-installation commands
-@cindex post-installation commands
-When writing the @code{install} target, you must classify all the
-commands into three categories: normal ones, @dfn{pre-installation}
-commands and @dfn{post-installation} commands.
-
-Normal commands move files into their proper places, and set their
-modes. They may not alter any files except the ones that come entirely
-from the package they belong to.
-
-Pre-installation and post-installation commands may alter other files;
-in particular, they can edit global configuration files or data bases.
-
-Pre-installation commands are typically executed before the normal
-commands, and post-installation commands are typically run after the
-normal commands.
-
-The most common use for a post-installation command is to run
-@code{install-info}. This cannot be done with a normal command, since
-it alters a file (the Info directory) which does not come entirely and
-solely from the package being installed. It is a post-installation
-command because it needs to be done after the normal command which
-installs the package's Info files.
-
-Most programs don't need any pre-installation commands, but we have the
-feature just in case it is needed.
-
-To classify the commands in the @code{install} rule into these three
-categories, insert @dfn{category lines} among them. A category line
-specifies the category for the commands that follow.
-
-A category line consists of a tab and a reference to a special Make
-variable, plus an optional comment at the end. There are three
-variables you can use, one for each category; the variable name
-specifies the category. Category lines are no-ops in ordinary execution
-because these three Make variables are normally undefined (and you
-@emph{should not} define them in the makefile).
-
-Here are the three possible category lines, each with a comment that
-explains what it means:
-
-@smallexample
- $(PRE_INSTALL) # @r{Pre-install commands follow.}
- $(POST_INSTALL) # @r{Post-install commands follow.}
- $(NORMAL_INSTALL) # @r{Normal commands follow.}
-@end smallexample
-
-If you don't use a category line at the beginning of the @code{install}
-rule, all the commands are classified as normal until the first category
-line. If you don't use any category lines, all the commands are
-classified as normal.
-
-These are the category lines for @code{uninstall}:
-
-@smallexample
- $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
- $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
- $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
-@end smallexample
-
-Typically, a pre-uninstall command would be used for deleting entries
-from the Info directory.
-
-If the @code{install} or @code{uninstall} target has any dependencies
-which act as subroutines of installation, then you should start
-@emph{each} dependency's commands with a category line, and start the
-main target's commands with a category line also. This way, you can
-ensure that each command is placed in the right category regardless of
-which of the dependencies actually run.
-
-Pre-installation and post-installation commands should not run any
-programs except for these:
-
-@example
-[ basename bash cat chgrp chmod chown cmp cp dd diff echo
-egrep expand expr false fgrep find getopt grep gunzip gzip
-hostname install install-info kill ldconfig ln ls md5sum
-mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
-test touch true uname xargs yes
-@end example
-
-@cindex binary packages
-The reason for distinguishing the commands in this way is for the sake
-of making binary packages. Typically a binary package contains all the
-executables and other files that need to be installed, and has its own
-method of installing them---so it does not need to run the normal
-installation commands. But installing the binary package does need to
-execute the pre-installation and post-installation commands.
-
-Programs to build binary packages work by extracting the
-pre-installation and post-installation commands. Here is one way of
-extracting the pre-installation commands:
-
-@smallexample
-make -n install -o all \
- PRE_INSTALL=pre-install \
- POST_INSTALL=post-install \
- NORMAL_INSTALL=normal-install \
- | gawk -f pre-install.awk
-@end smallexample
-
-@noindent
-where the file @file{pre-install.awk} could contain this:
-
-@smallexample
-$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
-on @{print $0@}
-$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
-@end smallexample
-
-The resulting file of pre-installation commands is executed as a shell
-script as part of installing the binary package.
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename standards.info
-@settitle GNU Coding Standards
-@c This date is automagically updated when you save this file:
-@set lastupdate May 13, 2000
-@c %**end of header
-
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* Standards: (standards). GNU coding standards.
-END-INFO-DIR-ENTRY
-@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, 1995, 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@end ifinfo
-
-@titlepage
-@title GNU Coding Standards
-@author Richard Stallman
-@author last updated @value{lastupdate}
-@page
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@end titlepage
-
-@ifinfo
-@node Top, Preface, (dir), (dir)
-@top Version
-
-Last updated @value{lastupdate}.
-@end ifinfo
-
-@menu
-* Preface:: About the GNU Coding Standards
-* Legal Issues:: 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
-* Managing Releases:: The Release Process
-* References:: References to Non-Free Software or Documentation
-@end menu
-
-@node Preface
-@chapter About the GNU Coding Standards
-
-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 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.
-
-Corrections or suggestions for this document should be sent to
-@email{gnu@@gnu.org}. If you make a suggestion, please include a
-suggested new wording for it; our time is limited. We prefer a context
-diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
-you don't have those files, please mail your suggestion anyway.
-
-This release of the GNU Coding Standards was last updated
-@value{lastupdate}.
-
-@node Legal Issues
-@chapter Keeping Free Software Free
-
-This @value{CHAPTER} discusses how you can make sure that GNU software
-avoids legal difficulties, and other related issues.
-
-@menu
-* Reading Non-Free Code:: Referring to Proprietary Programs
-* Contributions:: Accepting Contributions
-* Trademarks:: How We Deal with Trademark Issues
-@end menu
-
-@node Reading Non-Free Code
-@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.)
-
-If you have a vague recollection of the internals of a Unix program,
-this does not absolutely mean you can't write an imitation of it, but
-do try to organize the imitation internally along different lines,
-because this is likely to make the details of the Unix version
-irrelevant and dissimilar to your results.
-
-For example, Unix utilities were generally optimized to minimize
-memory use; if you go for speed instead, your program will be very
-different. You could keep the entire input file in core and scan it
-there instead of using stdio. Use a smarter algorithm discovered more
-recently than the Unix program. Eliminate use of temporary files. Do
-it in one pass instead of two (we did this in the assembler).
-
-Or, on the contrary, emphasize simplicity instead of speed. For some
-applications, the speed of today's computers makes simpler algorithms
-adequate.
-
-Or go for generality. For example, Unix programs often have static
-tables or fixed-size strings, which make for arbitrary limits; use
-dynamic allocation instead. Make sure your program handles NULs and
-other funny characters in the input files. Add a programming language
-for extensibility and write part of the program in that language.
-
-Or turn some parts of the program into independently usable libraries.
-Or use a simple garbage collector instead of tracking precisely when
-to free memory, or use a new GNU facility such as obstacks.
-
-@node Contributions
-@section Accepting Contributions
-
-If the program you are working on is copyrighted by the Free Software
-Foundation, then when someone else sends you a piece of code to add to
-the program, we need legal papers to use it---just as we asked you to
-sign papers initially. @emph{Each} person who makes a nontrivial
-contribution to a program must sign some sort of legal papers in order
-for us to have clear title to the program; the main author alone is not
-enough.
-
-So, before adding in any contributions from other people, please tell
-us, so we can arrange to get the papers. Then wait until we tell you
-that we have received the signed papers, before you actually use the
-contribution.
-
-This applies both before you release the program and afterward. If
-you receive diffs to fix a bug, and they make significant changes, we
-need legal papers for that change.
-
-This also applies to comments and documentation files. For copyright
-law, comments and code are just text. Copyright applies to all kinds of
-text, so we need legal papers for all kinds.
-
-We know it is frustrating to ask for legal papers; 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!
-
-You don't need papers for changes of a few lines here or there, since
-they are not significant for copyright purposes. Also, you don't need
-papers if all you get from the suggestion is some ideas, not actual code
-which you use. For example, if someone send you one implementation, but
-you write a different implementation of the same idea, you don't need to
-get papers.
-
-The very worst thing is if you forget to tell us about the other
-contributor. We could be very embarrassed in court some day as a
-result.
-
-We have more detailed advice for maintainers of programs; if you have
-reached the stage of actually maintaining a program for GNU (whether
-released or not), please ask us for a copy.
-
-@node Trademarks
-@section Trademarks
-
-Please do not include any trademark acknowledgements in GNU software
-packages or documentation.
-
-Trademark acknowledgements are the statements that such-and-such is a
-trademark of so-and-so. The GNU Project has no objection to the basic
-idea of trademarks, but these acknowledgements feel like kowtowing, so
-we don't use them. There is no legal requirement for them.
-
-What is legally required, as regards other people's trademarks, is to
-avoid using them in ways which a reader might read as naming or labeling
-our own programs or activities. For example, since ``Objective C'' is
-(or at least was) a trademark, we made sure to say that we provide a
-``compiler for the Objective C language'' rather than an ``Objective C
-compiler''. The latter is meant to be short for the former, but it does
-not explicitly state the relationship, so it could be misinterpreted as
-using ``Objective C'' as a label for the compiler rather than for the
-language.
-
-@node Design Advice
-@chapter General Program Design
-
-This @value{CHAPTER} discusses some of the issues you should take into
-account when designing your program.
-
-@c Standard or ANSI C
-@c
-@c In 1989 the American National Standards Institute (ANSI) standardized
-@c C as standard X3.159-1989. In December of that year the
-@c International Standards Organization ISO adopted the ANSI C standard
-@c making minor changes. In 1990 ANSI then re-adopted ISO standard
-@c C. This version of C is known as either ANSI C or Standard C.
-
-@menu
-* Source Language:: Which languges to use.
-* Compatibility:: Compatibility with other implementations
-* Using Extensions:: Using non-standard features
-* Standard C:: Using Standard (ANSI 1989) C features
-@end menu
-
-@node Source Language
-@section Which Languages to Use
-
-When you want to use a language that gets compiled and runs at high
-speed, the best language to use is C. Using another language is like
-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. For example, if you write your program in C++, people will
-have to install the GNU C++ compiler in order to compile your program.
-
-C has one other advantage over C++ and other compiled languages: more
-people know C, so more people will find it easy to read and modify the
-program if it is written in C.
-
-So in general it is much better to use use C, rather than the
-comparable alternatives.
-
-But there are two exceptions to that conclusion:
-
-@itemize @bullet
-@item
-It is no problem to use another language to write a tool specifically
-intended for use with that language. That is 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 of interest only to a narrow part of the community,
-then the question of which language it is written in has less effect on
-other people, so you may as well please yourself.
-@end itemize
-
-Many programs are designed to be extensible: they include an interpreter
-for a language that is higher level than C. Often much of the program
-is written in that language, too. The Emacs editor pioneered this
-technique.
-
-The standard extensibility interpreter for GNU software is GUILE, which
-implements the language Scheme (an especially clean and simple dialect
-of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject
-programs written in other ``scripting languages'' such as Perl and
-Python, but using GUILE is very important for the overall consistency of
-the GNU system.
-
-@node Compatibility
-@section Compatibility with Other Implementations
-
-With occasional exceptions, utility programs and libraries for GNU
-should be upward compatible with those in Berkeley Unix, and upward
-compatible with 1989 Standard C if 1989 Standard C specifies their
-behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
-their behavior.
-
-When these standards conflict, it is useful to offer compatibility
-modes for each of them.
-
-1989 Standard C and @sc{posix} prohibit many kinds of extensions. Feel
-free to make the extensions anyway, and include a @samp{--ansi},
-@samp{--posix}, or @samp{--compatible} option to turn them off.
-However, if the extension has a significant chance of breaking any real
-programs or scripts, then it is not really upward compatible. So you
-should try to redesign its interface to make it upward compatible.
-
-Many GNU programs suppress extensions that conflict with @sc{posix} if the
-environment variable @code{POSIXLY_CORRECT} is defined (even if it is
-defined with a null value). Please make your program recognize this
-variable if appropriate.
-
-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,
-@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 are welcome regardless of whether
-there is any precedent for them.
-
-@node Using Extensions
-@section Using Non-standard Features
-
-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.
-
-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.
-
-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.
-
-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.
-
-An exception to this rule are the large, established programs (such as
-Emacs) which run on a great variety of systems. Using GNU extensions in
-such programs would make many users unhappy, so we don't do that.
-
-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 extremely troublesome in certain cases.
-
-@node Standard C
-@section 1989 Standard C and Pre-Standard C
-
-1989 Standard C is widespread enough now that it is ok to use its
-features in new programs. There is one exception: do not ever use the
-``trigraph'' feature of 1989 Standard C.
-
-However, it is easy to support pre-standard compilers in most programs,
-so if you know how to do that, feel free. If a program you are
-maintaining has such support, you should try to keep it working.
-
-To support pre-standard C, instead of writing function definitions in
-standard prototype form,
-
-@example
-int
-foo (int x, int y)
-@dots{}
-@end example
-
-@noindent
-write the definition in pre-standard style 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
-int foo (int, int);
-@end example
-
-You need such a declaration anyway, in a header file, to get the benefit
-of prototypes in all the files where the function is called. And once
-you have the declaration, you normally lose nothing by writing the
-function definition in the pre-standard style.
-
-This technique does not work for integer types narrower than @code{int}.
-If you think of an argument as being of a type narrower than @code{int},
-declare it as @code{int} instead.
-
-There are a few special cases where this technique is hard to use. For
-example, if a function argument needs to hold the system type
-@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
-@code{int} on some machines; but you cannot use @code{int} instead,
-because @code{dev_t} is wider than @code{int} on some machines. There
-is no type you can safely use on all machines in a non-standard
-definition. The only way to support non-standard C and pass such an
-argument is to check the width of @code{dev_t} using Autoconf and choose
-the argument type accordingly. This may not be worth the trouble.
-
-In order to support pre-standard compilers that do not recognize
-prototypes, you may want to use a preprocessor macro like this:
-
-@example
-/* Declare the prototype for a general external function. */
-#if defined (__STDC__) || defined (WINDOWSNT)
-#define P_(proto) proto
-#else
-#define P_(proto) ()
-#endif
-@end example
-
-@node Program Behavior
-@chapter Program Behavior for All Programs
-
-This @value{CHAPTER} describes conventions for writing robust
-software. It also describes general standards for error messages, the
-command line interface, and how libraries should behave.
-
-@menu
-* Semantics:: Writing robust programs
-* Libraries:: Library behavior
-* Errors:: Formatting error messages
-* User Interfaces:: Standards for command line interfaces
-* Option Table:: Table of long options.
-* Memory Usage:: When and how to care about memory needs
-@end menu
-
-@node Semantics
-@section Writing Robust Programs
-
-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.
-
-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 terminals or printers
-that can't handle those characters.
-Whenever possible, try to make programs work properly with
-sequences of bytes that represent multibyte characters, using encodings
-such as UTF-8 and others.
-
-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.
-
-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.
-
-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}.
-
-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}.
-
-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.
-
-Use @code{getopt_long} to decode arguments, unless the argument syntax
-makes this unreasonable.
-
-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?
-
-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 are supported compatibly by GNU.
-
-The preferred signal handling facilities are the BSD variant of
-@code{signal}, and the @sc{posix} @code{sigaction} function; the
-alternative USG @code{signal} interface is an inferior design.
-
-Nowadays, using the @sc{posix} signal functions may be the easiest way
-to make a program portable. If you use @code{signal}, then on GNU/Linux
-systems running GNU libc version 1, you should include
-@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
-behavior. It is up to you whether to support systems where
-@code{signal} has only the USG behavior, or give up on them.
-
-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.
-
-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.
-
-If you make temporary files, check the @code{TMPDIR} environment
-variable; if that variable is defined, use the specified directory
-instead of @file{/tmp}.
-
-In addition, be aware that there is a possible security problem when
-creating temporary files in directories world-writable directories. In
-C, you can avoid this problem by creating temporary files in this
-manner:
-
-@example
-fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
-@end example
-
-@noindent
-or by using the @code{mkstemps} function from libiberty.
-
-In bash, use @code{set -C} to avoid this problem.
-
-@node Libraries
-@section Library Behavior
-
-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.
-
-Here are certain name conventions for libraries, to avoid name
-conflicts.
-
-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.
-
-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.
-
-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.
-
-Static functions and variables can be used as you like and need not
-fit any naming convention.
-
-@node Errors
-@section Formatting Error Messages
-
-Error messages from compilers should look like this:
-
-@example
-@var{source-file-name}:@var{lineno}: @var{message}
-@end example
-
-@noindent
-If you want to mention the column number, use this format:
-
-@example
-@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
-@end example
-
-@noindent
-Line numbers should start from 1 at the beginning of the file, and
-column numbers should start from 1 at the beginning of the line. (Both
-of these conventions are chosen for compatibility.) Calculate column
-numbers assuming that space and all ASCII printing characters have
-equal width, and assuming tab stops every 8 columns.
-
-Error messages from other noninteractive programs should look like this:
-
-@example
-@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
-@end example
-
-@noindent
-when there is an appropriate source file, or like this:
-
-@example
-@var{program}: @var{message}
-@end example
-
-@noindent
-when there is no relevant source file.
-
-If you want to mention the column number, use this format:
-
-@example
-@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
-@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.
-
-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.
-
-@node User Interfaces
-@section Standards for Command Line Interfaces
-
-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.
-
-Instead, use a run time option or a compilation switch or both
-to select among the alternate behaviors.
-
-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. (Variation in error
-message syntax when using a terminal is ok, because that is a side issue
-that people do not depend on.)
-
-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.
-
-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.
-
-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.
-
-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}.
-
-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 (@pxref{Option Table}).
-
-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} or @samp{--output}). Even if you allow an output
-file name as an ordinary argument for compatibility, try to provide an
-option as another way to specify it. This will lead to more consistency
-among GNU utilities, and fewer idiosyncracies for users to remember.
-
-All programs should support two standard options: @samp{--version}
-and @samp{--help}.
-
-@table @code
-@item --version
-This option should direct the program to print information about its name,
-version, origin and legal status, all on standard output, and then exit
-successfully. Other options and arguments should be ignored once this
-is seen, and the program should not perform its normal function.
-
-The first line is meant to be easy for a program to parse; the version
-number proper starts after the last space. In addition, it contains
-the canonical name for this program, in this format:
-
-@example
-GNU Emacs 19.30
-@end example
-
-@noindent
-The program's name should be a constant string; @emph{don't} compute it
-from @code{argv[0]}. The idea is to state the standard or canonical
-name for the program, not its file name. There are other ways to find
-out the precise file name where a command is found in @code{PATH}.
-
-If the program is a subsidiary part of a larger package, mention the
-package name in parentheses, like this:
-
-@example
-emacsserver (GNU Emacs) 19.30
-@end example
-
-@noindent
-If the package has a version number which is different from this
-program's version number, you can mention the package version number
-just before the close-parenthesis.
-
-If you @strong{need} to mention the version numbers of libraries which
-are distributed separately from the package which contains this program,
-you can do so by printing an additional line of version info for each
-library you want to mention. Use the same format for these lines as for
-the first line.
-
-Please do not mention all of the libraries that the program uses ``just
-for completeness''---that would produce a lot of unhelpful clutter.
-Please mention library version numbers only if you find in practice that
-they are very important to you in debugging.
-
-The following line, after the version number line or lines, should be a
-copyright notice. If more than one copyright notice is called for, put
-each on a separate line.
-
-Next should follow a brief statement that the program is free software,
-and that users are free to copy and change it on certain conditions. If
-the program is covered by the GNU GPL, say so here. Also mention that
-there is no warranty, to the extent permitted by law.
-
-It is ok to finish the output with a list of the major authors of the
-program, as a way of giving credit.
-
-Here's an example of output that follows these rules:
-
-@smallexample
-GNU Emacs 19.34.5
-Copyright (C) 1996 Free Software Foundation, Inc.
-GNU Emacs comes with NO WARRANTY,
-to the extent permitted by law.
-You may redistribute copies of GNU Emacs
-under the terms of the GNU General Public License.
-For more information about these matters,
-see the files named COPYING.
-@end smallexample
-
-You should adapt this to your program, of course, filling in the proper
-year, copyright holder, name of program, and the references to
-distribution terms, and changing the rest of the wording as necessary.
-
-This copyright notice only needs to mention the most recent year in
-which changes were made---there's no need to list the years for previous
-versions' changes. You don't have to mention the name of the program in
-these notices, if that is inconvenient, since it appeared in the first
-line.
-
-@item --help
-This option should output brief documentation for how to invoke the
-program, on standard output, then exit successfully. Other options and
-arguments should be ignored once this is seen, and the program should
-not perform its normal function.
-
-Near the end of the @samp{--help} option's output there should be a line
-that says where to mail bug reports. It should have this format:
-
-@example
-Report bugs to @var{mailing-address}.
-@end example
-@end table
-
-@node Option Table
-@section Table of Long Options
-
-Here is a table of long options used by GNU programs. It is surely
-incomplete, but we aim to list all the options that a new program might
-want to be compatible with. If you use names not already in the table,
-please send @email{gnu@@gnu.org} a list of them, with their
-meanings, so we can update the table.
-
-@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
-
-@table @samp
-@item after-date
-@samp{-N} in @code{tar}.
-
-@item all
-@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
-and @code{unexpand}.
-
-@item all-text
-@samp{-a} in @code{diff}.
-
-@item almost-all
-@samp{-A} in @code{ls}.
-
-@item append
-@samp{-a} in @code{etags}, @code{tee}, @code{time};
-@samp{-r} in @code{tar}.
-
-@item archive
-@samp{-a} in @code{cp}.
-
-@item archive-name
-@samp{-n} in @code{shar}.
-
-@item arglength
-@samp{-l} in @code{m4}.
-
-@item ascii
-@samp{-a} in @code{diff}.
-
-@item assign
-@samp{-v} in @code{gawk}.
-
-@item assume-new
-@samp{-W} in Make.
-
-@item assume-old
-@samp{-o} in Make.
-
-@item auto-check
-@samp{-a} in @code{recode}.
-
-@item auto-pager
-@samp{-a} in @code{wdiff}.
-
-@item auto-reference
-@samp{-A} in @code{ptx}.
-
-@item avoid-wraps
-@samp{-n} in @code{wdiff}.
-
-@item background
-For server programs, run in the background.
-
-@item backward-search
-@samp{-B} in @code{ctags}.
-
-@item basename
-@samp{-f} in @code{shar}.
-
-@item batch
-Used in GDB.
-
-@item baud
-Used in GDB.
-
-@item before
-@samp{-b} in @code{tac}.
-
-@item binary
-@samp{-b} in @code{cpio} and @code{diff}.
-
-@item bits-per-code
-@samp{-b} in @code{shar}.
-
-@item block-size
-Used in @code{cpio} and @code{tar}.
-
-@item blocks
-@samp{-b} in @code{head} and @code{tail}.
-
-@item break-file
-@samp{-b} in @code{ptx}.
-
-@item brief
-Used in various programs to make output shorter.
-
-@item bytes
-@samp{-c} in @code{head}, @code{split}, and @code{tail}.
-
-@item c@t{++}
-@samp{-C} in @code{etags}.
-
-@item catenate
-@samp{-A} in @code{tar}.
-
-@item cd
-Used in various programs to specify the directory to use.
-
-@item changes
-@samp{-c} in @code{chgrp} and @code{chown}.
-
-@item classify
-@samp{-F} in @code{ls}.
-
-@item colons
-@samp{-c} in @code{recode}.
-
-@item command
-@samp{-c} in @code{su};
-@samp{-x} in GDB.
-
-@item compare
-@samp{-d} in @code{tar}.
-
-@item compat
-Used in @code{gawk}.
-
-@item compress
-@samp{-Z} in @code{tar} and @code{shar}.
-
-@item concatenate
-@samp{-A} in @code{tar}.
-
-@item confirmation
-@samp{-w} in @code{tar}.
-
-@item context
-Used in @code{diff}.
-
-@item copyleft
-@samp{-W copyleft} in @code{gawk}.
-
-@item copyright
-@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
-@samp{-W copyright} in @code{gawk}.
-
-@item core
-Used in GDB.
-
-@item count
-@samp{-q} in @code{who}.
-
-@item count-links
-@samp{-l} in @code{du}.
-
-@item create
-Used in @code{tar} and @code{cpio}.
-
-@item cut-mark
-@samp{-c} in @code{shar}.
-
-@item cxref
-@samp{-x} in @code{ctags}.
-
-@item date
-@samp{-d} in @code{touch}.
-
-@item debug
-@samp{-d} in Make and @code{m4};
-@samp{-t} in Bison.
-
-@item define
-@samp{-D} in @code{m4}.
-
-@item defines
-@samp{-d} in Bison and @code{ctags}.
-
-@item delete
-@samp{-D} in @code{tar}.
-
-@item dereference
-@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
-@code{ls}, and @code{tar}.
-
-@item dereference-args
-@samp{-D} in @code{du}.
-
-@item device
-Specify an I/O device (special file name).
-
-@item diacritics
-@samp{-d} in @code{recode}.
-
-@item dictionary-order
-@samp{-d} in @code{look}.
-
-@item diff
-@samp{-d} in @code{tar}.
-
-@item digits
-@samp{-n} in @code{csplit}.
-
-@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 discard-all
-@samp{-x} in @code{strip}.
-
-@item discard-locals
-@samp{-X} in @code{strip}.
-
-@item dry-run
-@samp{-n} in Make.
-
-@item ed
-@samp{-e} in @code{diff}.
-
-@item elide-empty-files
-@samp{-z} in @code{csplit}.
-
-@item end-delete
-@samp{-x} in @code{wdiff}.
-
-@item end-insert
-@samp{-z} in @code{wdiff}.
-
-@item entire-new-file
-@samp{-N} in @code{diff}.
-
-@item environment-overrides
-@samp{-e} in Make.
-
-@item eof
-@samp{-e} in @code{xargs}.
-
-@item epoch
-Used in GDB.
-
-@item error-limit
-Used in @code{makeinfo}.
-
-@item error-output
-@samp{-o} in @code{m4}.
-
-@item escape
-@samp{-b} in @code{ls}.
-
-@item exclude-from
-@samp{-X} in @code{tar}.
-
-@item exec
-Used in GDB.
-
-@item exit
-@samp{-x} in @code{xargs}.
-
-@item exit-0
-@samp{-e} in @code{unshar}.
-
-@item expand-tabs
-@samp{-t} in @code{diff}.
-
-@item expression
-@samp{-e} in @code{sed}.
-
-@item extern-only
-@samp{-g} in @code{nm}.
-
-@item extract
-@samp{-i} in @code{cpio};
-@samp{-x} in @code{tar}.
-
-@item faces
-@samp{-f} in @code{finger}.
-
-@item fast
-@samp{-f} in @code{su}.
-
-@item fatal-warnings
-@samp{-E} in @code{m4}.
-
-@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}.
-
-@item field-separator
-@samp{-F} in @code{gawk}.
-
-@item file-prefix
-@samp{-b} in Bison.
-
-@item file-type
-@samp{-F} in @code{ls}.
-
-@item files-from
-@samp{-T} in @code{tar}.
-
-@item fill-column
-Used in @code{makeinfo}.
-
-@item flag-truncation
-@samp{-F} in @code{ptx}.
-
-@item fixed-output-files
-@samp{-y} in Bison.
-
-@item follow
-@samp{-f} in @code{tail}.
-
-@item footnote-style
-Used in @code{makeinfo}.
-
-@item force
-@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
-
-@item force-prefix
-@samp{-F} in @code{shar}.
-
-@item foreground
-For server programs, run in the foreground;
-in other words, don't do anything special to run the server
-in the background.
-
-@item format
-Used in @code{ls}, @code{time}, and @code{ptx}.
-
-@item freeze-state
-@samp{-F} in @code{m4}.
-
-@item fullname
-Used in GDB.
-
-@item gap-size
-@samp{-g} in @code{ptx}.
-
-@item get
-@samp{-x} in @code{tar}.
-
-@item graphic
-@samp{-i} in @code{ul}.
-
-@item graphics
-@samp{-g} in @code{recode}.
-
-@item group
-@samp{-g} in @code{install}.
-
-@item gzip
-@samp{-z} in @code{tar} and @code{shar}.
-
-@item hashsize
-@samp{-H} in @code{m4}.
-
-@item header
-@samp{-h} in @code{objdump} and @code{recode}
-
-@item heading
-@samp{-H} in @code{who}.
-
-@item help
-Used to ask for brief usage information.
-
-@item here-delimiter
-@samp{-d} in @code{shar}.
-
-@item hide-control-chars
-@samp{-q} in @code{ls}.
-
-@item html
-In @code{makeinfo}, output HTML.
-
-@item idle
-@samp{-u} in @code{who}.
-
-@item ifdef
-@samp{-D} in @code{diff}.
-
-@item ignore
-@samp{-I} in @code{ls};
-@samp{-x} in @code{recode}.
-
-@item ignore-all-space
-@samp{-w} in @code{diff}.
-
-@item ignore-backups
-@samp{-B} in @code{ls}.
-
-@item ignore-blank-lines
-@samp{-B} in @code{diff}.
-
-@item ignore-case
-@samp{-f} in @code{look} and @code{ptx};
-@samp{-i} in @code{diff} and @code{wdiff}.
-
-@item ignore-errors
-@samp{-i} in Make.
-
-@item ignore-file
-@samp{-i} in @code{ptx}.
-
-@item ignore-indentation
-@samp{-I} in @code{etags}.
-
-@item ignore-init-file
-@samp{-f} in Oleo.
-
-@item ignore-interrupts
-@samp{-i} in @code{tee}.
-
-@item ignore-matching-lines
-@samp{-I} in @code{diff}.
-
-@item ignore-space-change
-@samp{-b} in @code{diff}.
-
-@item ignore-zeros
-@samp{-i} in @code{tar}.
-
-@item include
-@samp{-i} in @code{etags};
-@samp{-I} in @code{m4}.
-
-@item include-dir
-@samp{-I} in Make.
-
-@item incremental
-@samp{-G} in @code{tar}.
-
-@item info
-@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
-
-@item init-file
-In some programs, specify the name of the file to read as the user's
-init file.
-
-@item initial
-@samp{-i} in @code{expand}.
-
-@item initial-tab
-@samp{-T} in @code{diff}.
-
-@item inode
-@samp{-i} in @code{ls}.
-
-@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 intermix-type
-@samp{-p} in @code{shar}.
-
-@item iso-8601
-Used in @code{date}
-
-@item jobs
-@samp{-j} in Make.
-
-@item just-print
-@samp{-n} in Make.
-
-@item keep-going
-@samp{-k} in Make.
-
-@item keep-files
-@samp{-k} in @code{csplit}.
-
-@item kilobytes
-@samp{-k} in @code{du} and @code{ls}.
-
-@item language
-@samp{-l} in @code{etags}.
-
-@item less-mode
-@samp{-l} in @code{wdiff}.
-
-@item level-for-gzip
-@samp{-g} in @code{shar}.
-
-@item line-bytes
-@samp{-C} in @code{split}.
-
-@item lines
-Used in @code{split}, @code{head}, and @code{tail}.
-
-@item link
-@samp{-l} in @code{cpio}.
-
-@item lint
-@itemx lint-old
-Used in @code{gawk}.
-
-@item list
-@samp{-t} in @code{cpio};
-@samp{-l} in @code{recode}.
-
-@item list
-@samp{-t} in @code{tar}.
-
-@item literal
-@samp{-N} in @code{ls}.
-
-@item load-average
-@samp{-l} in Make.
-
-@item login
-Used in @code{su}.
-
-@item machine
-No listing of which programs already use this;
-someone should check to
-see if any actually do, and tell @email{gnu@@gnu.org}.
-
-@item macro-name
-@samp{-M} in @code{ptx}.
-
-@item mail
-@samp{-m} in @code{hello} and @code{uname}.
-
-@item make-directories
-@samp{-d} in @code{cpio}.
-
-@item makefile
-@samp{-f} in Make.
-
-@item mapped
-Used in GDB.
-
-@item max-args
-@samp{-n} in @code{xargs}.
-
-@item max-chars
-@samp{-n} in @code{xargs}.
-
-@item max-lines
-@samp{-l} in @code{xargs}.
-
-@item max-load
-@samp{-l} in Make.
-
-@item max-procs
-@samp{-P} in @code{xargs}.
-
-@item mesg
-@samp{-T} in @code{who}.
-
-@item message
-@samp{-T} in @code{who}.
-
-@item minimal
-@samp{-d} in @code{diff}.
-
-@item mixed-uuencode
-@samp{-M} in @code{shar}.
-
-@item mode
-@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
-
-@item modification-time
-@samp{-m} in @code{tar}.
-
-@item multi-volume
-@samp{-M} in @code{tar}.
-
-@item name-prefix
-@samp{-a} in Bison.
-
-@item nesting-limit
-@samp{-L} in @code{m4}.
-
-@item net-headers
-@samp{-a} in @code{shar}.
-
-@item new-file
-@samp{-W} in Make.
-
-@item no-builtin-rules
-@samp{-r} in Make.
-
-@item no-character-count
-@samp{-w} in @code{shar}.
-
-@item no-check-existing
-@samp{-x} in @code{shar}.
-
-@item no-common
-@samp{-3} in @code{wdiff}.
-
-@item no-create
-@samp{-c} in @code{touch}.
-
-@item no-defines
-@samp{-D} in @code{etags}.
-
-@item no-deleted
-@samp{-1} in @code{wdiff}.
-
-@item no-dereference
-@samp{-d} in @code{cp}.
-
-@item no-inserted
-@samp{-2} in @code{wdiff}.
-
-@item no-keep-going
-@samp{-S} in Make.
-
-@item no-lines
-@samp{-l} in Bison.
-
-@item no-piping
-@samp{-P} in @code{shar}.
-
-@item no-prof
-@samp{-e} in @code{gprof}.
-
-@item no-regex
-@samp{-R} in @code{etags}.
-
-@item no-sort
-@samp{-p} in @code{nm}.
-
-@item no-split
-Used in @code{makeinfo}.
-
-@item no-static
-@samp{-a} in @code{gprof}.
-
-@item no-time
-@samp{-E} in @code{gprof}.
-
-@item no-timestamp
-@samp{-m} in @code{shar}.
-
-@item no-validate
-Used in @code{makeinfo}.
-
-@item no-wait
-Used in @code{emacsclient}.
-
-@item no-warn
-Used in various programs to inhibit warnings.
-
-@item node
-@samp{-n} in @code{info}.
-
-@item nodename
-@samp{-n} in @code{uname}.
-
-@item nonmatching
-@samp{-f} in @code{cpio}.
-
-@item nstuff
-@samp{-n} in @code{objdump}.
-
-@item null
-@samp{-0} in @code{xargs}.
-
-@item number
-@samp{-n} in @code{cat}.
-
-@item number-nonblank
-@samp{-b} in @code{cat}.
-
-@item numeric-sort
-@samp{-n} in @code{nm}.
-
-@item numeric-uid-gid
-@samp{-n} in @code{cpio} and @code{ls}.
-
-@item nx
-Used in GDB.
-
-@item old-archive
-@samp{-o} in @code{tar}.
-
-@item old-file
-@samp{-o} in Make.
-
-@item one-file-system
-@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
-
-@item only-file
-@samp{-o} in @code{ptx}.
-
-@item only-prof
-@samp{-f} in @code{gprof}.
-
-@item only-time
-@samp{-F} in @code{gprof}.
-
-@item options
-@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
-@code{fdmountd}, and @code{fdumount}.
-
-@item output
-In various programs, specify the output file name.
-
-@item output-prefix
-@samp{-o} in @code{shar}.
-
-@item override
-@samp{-o} in @code{rm}.
-
-@item overwrite
-@samp{-c} in @code{unshar}.
-
-@item owner
-@samp{-o} in @code{install}.
-
-@item paginate
-@samp{-l} in @code{diff}.
-
-@item paragraph-indent
-Used in @code{makeinfo}.
-
-@item parents
-@samp{-p} in @code{mkdir} and @code{rmdir}.
-
-@item pass-all
-@samp{-p} in @code{ul}.
-
-@item pass-through
-@samp{-p} in @code{cpio}.
-
-@item port
-@samp{-P} in @code{finger}.
-
-@item portability
-@samp{-c} in @code{cpio} and @code{tar}.
-
-@item posix
-Used in @code{gawk}.
-
-@item prefix-builtins
-@samp{-P} in @code{m4}.
-
-@item prefix
-@samp{-f} in @code{csplit}.
-
-@item preserve
-Used in @code{tar} and @code{cp}.
-
-@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 print-chars
-@samp{-L} in @code{cmp}.
-
-@item print-data-base
-@samp{-p} in Make.
-
-@item print-directory
-@samp{-w} in Make.
-
-@item print-file-name
-@samp{-o} in @code{nm}.
-
-@item print-symdefs
-@samp{-s} in @code{nm}.
-
-@item printer
-@samp{-p} in @code{wdiff}.
-
-@item prompt
-@samp{-p} in @code{ed}.
-
-@item proxy
-Specify an HTTP proxy.
-
-@item query-user
-@samp{-X} in @code{shar}.
-
-@item question
-@samp{-q} in Make.
-
-@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 quiet-unshar
-@samp{-Q} in @code{shar}
-
-@item quote-name
-@samp{-Q} in @code{ls}.
-
-@item rcs
-@samp{-n} in @code{diff}.
-
-@item re-interval
-Used in @code{gawk}.
-
-@item read-full-blocks
-@samp{-B} in @code{tar}.
-
-@item readnow
-Used in GDB.
-
-@item recon
-@samp{-n} in Make.
-
-@item record-number
-@samp{-R} in @code{tar}.
-
-@item recursive
-Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
-and @code{rm}.
-
-@item reference-limit
-Used in @code{makeinfo}.
-
-@item references
-@samp{-r} in @code{ptx}.
-
-@item regex
-@samp{-r} in @code{tac} and @code{etags}.
-
-@item release
-@samp{-r} in @code{uname}.
-
-@item reload-state
-@samp{-R} in @code{m4}.
-
-@item relocation
-@samp{-r} in @code{objdump}.
-
-@item rename
-@samp{-r} in @code{cpio}.
-
-@item replace
-@samp{-i} in @code{xargs}.
-
-@item report-identical-files
-@samp{-s} in @code{diff}.
-
-@item reset-access-time
-@samp{-a} in @code{cpio}.
-
-@item reverse
-@samp{-r} in @code{ls} and @code{nm}.
-
-@item reversed-ed
-@samp{-f} in @code{diff}.
-
-@item right-side-defs
-@samp{-R} in @code{ptx}.
-
-@item same-order
-@samp{-s} in @code{tar}.
-
-@item same-permissions
-@samp{-p} in @code{tar}.
-
-@item save
-@samp{-g} in @code{stty}.
-
-@item se
-Used in GDB.
-
-@item sentence-regexp
-@samp{-S} in @code{ptx}.
-
-@item separate-dirs
-@samp{-S} in @code{du}.
-
-@item separator
-@samp{-s} in @code{tac}.
-
-@item sequence
-Used by @code{recode} to chose files or pipes for sequencing passes.
-
-@item shell
-@samp{-s} in @code{su}.
-
-@item show-all
-@samp{-A} in @code{cat}.
-
-@item show-c-function
-@samp{-p} in @code{diff}.
-
-@item show-ends
-@samp{-E} in @code{cat}.
-
-@item show-function-line
-@samp{-F} in @code{diff}.
-
-@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.
-
-@item size
-@samp{-s} in @code{ls}.
-
-@item socket
-Specify a file descriptor for a network server to use for its socket,
-instead of opening and binding a new socket. This provides a way to
-run, in a nonpriveledged process, a server that normally needs a
-reserved port number.
-
-@item sort
-Used in @code{ls}.
-
-@item source
-@samp{-W source} in @code{gawk}.
-
-@item sparse
-@samp{-S} in @code{tar}.
-
-@item speed-large-files
-@samp{-H} in @code{diff}.
-
-@item split-at
-@samp{-E} in @code{unshar}.
-
-@item split-size-limit
-@samp{-L} in @code{shar}.
-
-@item squeeze-blank
-@samp{-s} in @code{cat}.
-
-@item start-delete
-@samp{-w} in @code{wdiff}.
-
-@item start-insert
-@samp{-y} 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 statistics
-@samp{-s} in @code{wdiff}.
-
-@item stdin-file-list
-@samp{-S} in @code{shar}.
-
-@item stop
-@samp{-S} in Make.
-
-@item strict
-@samp{-s} in @code{recode}.
-
-@item strip
-@samp{-s} in @code{install}.
-
-@item strip-all
-@samp{-s} in @code{strip}.
-
-@item strip-debug
-@samp{-S} in @code{strip}.
-
-@item submitter
-@samp{-s} in @code{shar}.
-
-@item suffix
-@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
-
-@item suffix-format
-@samp{-b} in @code{csplit}.
-
-@item sum
-@samp{-s} in @code{gprof}.
-
-@item summarize
-@samp{-s} in @code{du}.
-
-@item symbolic
-@samp{-s} in @code{ln}.
-
-@item symbols
-Used in GDB and @code{objdump}.
-
-@item synclines
-@samp{-s} in @code{m4}.
-
-@item sysname
-@samp{-s} in @code{uname}.
-
-@item tabs
-@samp{-t} in @code{expand} and @code{unexpand}.
-
-@item tabsize
-@samp{-T} in @code{ls}.
-
-@item terminal
-@samp{-T} in @code{tput} and @code{ul}.
-@samp{-t} in @code{wdiff}.
-
-@item text
-@samp{-a} in @code{diff}.
-
-@item text-files
-@samp{-T} in @code{shar}.
-
-@item time
-Used in @code{ls} and @code{touch}.
-
-@item timeout
-Specify how long to wait before giving up on some operation.
-
-@item to-stdout
-@samp{-O} in @code{tar}.
-
-@item total
-@samp{-c} in @code{du}.
-
-@item touch
-@samp{-t} in Make, @code{ranlib}, and @code{recode}.
-
-@item trace
-@samp{-t} in @code{m4}.
-
-@item traditional
-@samp{-t} in @code{hello};
-@samp{-W traditional} in @code{gawk};
-@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
-
-@item tty
-Used in GDB.
-
-@item typedefs
-@samp{-t} in @code{ctags}.
-
-@item typedefs-and-c++
-@samp{-T} in @code{ctags}.
-
-@item typeset-mode
-@samp{-t} in @code{ptx}.
-
-@item uncompress
-@samp{-z} in @code{tar}.
-
-@item unconditional
-@samp{-u} in @code{cpio}.
-
-@item undefine
-@samp{-U} in @code{m4}.
-
-@item undefined-only
-@samp{-u} in @code{nm}.
-
-@item update
-@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
-
-@item usage
-Used in @code{gawk}; same as @samp{--help}.
-
-@item uuencode
-@samp{-B} in @code{shar}.
-
-@item vanilla-operation
-@samp{-V} in @code{shar}.
-
-@item verbose
-Print more information about progress. Many programs support this.
-
-@item verify
-@samp{-W} in @code{tar}.
-
-@item version
-Print the version number.
-
-@item version-control
-@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
-
-@item vgrind
-@samp{-v} in @code{ctags}.
-
-@item volume
-@samp{-V} in @code{tar}.
-
-@item what-if
-@samp{-W} in Make.
-
-@item whole-size-limit
-@samp{-l} in @code{shar}.
-
-@item width
-@samp{-w} in @code{ls} and @code{ptx}.
-
-@item word-regexp
-@samp{-W} in @code{ptx}.
-
-@item writable
-@samp{-T} in @code{who}.
-
-@item zeros
-@samp{-z} in @code{gprof}.
-@end table
-
-@node Memory Usage
-@section Memory Usage
-
-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.
-
-If your program creates complicated data structures, just make them in
-core and give a fatal error if @code{malloc} returns zero.
-
-@node Writing C
-@chapter Making The Best Use of C
-
-This @value{CHAPTER} provides advice on how best to use the C language
-when writing GNU software.
-
-@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
-* Internationalization:: Techniques for internationalization
-* Mmap:: How you can safely use @code{mmap}.
-@end menu
-
-@node Formatting
-@section Formatting Your Source Code
-
-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.
-
-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:
-
-@example
-static char *
-concat (s1, s2) /* Name starts in column zero here */
- char *s1, *s2;
-@{ /* Open brace in column zero here */
- @dots{}
-@}
-@end example
-
-@noindent
-or, if you want to use Standard C syntax, format the definition like
-this:
-
-@example
-static char *
-concat (char *s1, char *s2)
-@{
- @dots{}
-@}
-@end example
-
-In Standard C, if the arguments don't fit nicely on one line,
-split it like this:
-
-@example
-int
-lots_of_args (int an_integer, long a_long, short a_short,
- double a_double, float a_float)
-@dots{}
-@end example
-
-The rest of this section gives our recommendations for other aspects of
-C formatting style. We don't think of them as requirements, because it
-causes no problems for users if two different programs have different
-formatting styles.
-
-But whatever style you use, please use it consistently, since a mixture
-of styles within one program tends to look ugly. If you are
-contributing changes to an existing program, please follow the style of
-that program.
-
-For the body of the function, our recommended style looks like this:
-
-@example
-if (x < foo (y, z))
- haha = bar[4] + 5;
-else
- @{
- while (z)
- @{
- haha += foo (z, z);
- z--;
- @}
- return ++x + bar ();
- @}
-@end example
-
-We find it easier to read a program when it has spaces before the
-open-parentheses and after the commas. Especially after the commas.
-
-When you split an expression into multiple lines, split it
-before an operator, not after one. Here is the right way:
-
-@example
-if (foo_this_is_long && bar > win (x, y, z)
- && remaining_condition)
-@end example
-
-Try to avoid having two operators of different precedence at the same
-level of indentation. For example, don't write this:
-
-@example
-mode = (inmode[j] == VOIDmode
- || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
- ? outmode[j] : inmode[j]);
-@end example
-
-Instead, use extra parentheses so that the indentation shows the nesting:
-
-@example
-mode = ((inmode[j] == VOIDmode
- || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
- ? outmode[j] : inmode[j]);
-@end example
-
-Insert extra parentheses so that Emacs will indent the code properly.
-For example, the following indentation looks nice if you do it by hand,
-
-@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
-
-@noindent
-but Emacs would alter it. Adding a set of parentheses produces
-something that looks equally nice, and which Emacs will preserve:
-
-@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
-
-Format do-while statements like this:
-
-@example
-do
- @{
- a = foo (a);
- @}
-while (a > 0);
-@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
-@section 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 write the comments in a GNU program in English, because English
-is the one language that nearly all programmers in all countries can
-read. If you do not write English well, please write comments in
-English as well as you can, then ask other people to help rewrite them.
-If you can't write comments in English, please find someone to work with
-you and translate your comments into English.
-
-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:
-
-@example
-/* Nonzero means truncate lines in the display;
- zero means continue them. */
-int truncate_lines;
-@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:
-
-@example
-@group
-#ifdef foo
- @dots{}
-#else /* not foo */
- @dots{}
-#endif /* not foo */
-@end group
-@group
-#ifdef foo
- @dots{}
-#endif /* foo */
-@end group
-@end example
-
-@noindent
-but, by contrast, write the comments this way for a @samp{#ifndef}:
-
-@example
-@group
-#ifndef foo
- @dots{}
-#else /* foo */
- @dots{}
-#endif /* foo */
-@end group
-@group
-#ifndef foo
- @dots{}
-#endif /* not foo */
-@end group
-@end example
-
-@node Syntactic Conventions
-@section Clean Use of C Constructs
-
-Please explicitly declare all arguments to functions.
-Don't omit them just because they are @code{int}s.
-
-Some programmers like to use the GCC @samp{-Wall} option, and change the
-code whenever it issues a warning. If you want to do this, then do.
-Other programmers prefer not to use @samp{-Wall}, because it gives
-warnings for valid and legitimate code which they do not want to change.
-If you want to do this, then do. The compiler should be your servant,
-not your master.
-
-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.
-
-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.
-
-Don't use local variables or parameters that shadow global identifiers.
-
-Don't declare multiple variables in one declaration that spans lines.
-Start a new declaration on each line, instead. For example, instead
-of this:
-
-@example
-@group
-int foo,
- bar;
-@end group
-@end example
-
-@noindent
-write either this:
-
-@example
-int foo, bar;
-@end example
-
-@noindent
-or this:
-
-@example
-int foo;
-int bar;
-@end example
-
-@noindent
-(If they are global variables, each should have a comment preceding it
-anyway.)
-
-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:
-
-@example
-if (foo)
- if (bar)
- win ();
- else
- lose ();
-@end example
-
-@noindent
-always like this:
-
-@example
-if (foo)
- @{
- if (bar)
- win ();
- else
- lose ();
- @}
-@end example
-
-If you have an @code{if} statement nested inside of an @code{else}
-statement, either write @code{else if} on one line, like this,
-
-@example
-if (foo)
- @dots{}
-else if (bar)
- @dots{}
-@end example
-
-@noindent
-with its @code{then}-part indented like the preceding @code{then}-part,
-or write the nested @code{if} within braces like this:
-
-@example
-if (foo)
- @dots{}
-else
- @{
- if (bar)
- @dots{}
- @}
-@end example
-
-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.
-
-Try to avoid assignments inside @code{if}-conditions. For example,
-don't write this:
-
-@example
-if ((foo = (char *) malloc (sizeof *foo)) == 0)
- fatal ("virtual memory exhausted");
-@end example
-
-@noindent
-instead, write this:
-
-@example
-foo = (char *) malloc (sizeof *foo);
-if (foo == 0)
- fatal ("virtual memory exhausted");
-@end example
-
-Don't make the program ugly to placate @code{lint}. Please don't insert any
-casts to @code{void}. Zero without a cast is perfectly fine as a null
-pointer constant, except when calling a varargs function.
-
-@node Names
-@section Naming Variables and Functions
-
-The names of global variables and functions in a program serve as
-comments of a sort. So don't choose terse names---instead, look for
-names that give useful information about the meaning of the variable or
-function. In a GNU program, names should be English, like other
-comments.
-
-Local variable names can be shorter, because they are used only within
-one context, where (presumably) comments explain their purpose.
-
-Try to limit your use of abbreviations in symbol names. It is ok to
-make a few abbreviations, explain what they mean, and then use them
-frequently, but don't use lots of obscure abbreviations.
-
-Please use underscores to separate words in a name, so that the Emacs
-word commands can be useful within them. Stick to lower case; reserve
-upper case for macros and @code{enum} constants, and for name-prefixes
-that follow a uniform convention.
-
-For example, you should use names like @code{ignore_space_change_flag};
-don't use names like @code{iCantReadThis}.
-
-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,
-
-@example
-@group
-/* Ignore changes in horizontal whitespace (-b). */
-int ignore_space_change_flag;
-@end group
-@end example
-
-When you want to define names with constant integer values, use
-@code{enum} rather than @samp{#define}. GDB knows about enumeration
-constants.
-
-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.
-
-@node System Portability
-@section Portability between System Types
-
-In the Unix world, ``portability'' refers to porting to different Unix
-versions. For a GNU program, this kind of portability is desirable, but
-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.
-
-Avoid using the format of semi-internal data bases (e.g., directories)
-when there is a higher-level alternative (@code{readdir}).
-
-As for systems that are not like Unix, such as MSDOS, Windows, the
-Macintosh, VMS, and MVS, supporting them is often a lot of work. When
-that is the case, it is better to spend your time adding features that
-will be useful on GNU and GNU/Linux, rather than on supporting other
-incompatible systems.
-
-It is a good idea to define the ``feature test macro''
-@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
-or GNU/Linux, this will enable the declarations of GNU library extension
-functions, and that will usually give you a compiler error message if
-you define the same function names in some other way in your program.
-(You don't have to actually @emph{use} these functions, if you prefer
-to make the program more portable to other systems.)
-
-But whether or not you use these GNU extensions, you should avoid
-using their names for any other meanings. Doing so would make it hard
-to move your code into other GNU programs.
-
-@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:
-
-@example
-int c;
-@dots{}
-while ((c = getchar()) != EOF)
- write(file_descriptor, &c, 1);
-@end example
-
-When calling functions, you need not worry about the difference between
-pointers of various types, or between pointers and integers. On most
-machines, there's no difference anyway. As for the few machines where
-there is a difference, all of them support 1989 Standard C, so you can
-use prototypes (perhaps conditionalized to be active only in Standard C)
-to make the code work on those systems.
-
-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:
-
-@example
-error (s, a1, a2, a3)
- char *s;
- char *a1, *a2, *a3;
-@{
- fprintf (stderr, "error: ");
- fprintf (stderr, s, a1, a2, a3);
-@}
-@end example
-
-@noindent
-In practice, this works on all machines, since a pointer is generally
-the widest possible kind of argument; it is much simpler than any
-``correct'' alternative. Be sure @emph{not} to use a prototype for such
-functions.
-
-If you have decided to use 1989 Standard C, then you can instead define
-@code{error} using @file{stdarg.h}, and pass the arguments along to
-@code{vfprintf}.
-
-Avoid casting pointers to integers if you can. Such casts greatly
-reduce portability, and in most programs they are easy to avoid. In the
-cases where casting pointers to integers is essential---such as, a Lisp
-interpreter which stores type information as well as an address in one
-word---you'll have to make explicit provisions to handle different word
-sizes. You will also need to make provision for systems in which the
-normal range of addresses you can get from @code{malloc} starts far away
-from zero.
-
-@node System Functions
-@section Calling System Functions
-
-C implementations differ substantially. 1989 Standard C reduces but does
-not eliminate the incompatibilities; meanwhile, many GNU packages still
-support pre-standard compilers because this is not hard to do. This
-chapter gives recommendations for how to use the more-or-less standard C
-library functions to avoid unnecessary loss of portability.
-
-@itemize @bullet
-@item
-Don't use the return value of @code{sprintf}. It returns the number of
-characters written on some systems, but not on all systems.
-
-@item
-Be aware that @code{vfprintf} is not always available.
-
-@item
-@code{main} should be declared to return type @code{int}. It should
-terminate either by calling @code{exit} or by returning the integer
-status code; make sure it cannot ever return an undefined value.
-
-@item
-Don't declare system functions explicitly.
-
-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.
-
-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
-If you must declare a system function, don't specify the argument types.
-Use an old-style declaration, not a Standard C prototype. The more you
-specify about the function, the more likely a conflict.
-
-@item
-In particular, don't unconditionally declare @code{malloc} or
-@code{realloc}.
-
-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.
-
-Because @code{xmalloc} and @code{xrealloc} are defined in your program,
-you can declare them in other files without any risk of type conflict.
-
-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
-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
-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.
-
-That causes less of a problem than you might think. The newer standard
-string functions should be avoided anyway because many systems still
-don't support them. The string functions you can use are these:
-
-@example
-strcpy strncpy strcat strncat
-strlen strcmp strncmp
-strchr strrchr
-@end example
-
-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.
-
-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.
-
-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.
-
-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
-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:
-
-@example
-#ifndef HAVE_STRCHR
-#define strchr index
-#endif
-#ifndef HAVE_STRRCHR
-#define strrchr rindex
-#endif
-
-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 Internationalization
-@section Internationalization
-
-GNU has a library called GNU gettext that makes it easy to translate the
-messages in a program into various languages. You should use this
-library in every program. Use English for the messages as they appear
-in the program, and let gettext provide the way to translate them into
-other languages.
-
-Using GNU gettext involves putting a call to the @code{gettext} macro
-around each string that might need translation---like this:
-
-@example
-printf (gettext ("Processing file `%s'..."));
-@end example
-
-@noindent
-This permits GNU gettext to replace the string @code{"Processing file
-`%s'..."} with a translated version.
-
-Once a program uses gettext, please make a point of writing calls to
-@code{gettext} when you add new strings that call for translation.
-
-Using GNU gettext in a package involves specifying a @dfn{text domain
-name} for the package. The text domain name is used to separate the
-translations for this package from the translations for other packages.
-Normally, the text domain name should be the same as the name of the
-package---for example, @samp{fileutils} for the GNU file utilities.
-
-To enable gettext to work well, avoid writing code that makes
-assumptions about the structure of words or sentences. When you want
-the precise text of a sentence to vary depending on the data, use two or
-more alternative string constants each containing a complete sentences,
-rather than inserting conditionalized words or phrases into a single
-sentence framework.
-
-Here is an example of what not to do:
-
-@example
-printf ("%d file%s processed", nfiles,
- nfiles != 1 ? "s" : "");
-@end example
-
-@noindent
-The problem with that example is that it assumes that plurals are made
-by adding `s'. If you apply gettext to the format string, like this,
-
-@example
-printf (gettext ("%d file%s processed"), nfiles,
- nfiles != 1 ? "s" : "");
-@end example
-
-@noindent
-the message can use different words, but it will still be forced to use
-`s' for the plural. Here is a better way:
-
-@example
-printf ((nfiles != 1 ? "%d files processed"
- : "%d file processed"),
- nfiles);
-@end example
-
-@noindent
-This way, you can apply gettext to each of the two strings
-independently:
-
-@example
-printf ((nfiles != 1 ? gettext ("%d files processed")
- : gettext ("%d file processed")),
- nfiles);
-@end example
-
-@noindent
-This can be any method of forming the plural of the word for ``file'', and
-also handles languages that require agreement in the word for
-``processed''.
-
-A similar problem appears at the level of sentence structure with this
-code:
-
-@example
-printf ("# Implicit rule search has%s been done.\n",
- f->tried_implicit ? "" : " not");
-@end example
-
-@noindent
-Adding @code{gettext} calls to this code cannot give correct results for
-all languages, because negation in some languages requires adding words
-at more than one place in the sentence. By contrast, adding
-@code{gettext} calls does the job straightfowardly if the code starts
-out like this:
-
-@example
-printf (f->tried_implicit
- ? "# Implicit rule search has been done.\n",
- : "# Implicit rule search has not been done.\n");
-@end example
-
-@node Mmap
-@section Mmap
-
-Don't assume that @code{mmap} either works on all files or fails
-for all files. It may work on some files and fail on others.
-
-The proper way to use @code{mmap} is to try it on the specific file for
-which you want to use it---and if @code{mmap} doesn't work, fall back on
-doing the job in another way using @code{read} and @code{write}.
-
-The reason this precaution is needed is that the GNU kernel (the HURD)
-provides a user-extensible file system, in which there can be many
-different kinds of ``ordinary files.'' Many of them support
-@code{mmap}, but some do not. It is important to make programs handle
-all these kinds of files.
-
-@node Documentation
-@chapter Documenting Programs
-
-@menu
-* GNU Manuals:: Writing proper manuals.
-* Manual Structure Details:: Specific structure conventions.
-* License for Manuals:: Writing the distribution terms for a manual.
-* NEWS File:: NEWS files supplement manuals.
-* Change Logs:: Recording Changes
-* Man Pages:: Man pages are secondary.
-* Reading other Manuals:: How far you can go in learning
- from other manuals.
-@end menu
-
-@node GNU Manuals
-@section GNU Manuals
-
-The preferred way to document part of the GNU system is to write a
-manual in the Texinfo formatting language. This makes it possible to
-produce a good quality formatted book, using @TeX{}, and to generate an
-Info file. It is also possible to generate HTML output from Texinfo
-source. See the Texinfo manual, either the hardcopy, or the on-line
-version available through @code{info} or the Emacs Info subsystem
-(@kbd{C-h i}).
-
-Programmers often find it most natural to structure the documentation
-following the structure of the implementation, which they know. But
-this structure is not necessarily good for explaining how to use the
-program; it may be irrelevant and confusing for a user.
-
-At every level, from the sentences in a paragraph to the grouping of
-topics into separate manuals, the right way to structure documentation
-is according to the concepts and questions that a user will have in mind
-when reading it. Sometimes this structure of ideas matches the
-structure of the implementation of the software being documented---but
-often they are different. Often the most important part of learning to
-write good documentation is learning to notice when you are structuring
-the documentation like the implementation, and think about better
-alternatives.
-
-For example, each program in the GNU system probably ought to be
-documented in one manual; but this does not mean each program should
-have its own manual. That would be following the structure of the
-implementation, rather than the structure that helps the user
-understand.
-
-Instead, each manual should cover a coherent @emph{topic}. For example,
-instead of a manual for @code{diff} and a manual for @code{diff3}, we
-have one manual for ``comparison of files'' which covers both of those
-programs, as well as @code{cmp}. By documenting these programs
-together, we can make the whole subject clearer.
-
-The manual which discusses a program should document all of the
-program's command-line options and all of its commands. It should give
-examples of their use. But don't organize the manual as a list of
-features. Instead, organize it logically, by subtopics. Address the
-questions that a user will ask when thinking about the job that the
-program does.
-
-In general, a GNU manual should serve both as tutorial and reference.
-It should be set up for convenient access to each topic through Info,
-and for reading straight through (appendixes aside). A GNU manual
-should give a good introduction to a beginner reading through from the
-start, and should also provide all the details that hackers want.
-The Bison manual is a good example of this---please take a look at it
-to see what we mean.
-
-That is not as hard as it first sounds. Arrange each chapter as a
-logical breakdown of its topic, but order the sections, and write their
-text, so that reading the chapter straight through makes sense. Do
-likewise when structuring the book into chapters, and when structuring a
-section into paragraphs. The watchword is, @emph{at each point, address
-the most fundamental and important issue raised by the preceding text.}
-
-If necessary, add extra chapters at the beginning of the manual which
-are purely tutorial and cover the basics of the subject. These provide
-the framework for a beginner to understand the rest of the manual. The
-Bison manual provides a good example of how to do this.
-
-Don't use Unix man pages as a model for how to write GNU documentation;
-most of them are terse, badly structured, and give inadequate
-explanation of the underlying concepts. (There are, of course
-exceptions.) Also Unix man pages use a particular format which is
-different from what we use in GNU manuals.
-
-Please include an email address in the manual for where to report
-bugs @emph{in the manual}.
-
-Please do not use the term ``pathname'' that is used in Unix
-documentation; use ``file name'' (two words) instead. We use the term
-``path'' only for search paths, which are lists of directory names.
-
-Please do not use the term ``illegal'' to refer to erroneous input to a
-computer program. Please use ``invalid'' for this, and reserve the term
-``illegal'' for violations of law.
-
-@node Manual Structure Details
-@section Manual Structure Details
-
-The title page of the manual should state the version of the programs or
-packages documented in the manual. The Top node of the manual should
-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.
-
-Each program documented in the manual should have a node named
-@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
-node (together with its subnodes, if any) should describe the program's
-command line arguments and how to run it (the sort of information people
-would look in a man page for). Start with an @samp{@@example}
-containing a template for all the options and arguments that the program
-uses.
-
-Alternatively, put a menu item in some menu whose item name fits one of
-the above patterns. This identifies the node which that item points to
-as the node for this purpose, regardless of the node's actual name.
-
-There will be automatic features for specifying a program name and
-quickly reading just this part of its manual.
-
-If one manual describes several programs, it should have such a node for
-each program described.
-
-@node License for Manuals
-@section License for Manuals
-
-If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
-contains chapters that make political or personal statements, please
-copy the distribution terms of the GNU Emacs Manual, and adapt it by
-modifying appropriately the list of special chapters that may not be
-modified or deleted.
-
-If the manual does not contain any such chapters, then imitate the
-simpler distribution terms of the Texinfo manual.
-
-@node NEWS File
-@section The NEWS File
-
-In addition to its manual, the package should have a file named
-@file{NEWS} which contains a list of user-visible changes worth
-mentioning. In each new release, add items to the front of the file and
-identify the version they pertain to. Don't discard old items; leave
-them in the file after the newer items. This way, a user upgrading from
-any previous version can see what is new.
-
-If the @file{NEWS} file gets very long, move some of the older items
-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 to describe all the changes made to program source
-files. 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 you eliminate conceptual
-inconsistencies between different parts of a program, by giving you a
-history of how the conflicting concepts arose and who they came from.
-
-@menu
-* Change Log Concepts::
-* Style of Change Logs::
-* Simple Changes::
-* Conditional Changes::
-@end menu
-
-@node Change Log Concepts
-@subsection Change Log Concepts
-
-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.
-
-The change log file is normally called @file{ChangeLog} and covers an
-entire directory. Each directory can have its own change log, or a
-directory can use the change log of its parent directory--it's up to
-you.
-
-Another alternative is to record change log information with a version
-control system such as RCS or CVS. This can be converted automatically
-to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
-@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
-
-There's no need to describe the full purpose of the changes or how they
-work together. If you think that a change calls for explanation, you're
-probably right. Please do explain it---but please put the explanation
-in comments in the code, where people will see it whenever they see the
-code. For example, ``New function'' is enough for the change log when
-you add a function, because there should be a comment before the
-function definition to explain what it does.
-
-However, sometimes it is useful to write one line to describe the
-overall purpose of a batch of changes.
-
-The easiest way to add an entry to @file{ChangeLog} is with the Emacs
-command @kbd{M-x add-change-log-entry}. 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.
-
-@node Style of Change Logs
-@subsection Style of Change Logs
-
-Here are some examples of change log entries:
-
-@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 that entry.
-
-Separate unrelated change log 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.
-
-@node Simple Changes
-@subsection Simple Changes
-
-Certain simple kinds of changes don't need much detail in the change
-log.
-
-When you change the calling sequence of a function in a simple fashion,
-and you change all the callers of the function, there is no need to make
-individual entries for all the callers that you changed. Just write in
-the entry for the function being called, ``All callers changed.''
-
-@example
-* keyboard.c (Fcommand_execute): New arg SPECIAL.
-All callers changed.
-@end example
-
-When you change just comments or doc strings, it is enough to write an
-entry for the file, without mentioning the functions. Just ``Doc
-fixes'' is enough for the change log.
-
-There's no need to make change log entries 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; it is enough to compare what the
-documentation says with the way the program actually works.
-
-@node Conditional Changes
-@subsection Conditional Changes
-
-C programs often contain compile-time @code{#if} conditionals. Many
-changes are conditional; sometimes you add a new definition which is
-entirely contained in a conditional. It is very useful to indicate in
-the change log the conditions for which the change applies.
-
-Our convention for indicating conditional changes is to use square
-brackets around the name of the condition.
-
-Here is a simple example, describing a change which is conditional but
-does not have a function or entity name associated with it:
-
-@example
-* xterm.c [SOLARIS2]: Include string.h.
-@end example
-
-Here is an entry describing a new definition which is entirely
-conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
-used only when @code{HAVE_X_WINDOWS} is defined:
-
-@example
-* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
-@end example
-
-Here is an entry for a change within the function @code{init_display},
-whose definition as a whole is unconditional, but the changes themselves
-are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
-
-@example
-* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
-@end example
-
-Here is an entry for a change that takes affect only when
-a certain macro is @emph{not} defined:
-
-@example
-(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
-@end example
-
-@node Man Pages
-@section Man Pages
-
-In the GNU project, man pages are secondary. It is not necessary or
-expected for every GNU program to have a man page, but some of them do.
-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
-@section Reading other Manuals
-
-There may be non-free books or documentation files that describe the
-program you are documenting.
-
-It is ok to use these documents for reference, just as the author of a
-new algebra textbook can read other books on algebra. A large portion
-of any non-fiction book consists of facts, in this case facts about how
-a certain program works, and these facts are necessarily the same for
-everyone who writes about the subject. But be careful not to copy your
-outline structure, wording, tables or examples from preexisting non-free
-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{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
-@samp{gdb},
-@samp{x},
-and
-@samp{x-toolkit}.
-
-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
-@section Making Releases
-
-Package the distribution of @code{Foo version 69.96} up in a gzipped tar
-file with the name @file{foo-69.96.tar.gz}. It should unpack into a
-subdirectory named @file{foo-69.96}.
-
-Building and installing the program should never modify any of the files
-contained in the distribution. This means that all the files that form
-part of the program in any way must be classified into @dfn{source
-files} and @dfn{non-source files}. Source files are written by humans
-and never changed automatically; non-source files are produced from
-source files by programs under the control of the Makefile.
-
-The distribution should contain a file named @file{README} which gives
-the name of the package, and a general description of what it does. It
-is also good to explain the purpose of each of the first-level
-subdirectories in the package, if there are any. The @file{README} file
-should either state the version number of the package, or refer to where
-in the package it can be found.
-
-The @file{README} file should refer to the file @file{INSTALL}, which
-should contain an explanation of the installation procedure.
-
-The @file{README} file should also refer to the file which contains the
-copying conditions. The GNU GPL, if used, should be in a file called
-@file{COPYING}. If the GNU LGPL is used, it should be in a file called
-@file{COPYING.LIB}.
-
-Naturally, all the source files must be in the distribution. It is okay
-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, @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.
-
-Non-source files that might actually be modified by building and
-installing the program should @strong{never} be included in the
-distribution. So if you do distribute non-source files, always make
-sure they are up to date when you make a new distribution.
-
-Make sure that the directory into which the distribution unpacks (as
-well as any subdirectories) are all world-writable (octal mode 777).
-This is so that old versions of @code{tar} which preserve the
-ownership and permissions of the files from the tar archive will be
-able to extract all the files even if the user is unprivileged.
-
-Make sure that all the files in the distribution are world-readable.
-
-Make sure that no file name in the distribution is more than 14
-characters long. Likewise, no file created by building the program
-should have a name longer than 14 characters. The reason for this is
-that some systems adhere to a foolish interpretation of the @sc{posix}
-standard, and refuse to open a longer name, rather than truncating as
-they did in the past.
-
-Don't include any symbolic links in the distribution itself. If the tar
-file contains symbolic links, then people cannot even unpack it on
-systems that don't support symbolic links. Also, don't use multiple
-names for one file in different directories, because certain file
-systems cannot handle this and that prevents unpacking the
-distribution.
-
-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} 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.
-Leaving them out would make the distribution file a little smaller at
-the expense of possible inconvenience to a user who doesn't know what
-other files to get.
-
-@node References
-@chapter References to Non-Free Software and Documentation
-
-A GNU program should not recommend use of any non-free program. We
-can't stop some people from writing proprietary programs, or stop other
-people from using them. But we can and should avoid helping to
-advertise them to new customers.
-
-Sometimes it is important to mention how to build your package on top of
-some non-free operating system or other non-free base package. In such
-cases, please mention the name of the non-free package or system in the
-briefest possible way. Don't include any references for where to find
-more information about the proprietary program. The goal should be that
-people already using the proprietary program will get the advice they
-need about how to use your free program, while people who don't already
-use the proprietary program will not see anything to encourage them to
-take an interest in it.
-
-Likewise, a GNU package should not refer the user to any non-free
-documentation for free software. The need for free documentation to go
-with free software is now a major focus of the GNU project; to show that
-we are serious about the need for free documentation, we must not
-undermine our position by recommending use of documentation that isn't
-free.
-
-@contents
-
-@bye
-Local variables:
-update-date-leading-regexp: "@c This date is automagically updated when you save this file:\n@set lastupdate "
-update-date-trailing-regexp: ""
-eval: (load "/gd/gnuorg/update-date.el")
-eval: (add-hook 'write-file-hooks 'update-date)
-End:
git://gcc.gnu.org / gcc.git / commitdiff