From: tomo Date: Thu, 6 Jan 2000 07:14:36 +0000 (+0000) Subject: XEmacs 21.2.24 "Hecate". X-Git-Tag: r21-2-24~2 X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=commitdiff_plain;h=b73e352f264e9da0a00159dc29f318305cbe8636 XEmacs 21.2.24 "Hecate". --- diff --git a/CHANGES-beta b/CHANGES-beta index 6666b17..27aac64 100644 --- a/CHANGES-beta +++ b/CHANGES-beta @@ -1,4 +1,21 @@ -*- indented-text -*- +to 21.2.24 "Hecate" + +to 21.2.23 "Hebe" +-- MS-Windows selection fixes from Mike Alexander +-- MS-WIndows process handling fixes from Mike Alexander +-- Subwindow GC fix from Andy Piper +-- Various minor fixes from Andy Piper +-- Rewrite module configure support, Martin Buchholz +-- Various Windows fixes, Martin Buchholz, Adrian Aichner, Andy Piper +-- HP native compiler compilation fixes, Martin Buchholz +-- Workarounds for Cygnus compiler bugs, Martin Buchholz +-- Workarounds for Cygwin broken header files, Martin Buchholz +-- itimers work again, Kyle Jones +-- random code cleanup, Martin Buchholz +-- various redisplay fixes, Andy Piper, Jan Vroonhof +-- various fixes from Hrvoje Niksic, Yoshiki Hayashi + to 21.2.22 "Mercedes" -- ESD Sound support from Robert Bihlmeyer -- 10% faster redisplay from Jan Vroonhof diff --git a/ChangeLog b/ChangeLog index bba1269..993d2ea 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,29 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-11-30 Martin Buchholz + + * configure.in: Fix module support. + --with-modules=yes was completely broken. + AC_DEFINE(HAVE_DLFCN_H) was invoked twice. + Remove linking test for _dlopen - seems totally bogus. + Die if --with-modules=yes but no module support found. + Do nothing, not even msg, if --with-modules=no. + +1999-11-17 Isaac Hollander + + * Makefile.in.in: add and use TAR macro. Sometimes tar only copies + symlinks instead of the actual files + +1999-11-30 Martin Buchholz + + * aclocal.m4: Shared library support for hpux >= version 11 + +1999-11-29 Martin Buchholz + + * Makefile.in.in (beta): `make beta' should rebuild info. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released @@ -27,7 +53,7 @@ * configure.in (native_sound_lib, *-sgi-*): Check for audio.h. (LIBS): Check for libCsup. - * etc/sample.Xdefaults: adds a reference to beNiceToColrmap, + * etc/sample.Xdefaults: adds a reference to beNiceToColormap, so that the user can guess what to do if xemacs' dialogs are butt ugly. diff --git a/Makefile.in.in b/Makefile.in.in index 3a29d39..8a0b9f0 100644 --- a/Makefile.in.in +++ b/Makefile.in.in @@ -65,6 +65,7 @@ LC_ALL = C RM = rm -f MAKEPATH=./lib-src/make-path pwd = /bin/pwd +TAR = tar ## ==================== Things `configure' Might Edit ==================== @@ -260,7 +261,7 @@ ${PROGNAME}: ${GENERATED_HEADERS} ${MAKE_SUBDIR} ${GENERATED_LISP} .PHONY: ${SUBDIR} all beta all-elc all-elcs dump-elc dump-elcs autoloads finder ## Convenience target for XEmacs beta testers -beta: clean all-elc finder +beta: clean all-elc finder info ## Convenience target for XEmacs maintainers ## This would run `make-xemacsdist' if I were really confident that everything @@ -460,8 +461,8 @@ install-arch-indep: mkdir info -a "`(cd $${dir} && $(pwd))`" != \ "`(cd $${dest} && $(pwd))`" \ && (echo "Copying $${dir}..." ; \ - (cd $${dir} && tar -cf - . ) | \ - (cd $${dest} && umask 022 && tar -xf - );\ + (cd $${dir} && $(TAR) -cf - . ) | \ + (cd $${dest} && umask 022 && $(TAR) -xf - );\ chmod 0755 $${dest}; \ for subdir in `find $${dest} -type d ! -name RCS ! -name SCCS ! -name CVS -print` ; do \ (cd $${subdir} && $(RM) -r RCS CVS SCCS \#* *~) ; \ diff --git a/aclocal.m4 b/aclocal.m4 index 5635441..e1a8e77 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -108,7 +108,7 @@ if test "$XEGCC" = yes; then else # PORTME Check for PIC flags for the system compiler. case "$xehost_os" in - hpux9* | hpux10*) + hpux9* | hpux1[[0-9]]*) # Is there a better link_static_flag that works with the bundled CC? wl='-Wl,' dll_cflags='+Z' diff --git a/configure b/configure index cf53d2e..4090984 100755 --- a/configure +++ b/configure @@ -7766,7 +7766,7 @@ EOF lwlib_objs="$lwlib_objs lwlib-Xaw.o" && if test "$extra_verbose" = "yes"; then echo " Appending \"lwlib-Xaw.o\" to \$lwlib_objs"; fi if test "$have_xaw3d"; then - libs_x="-lXaw3d $libs_x" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-lXaw3d\" to \$libs_x"; fi + libs_x="-lXaw3d $libs_x" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-lXaw3d\" to \$libs_x"; fi else libs_x="-lXaw $libs_x" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-lXaw\" to \$libs_x"; fi fi ;; @@ -11842,19 +11842,21 @@ EOF LIBS="-Bstatic -lut -Bdynamic $LIBS" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-Bstatic -lut -Bdynamic\" to \$LIBS"; fi fi -for ac_hdr in dlfcn.h -do -ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'` -echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6 -echo "configure:11850: checking for $ac_hdr" >&5 +if test "$with_modules" != "no"; then + echo "checking for module support" 1>&6 +echo "configure:11848: checking for module support" >&5 + + ac_safe=`echo "dlfcn.h" | sed 'y%./+-%__p_%'` +echo $ac_n "checking for dlfcn.h""... $ac_c" 1>&6 +echo "configure:11852: checking for dlfcn.h" >&5 cat > conftest.$ac_ext < +#include EOF ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" -{ (eval echo configure:11858: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } +{ (eval echo configure:11860: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; } ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"` if test -z "$ac_err"; then rm -rf conftest* @@ -11869,36 +11871,15 @@ fi rm -f conftest* if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then echo "$ac_t""yes" 1>&6 - ac_tr_hdr=HAVE_`echo $ac_hdr | sed 'y%abcdefghijklmnopqrstuvwxyz./-%ABCDEFGHIJKLMNOPQRSTUVWXYZ___%'` - { test "$extra_verbose" = "yes" && cat << EOF - Defining $ac_tr_hdr -EOF -cat >> confdefs.h <> confdefs.h <<\EOF -#define HAVE_DLFCN_H 1 -EOF -} - -else - echo "$ac_t""no" 1>&6 -fi -done - -test -z "$with_modules" && test ! -z "$have_dlfcn" && { + + echo $ac_n "checking for dlopen in -ldl""... $ac_c" 1>&6 -echo "configure:11897: checking for dlopen in -ldl" >&5 +echo "configure:11878: checking for dlopen in -ldl" >&5 ac_lib_var=`echo dl'_'dlopen | sed 'y%./+-%__p_%'` xe_check_libs=" -ldl " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11894: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11923,38 +11904,28 @@ xe_check_libs="" if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then echo "$ac_t""yes" 1>&6 - { test "$extra_verbose" = "yes" && cat << \EOF - Defining HAVE_DLOPEN -EOF -cat >> confdefs.h <<\EOF -#define HAVE_DLOPEN 1 -EOF -} - DLL_LIB=dl; with_modules=yes + have_dl=yes libdl=dl else echo "$ac_t""no" 1>&6 -fi - } -test -z "$with_modules" && test ! -z "$have_dlfcn" && { -echo $ac_n "checking for _dlopen in -lc""... $ac_c" 1>&6 -echo "configure:11942: checking for _dlopen in -lc" >&5 -ac_lib_var=`echo c'_'_dlopen | sed 'y%./+-%__p_%'` +echo $ac_n "checking for dlopen in -lc""... $ac_c" 1>&6 +echo "configure:11913: checking for dlopen in -lc" >&5 +ac_lib_var=`echo c'_'dlopen | sed 'y%./+-%__p_%'` xe_check_libs=" -lc " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11929: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -11968,72 +11939,37 @@ xe_check_libs="" if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then echo "$ac_t""yes" 1>&6 - { test "$extra_verbose" = "yes" && cat << \EOF - Defining HAVE_DLOPEN -EOF -cat >> confdefs.h <<\EOF -#define HAVE_DLOPEN 1 -EOF -} - DLL_LIB=; with_modules=yes + have_dl=yes else echo "$ac_t""no" 1>&6 fi - } -test -z "$with_modules" && test ! -z "$have_dlfcn" && { -echo $ac_n "checking for dlopen in -lc""... $ac_c" 1>&6 -echo "configure:11987: checking for dlopen in -lc" >&5 -ac_lib_var=`echo c'_'dlopen | sed 'y%./+-%__p_%'` -xe_check_libs=" -lc " -cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then - rm -rf conftest* - eval "ac_cv_lib_$ac_lib_var=yes" else - echo "configure: failed program was:" >&5 - cat conftest.$ac_ext >&5 - rm -rf conftest* - eval "ac_cv_lib_$ac_lib_var=no" + echo "$ac_t""no" 1>&6 fi -rm -f conftest* -xe_check_libs="" -if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then - echo "$ac_t""yes" 1>&6 - { test "$extra_verbose" = "yes" && cat << \EOF + if test -n "$have_dl"; then + { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_DLOPEN EOF cat >> confdefs.h <<\EOF #define HAVE_DLOPEN 1 EOF } - DLL_LIB=; with_modules=yes -else - echo "$ac_t""no" 1>&6 -fi - } -test -z "$with_modules" && { + else + echo $ac_n "checking for shl_load in -ldld""... $ac_c" 1>&6 -echo "configure:12032: checking for shl_load in -ldld" >&5 +echo "configure:11968: checking for shl_load in -ldld" >&5 ac_lib_var=`echo dld'_'shl_load | sed 'y%./+-%__p_%'` xe_check_libs=" -ldld " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:11984: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -12058,27 +11994,25 @@ xe_check_libs="" if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then echo "$ac_t""yes" 1>&6 - { test "$extra_verbose" = "yes" && cat << \EOF + libdl=dld have_dl=yes; + { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_SHL_LOAD EOF cat >> confdefs.h <<\EOF #define HAVE_SHL_LOAD 1 EOF } - DLL_LIB=dld; with_modules=yes + else echo "$ac_t""no" 1>&6 -fi - } -test -z "$with_modules" && { echo $ac_n "checking for dld_init in -ldld""... $ac_c" 1>&6 -echo "configure:12077: checking for dld_init in -ldld" >&5 +echo "configure:12011: checking for dld_init in -ldld" >&5 ac_lib_var=`echo dld'_'dld_init | sed 'y%./+-%__p_%'` xe_check_libs=" -ldld " cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12027: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_lib_$ac_lib_var=yes" else @@ -12103,21 +12037,27 @@ xe_check_libs="" if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then echo "$ac_t""yes" 1>&6 - { test "$extra_verbose" = "yes" && cat << \EOF + libdl=dld have_dl=yes; + { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_DLD_INIT EOF cat >> confdefs.h <<\EOF #define HAVE_DLD_INIT 1 EOF } - DLL_LIB=dld; with_modules=yes + else echo "$ac_t""no" 1>&6 fi - } -if test "$with_modules" = "yes"; then - + +fi + + + fi + + if test -n "$have_dl"; then + dll_ld= dll_ldflags= dll_cflags= @@ -12128,7 +12068,7 @@ xehost=$canonical xealias=$internal_configuration echo "checking how to build dynamic libraries for ${xehost}" 1>&6 -echo "configure:12132: checking how to build dynamic libraries for ${xehost}" >&5 +echo "configure:12072: checking how to build dynamic libraries for ${xehost}" >&5 # Transform *-*-linux* to *-*-linux-gnu*, to support old configure scripts. case "$xehost" in *-*-linux-gnu*) ;; @@ -12156,9 +12096,9 @@ if test "$GCC" = "yes"; then XEGCC=yes else echo $ac_n "checking checking whether we are using GNU C""... $ac_c" 1>&6 -echo "configure:12160: checking checking whether we are using GNU C" >&5 +echo "configure:12100: checking checking whether we are using GNU C" >&5 cat > conftest.$ac_ext <&6 -echo "configure:12184: checking how to produce PIC code" >&5 +echo "configure:12124: checking how to produce PIC code" >&5 wl= can_build_shared=yes @@ -12208,7 +12148,7 @@ if test "$XEGCC" = yes; then else # PORTME Check for PIC flags for the system compiler. case "$xehost_os" in - hpux9* | hpux10*) + hpux9* | hpux1[0-9]*) # Is there a better link_static_flag that works with the bundled CC? wl='-Wl,' dll_cflags='+Z' @@ -12273,18 +12213,18 @@ if test -n "$dll_cflags"; then # Check to make sure the dll_cflags actually works. echo $ac_n "checking if PIC flag ${dll_cflags} really works""... $ac_c" 1>&6 -echo "configure:12277: checking if PIC flag ${dll_cflags} really works" >&5 +echo "configure:12217: checking if PIC flag ${dll_cflags} really works" >&5 save_CFLAGS="$CFLAGS" CFLAGS="$CFLAGS $dll_cflags -DPIC" cat > conftest.$ac_ext <&5; (eval $ac_compile) 2>&5; }; then +if { (eval echo configure:12228: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then rm -rf conftest* # On HP-UX, the stripped-down bundled CC doesn't accept +Z, but also @@ -12315,7 +12255,7 @@ cc_produces_so=no xldf= xcldf= echo $ac_n "checking if C compiler can produce shared libraries""... $ac_c" 1>&6 -echo "configure:12319: checking if C compiler can produce shared libraries" >&5 +echo "configure:12259: checking if C compiler can produce shared libraries" >&5 if test "$XEGCC" = yes; then xcldf="-shared" xldf="-shared" @@ -12366,14 +12306,14 @@ if test -n "$xcldf"; then xe_libs= ac_link='${CC-cc} -o conftest $CFLAGS '"$xe_cppflags $xe_ldflags"' conftest.$ac_ext '"$xe_libs"' 1>&5' cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12317: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* cc_produces_so=yes else @@ -12398,7 +12338,7 @@ if test -z "$LTLD"; then if test "$XEGCC" = yes; then # Check if gcc -print-prog-name=ld gives a path. echo $ac_n "checking for ld used by GCC""... $ac_c" 1>&6 -echo "configure:12402: checking for ld used by GCC" >&5 +echo "configure:12342: checking for ld used by GCC" >&5 ac_prog=`($CC -print-prog-name=ld) 2>&5` case "$ac_prog" in # Accept absolute paths. @@ -12423,7 +12363,7 @@ echo "configure:12402: checking for ld used by GCC" >&5 esac else echo $ac_n "checking for GNU ld""... $ac_c" 1>&6 -echo "configure:12427: checking for GNU ld" >&5 +echo "configure:12367: checking for GNU ld" >&5 fi if test -z "$LTLD"; then @@ -12461,7 +12401,7 @@ ld_dynamic_link_flags= # Check to see if it really is or isn't GNU ld. echo $ac_n "checking if the linker is GNU ld""... $ac_c" 1>&6 -echo "configure:12465: checking if the linker is GNU ld" >&5 +echo "configure:12405: checking if the linker is GNU ld" >&5 # I'd rather use --version here, but apparently some GNU ld's only accept -v. if $LTLD -v 2>&1 &5; then xe_gnu_ld=yes @@ -12488,7 +12428,7 @@ else # OK - only NOW do we futz about with ld. # See if the linker supports building shared libraries. echo $ac_n "checking whether the linker supports shared libraries""... $ac_c" 1>&6 -echo "configure:12492: checking whether the linker supports shared libraries" >&5 +echo "configure:12432: checking whether the linker supports shared libraries" >&5 dll_ld=$CC dll_ldflags=$LDFLAGS ld_shlibs=yes @@ -12684,6 +12624,8 @@ fi # End of if test "$can_build_shared" = "yes" + fi + if test "$can_build_shared" = "yes"; then { test "$extra_verbose" = "yes" && cat << \EOF Defining HAVE_SHLIB @@ -12693,21 +12635,18 @@ cat >> confdefs.h <<\EOF EOF } - extra_objs="$extra_objs sysdll.o" && if test "$extra_verbose" = "yes"; then - echo " xemacs will be linked with \"sysdll.o\"" - fi - extra_objs="$extra_objs emodules.o" && if test "$extra_verbose" = "yes"; then - echo " xemacs will be linked with \"emodules.o\"" + extra_objs="$extra_objs sysdll.o emodules.o" && if test "$extra_verbose" = "yes"; then + echo " xemacs will be linked with \"sysdll.o emodules.o\"" fi INSTALL_ARCH_DEP_SUBDIR="$INSTALL_ARCH_DEP_SUBDIR src" && if test "$extra_verbose" = "yes"; then echo " Appending \"src\" to \$INSTALL_ARCH_DEP_SUBDIR"; fi - test ! -z "$DLL_LIB" && LIBS="-l${DLL_LIB} $LIBS" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-l${DLL_LIB}\" to \$LIBS"; fi + test -n "$libdl" && LIBS="-l${libdl} $LIBS" && if test "$extra_verbose" = "yes"; then echo " Prepending \"-l${libdl}\" to \$LIBS"; fi for ac_func in dlerror _dlerror do echo $ac_n "checking for $ac_func""... $ac_c" 1>&6 -echo "configure:12708: checking for $ac_func" >&5 +echo "configure:12647: checking for $ac_func" >&5 cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then +if { (eval echo configure:12673: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then rm -rf conftest* eval "ac_cv_func_$ac_func=yes" else @@ -12757,18 +12696,23 @@ else fi done + with_modules=yes else - echo "configure: warning: disabling shared library support" 1>&2 + if test "$with_modules" = "yes"; then + { echo "Error:" "Required module support cannot be provided." >&2; exit 1; } + else + echo "configure: warning: "Module support cannot be provided."" 1>&2 + fi with_modules=no fi fi cat > conftest.$ac_ext <&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 +if { (eval echo configure:12716: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5 then : else @@ -13365,7 +13309,7 @@ if test ! -z ${emacs_beta_version} ; then xemacs_betaname="-b${emacs_beta_version}" fi else - xemacs_betaname="" + xemacs_betaname="" fi ( @@ -13435,7 +13379,7 @@ test "$with_jpeg" = yes && echo " Compiling in support for JPEG image handling test "$with_tiff" = yes && echo " Compiling in support for TIFF image handling." test "$with_xface" = yes && echo " Compiling in support for X-Face message headers." test "$with_native_sound" = yes && echo " Compiling in native sound support." -test "$with_nas_sound" = yes && echo " Compiling in network sound (NAS) support." +test "$with_nas_sound" = yes && echo " Compiling in network sound (NAS) support." test "$old_nas" = yes && echo " nas library lacks error trapping, will play synchronously." test "$with_esd" = yes && echo " Compiling in support for Enlightened Sound Daemon." @@ -13502,7 +13446,7 @@ case "$with_dialogs" in athena3d ) echo " Using Athena-3d dialog boxes." ;; msw ) echo " Using MS-Windows dialog boxes." ;; esac -test "$with_modules" = "yes" && echo " Compiling in DSO module support." +test "$with_modules" = "yes" && echo " Compiling in dynamic shared object module support." test "$with_clash_detection" = yes && \ echo " Clash detection will use \"$lockdir\" for locking files." echo " movemail will use \"$mail_locking\" for locking mail spool files." @@ -13536,12 +13480,10 @@ test -n "$exec_prefix" && for file in $internal_makefile_list; do test "$file" = src/Makefile.in && \ file="src/Makefile.in:src/Makefile.in.in:src/depend" - ac_output_files="${ac_output_files+$ac_output_files }$file" + ac_output_files="$ac_output_files $file" && if test "$extra_verbose" = "yes"; then echo " Appending \"$file\" to \$ac_output_files"; fi done ac_output_files="$ac_output_files src/paths.h lib-src/config.values" -if test "$with_modules" = "yes"; then - ac_output_files="$ac_output_files lib-src/ellcc.h" -fi +test "$with_modules" = "yes" && ac_output_files="$ac_output_files lib-src/ellcc.h" && if test "$extra_verbose" = "yes"; then echo " Appending \"lib-src/ellcc.h\" to \$ac_output_files"; fi trap '' 1 2 15 diff --git a/configure.in b/configure.in index 2962071..10a1e3e 100644 --- a/configure.in +++ b/configure.in @@ -2942,7 +2942,7 @@ case "$all_widgets" in AC_DEFINE(NEED_ATHENA) XE_APPEND(lwlib-Xaw.o, lwlib_objs) if test "$have_xaw3d"; then - XE_PREPEND(-lXaw3d, libs_x) + XE_PREPEND(-lXaw3d, libs_x) else XE_PREPEND(-lXaw, libs_x) fi ;; @@ -3687,24 +3687,42 @@ if test "$usage_tracking" = "yes"; then fi dnl autodetect dll support -AC_CHECK_HEADERS(dlfcn.h, [have_dlfcn=yes - AC_DEFINE(HAVE_DLFCN_H)]) -test -z "$with_modules" && test ! -z "$have_dlfcn" && { AC_CHECK_LIB(dl, dlopen, [ AC_DEFINE(HAVE_DLOPEN) DLL_LIB=dl; with_modules=yes]) } -test -z "$with_modules" && test ! -z "$have_dlfcn" && { AC_CHECK_LIB(c, _dlopen, [ AC_DEFINE(HAVE_DLOPEN) DLL_LIB=; with_modules=yes]) } -test -z "$with_modules" && test ! -z "$have_dlfcn" && { AC_CHECK_LIB(c, dlopen, [ AC_DEFINE(HAVE_DLOPEN) DLL_LIB=; with_modules=yes]) } -test -z "$with_modules" && { AC_CHECK_LIB(dld, shl_load, [ AC_DEFINE(HAVE_SHL_LOAD) DLL_LIB=dld; with_modules=yes]) } -test -z "$with_modules" && { AC_CHECK_LIB(dld, dld_init, [ AC_DEFINE(HAVE_DLD_INIT) DLL_LIB=dld; with_modules=yes]) } -if test "$with_modules" = "yes"; then - XE_SHLIB_STUFF +if test "$with_modules" != "no"; then + AC_CHECKING(for module support) + + dnl Find headers and libraries + AC_CHECK_HEADER(dlfcn.h, [ + AC_CHECK_LIB(dl, dlopen, [ have_dl=yes libdl=dl], [ + AC_CHECK_LIB(c, dlopen, [ have_dl=yes ])])]) + if test -n "$have_dl"; then + AC_DEFINE(HAVE_DLOPEN) + else + AC_CHECK_LIB(dld, shl_load, [ + libdl=dld have_dl=yes; + AC_DEFINE(HAVE_SHL_LOAD)], [ + AC_CHECK_LIB(dld, dld_init, [ + libdl=dld have_dl=yes; + AC_DEFINE(HAVE_DLD_INIT)])]) + fi + + if test -n "$have_dl"; then + dnl XE_SHLIB_STUFF (in aclocal.m4) defines $can_build_shared + XE_SHLIB_STUFF + fi + if test "$can_build_shared" = "yes"; then AC_DEFINE(HAVE_SHLIB) - XE_ADD_OBJS(sysdll.o) - XE_ADD_OBJS(emodules.o) + XE_ADD_OBJS(sysdll.o emodules.o) XE_APPEND(src, INSTALL_ARCH_DEP_SUBDIR) - test ! -z "$DLL_LIB" && XE_PREPEND(-l${DLL_LIB}, LIBS) + test -n "$libdl" && XE_PREPEND(-l${libdl}, LIBS) AC_CHECK_FUNCS(dlerror _dlerror) + with_modules=yes else - AC_MSG_WARN(disabling shared library support) + if test "$with_modules" = "yes"; then + XE_DIE("Required module support cannot be provided.") + else + AC_MSG_WARN("Module support cannot be provided.") + fi with_modules=no fi fi @@ -4087,7 +4105,7 @@ if test ! -z ${emacs_beta_version} ; then xemacs_betaname="-b${emacs_beta_version}" fi else - xemacs_betaname="" + xemacs_betaname="" fi dnl Start stdout redirection to '| tee -a Installation' @@ -4158,7 +4176,7 @@ test "$with_jpeg" = yes && echo " Compiling in support for JPEG image handling test "$with_tiff" = yes && echo " Compiling in support for TIFF image handling." test "$with_xface" = yes && echo " Compiling in support for X-Face message headers." test "$with_native_sound" = yes && echo " Compiling in native sound support." -test "$with_nas_sound" = yes && echo " Compiling in network sound (NAS) support." +test "$with_nas_sound" = yes && echo " Compiling in network sound (NAS) support." test "$old_nas" = yes && echo " nas library lacks error trapping, will play synchronously." test "$with_esd" = yes && echo " Compiling in support for Enlightened Sound Daemon." @@ -4225,7 +4243,7 @@ case "$with_dialogs" in athena3d ) echo " Using Athena-3d dialog boxes." ;; msw ) echo " Using MS-Windows dialog boxes." ;; esac -test "$with_modules" = "yes" && echo " Compiling in DSO module support." +test "$with_modules" = "yes" && echo " Compiling in dynamic shared object module support." test "$with_clash_detection" = yes && \ echo " Clash detection will use \"$lockdir\" for locking files." echo " movemail will use \"$mail_locking\" for locking mail spool files." @@ -4266,12 +4284,10 @@ dnl except ./Makefile from $srcdir/Makefile.in for file in $internal_makefile_list; do test "$file" = src/Makefile.in && \ file="src/Makefile.in:src/Makefile.in.in:src/depend" - ac_output_files="${ac_output_files+$ac_output_files }$file" + XE_APPEND($file, ac_output_files) done ac_output_files="$ac_output_files src/paths.h lib-src/config.values" -if test "$with_modules" = "yes"; then - ac_output_files="$ac_output_files lib-src/ellcc.h" -fi +test "$with_modules" = "yes" && XE_APPEND(lib-src/ellcc.h, ac_output_files) AC_OUTPUT($ac_output_files, [for dir in . $MAKE_SUBDIR; do diff --git a/dynodump/_dynodump.h b/dynodump/_dynodump.h index c09bd7f..847c4eb 100644 --- a/dynodump/_dynodump.h +++ b/dynodump/_dynodump.h @@ -32,7 +32,7 @@ * Mountain View, California 94043 */ -#pragma ident "@(#) $Id: _dynodump.h,v 1.5 1996/05/23 18:39:07 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: _dynodump.h,v 1.3 1997/05/29 04:22:29 steve Exp $ - SMI" #ifndef _DYNODUMP_DOT_H #define _DYNODUMP_DOT_H diff --git a/dynodump/dynodump.c b/dynodump/dynodump.c index b684813..ff4477d 100644 --- a/dynodump/dynodump.c +++ b/dynodump/dynodump.c @@ -73,7 +73,7 @@ * N.B. The above commentary is not quite correct in the flags have been hardwired * to RTLD_SAVREL. */ -#pragma ident "@(#) $Id: dynodump.c,v 1.8 1996/05/23 18:39:21 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: dynodump.c,v 1.6 1998/03/31 20:10:55 steve Exp $ - SMI" #define __EXTENSIONS__ 1 diff --git a/dynodump/i386/_relocate.c b/dynodump/i386/_relocate.c index d3ec59c..f97dd1b 100644 --- a/dynodump/i386/_relocate.c +++ b/dynodump/i386/_relocate.c @@ -32,7 +32,7 @@ * Mountain View, California 94043 */ -#pragma ident "@(#) $Id: _relocate.c,v 1.4 1995/06/26 20:12:41 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: _relocate.c,v 1.3 1997/05/29 04:23:02 steve Exp $ - SMI" /* LINTLIBRARY */ diff --git a/dynodump/i386/machdep.h b/dynodump/i386/machdep.h index c90e29c..4dc66fe 100644 --- a/dynodump/i386/machdep.h +++ b/dynodump/i386/machdep.h @@ -32,7 +32,7 @@ * Mountain View, California 94043 */ -#pragma ident "@(#) $Id: machdep.h,v 1.2 1995/02/16 22:58:43 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: machdep.h,v 1.3 1997/05/29 04:23:02 steve Exp $ - SMI" /* * Global include file for all sgs Intel machine dependent macros, constants diff --git a/dynodump/ppc/_relocate.c b/dynodump/ppc/_relocate.c index feb5ca9..754b417 100644 --- a/dynodump/ppc/_relocate.c +++ b/dynodump/ppc/_relocate.c @@ -32,7 +32,7 @@ * Mountain View, California 94043 */ -#pragma ident "@(#) $Id: _relocate.c,v 1.3 1995/06/26 20:16:39 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: _relocate.c,v 1.4 1998/03/31 20:10:55 steve Exp $ - SMI" /* LINTLIBRARY */ diff --git a/dynodump/ppc/machdep.h b/dynodump/ppc/machdep.h index 2a3d1e6..a649a9c 100644 --- a/dynodump/ppc/machdep.h +++ b/dynodump/ppc/machdep.h @@ -32,7 +32,7 @@ * Mountain View, California 94043 */ -#pragma ident "@(#) $Id: machdep.h,v 1.2 1995/02/16 22:58:49 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: machdep.h,v 1.3 1997/05/29 04:23:20 steve Exp $ - SMI" /* * Global include file for all sgs PowerPC machine dependent macros, constants diff --git a/dynodump/sparc/_relocate.c b/dynodump/sparc/_relocate.c index 10b0fda..14466f0 100644 --- a/dynodump/sparc/_relocate.c +++ b/dynodump/sparc/_relocate.c @@ -35,7 +35,7 @@ /* * Update the value of the `_edata' and `_end' symbols. */ -#pragma ident "@(#) $Id: _relocate.c,v 1.4 1995/06/26 20:13:26 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: _relocate.c,v 1.4 1998/03/31 20:10:55 steve Exp $ - SMI" #include #include diff --git a/dynodump/sparc/machdep.h b/dynodump/sparc/machdep.h index 972081e..b4b76d8 100644 --- a/dynodump/sparc/machdep.h +++ b/dynodump/sparc/machdep.h @@ -32,7 +32,7 @@ * Mountain View, California 94043 */ -#pragma ident "@(#) $Id: machdep.h,v 1.2 1995/02/16 22:58:55 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: machdep.h,v 1.3 1997/05/29 04:23:26 steve Exp $ - SMI" /* * Global include file for all sgs SPARC machine dependent macros, constants diff --git a/dynodump/syms.c b/dynodump/syms.c index c060f33..0ac5cb8 100644 --- a/dynodump/syms.c +++ b/dynodump/syms.c @@ -35,7 +35,7 @@ /* * Update the value of the `_edata' and `_end' symbols. */ -#pragma ident "@(#) $Id: syms.c,v 1.2 1995/03/06 22:39:22 georgn Exp $ - SMI" +#pragma ident "@(#) $Id: syms.c,v 1.3 1997/05/29 04:22:30 steve Exp $ - SMI" #include #include diff --git a/etc/NEWS b/etc/NEWS index 7267c67..9289e88 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -115,15 +115,6 @@ maintained internally. The new primitives available for this purpose are functions named `user-name-completion' and `user-name-all-completions'. -** Native widgets can be displayed in buffers. - -The glyph system has been extended to allow the display of glyphs that -are implemented as native window-system widgets. Thus you can embed -buttons, scrollbars, combo boxes, edit fields and progress gauges in a -buffer. As a side effect subwindow support now works once again. - -This support is currently only available under MS-Windows. - ** XEmacs can now play sound using Enlightenment Sound Daemon (ESD). It will try NAS first, then ESD, then playing native sound directly. @@ -191,6 +182,29 @@ for PSWrap. * Lisp and internal changes in XEmacs 21.2 ========================================== +** A new portable dumper is available. + +Olivier Galibert has written a portable dumper for XEmacs, based on +initial work by Kyle Jones. Normally, XEmacs C sources link into an +executable called `temacs', which loads the Lisp code and "unexecs" +into a proper `xemacs' executable. The unexec() process is unreliable +and makes XEmacs hard to port to new operating systems, or even to new +releases of old systems. + +A portable dumper is a different approach to dumping: instead of +dumping full-fledged executable, it only dumps out the initialized +data structures (both Lisp and C) into an external file. A normally +running XEmacs only needs to mmap() that file and relocate a bit to +get to the initialized data. In that scheme, there is no difference +between `temacs' and `xemacs'. + +This is all very experimental, though. Configure with `--pdump' to +try testing it. NOTE: it is expected that `make' will fail after +dumping `xemacs.dmp'. This is because Makefiles have not yet been +modified to not expect `temacs' producing an `xemacs' executable. You +can try it out by simply running `src/temacs'. If it starts without +failure, the portable dumping worked. + ** Much effort has been invested to make XEmacs Lisp faster: *** Many basic lisp operations are now faster. @@ -227,6 +241,23 @@ Many operations do not see any improvement. Surprisingly, running Speeding up your favorite slow operation is an excellent project to improve XEmacs. Don't forget to profile! +** Native widgets can be displayed in buffers. + +The glyph system has been extended to allow the display of glyphs that +are implemented as native window-system widgets. Thus you can embed +buttons, scrollbars, combo boxes, edit fields and progress gauges in a +buffer. As a side effect subwindow support now works once again. + +All of this is still very experimental. This support is currently +only available under MS-Windows. (#### Is this true?) + +** user-init-directory is now an absolute, unexpanded path. +Previously, `user-init-directory' used to be relative to +(concat "~" init-file-user). This turned out to be too complicated +for most packages (and some core Lisp files) to use correctly. + +Also, `init-file-user' has been obsoleted in the process. + ** XEmacs finally has an automated test suite! Although this is not yet very sophisticated, it is already responsible for several important bug fixes in XEmacs. To try it out, simply use @@ -258,14 +289,12 @@ now results in something like this: An extra bonus is that checking for circularities is not just friendlier, but actually faster than checking for C-g. -** The new form `ignore-file-errors', similar to `ignore-errors' may -be used as a short-hand for condition-case when you wish to ignore -file-related error. For example: - - (ignore-file-errors (delete-file "foo")) +** Functions for decoding base64 encoding are now available; see +`base64-encode-region', `base64-encode-string', `base64-decode-region' +and `base64-decode-string'. -** The arguments to `locate-file' are now much more "lispy". As -before, the usage is: +** The arguments to `locate-file' are now more Lisp-like. As before, +the usage is: (locate-file FILENAME PATH-LIST &optional SUFFIXES MODE) @@ -295,18 +324,11 @@ characters. For instance: (put-char-table ?c ?\n table) (translate-region (point-min) (point-max) table)) -** The `keywordp' function now returns non-nil only on symbols -interned in the global obarray. For example: - - (keywordp (intern ":foo" [0])) - => nil - (keywordp (intern ":foo")) ; The same as (keywordp :foo) - => t +** The new form `ignore-file-errors', similar to `ignore-errors' may +be used as a short-hand for condition-case when you wish to ignore +file-related error. For example: -This behaviour is compatible with other code which treats symbols -beginning with colon as keywords only if they are interned in the -global obarray. `keywordp' used to wrongly return t in both cases -above. + (ignore-file-errors (delete-file "foo")) ** The first argument to `intern-soft' may now also be a symbol, like with `unintern'. If given a symbol, `intern-soft' will look for that @@ -319,16 +341,18 @@ to check whether a specific symbol is interned in an obarray, e.g.: (intern-soft (make-symbol "foo")) => nil -** Functions for decoding base64 encoding are now available; see -`base64-encode-region', `base64-encode-string', `base64-decode-region' -and `base64-decode-string'. +** The `keywordp' function now returns non-nil only on symbols +interned in the global obarray. For example: -** user-init-directory is now an absolute, unexpanded path. -Previously, `user-init-directory' used to be relative to -(concat "~" init-file-user). This turned out to be too complicated -for most packages (and some core Lisp files) to use correctly. + (keywordp (intern ":foo" [0])) + => nil + (keywordp (intern ":foo")) ; The same as (keywordp :foo) + => t -Also, `init-file-user' has been obsoleted in the process. +This behaviour is compatible with other code which treats symbols +beginning with colon as keywords only if they are interned in the +global obarray. `keywordp' used to wrongly return t in both cases +above. * Changes in XEmacs 21.0 diff --git a/info/emodules.info b/info/emodules.info index b04e884..9b95d11 100644 --- a/info/emodules.info +++ b/info/emodules.info @@ -880,9 +880,9 @@ Index * documentation <1>: Initialization Mode. * documentation: Introduction. * DSO: Introduction. -* ellcc <1>: Introduction. -* ellcc: Using ellcc. * ELLCC: Environment Variables. +* ellcc <1>: Using ellcc. +* ellcc: Introduction. * ELLCFLAGS: Environment Variables. * ELLDLLFLAGS: Environment Variables. * ELLLD: Environment Variables. @@ -901,16 +901,16 @@ Index * header files: Introduction. * help: Introduction. * include files: Required Header File. -* initialization <1>: Required Variables. -* initialization <2>: Initialization Mode. +* initialization <1>: Initialization Mode. +* initialization <2>: Required Variables. * initialization: Required Functions. * linker: Introduction. * linking: Link Mode. * module compiler: Using ellcc. * module format: Annatomy of a Module. * module skeleton: Annatomy of a Module. -* modules_of_module <1>: Required Functions. -* modules_of_module: Loading other Modules. +* modules_of_module <1>: Loading other Modules. +* modules_of_module: Required Functions. * objects, defining: Defining Variables. * objects, Lisp: Defining Variables. * paths: Other ellcc options. diff --git a/info/info.info b/info/info.info index 17280e2..0ef2859 100644 --- a/info/info.info +++ b/info/info.info @@ -31,10 +31,11 @@ File: info.info, Node: Top, Next: Getting Started, Up: (dir) Info: An Introduction ********************* - Info is a program for reading documentation, which you are using now. + Info is a program for reading documentation, which you might be using +now to read this. - To learn how to use Info, type the command `h'. It brings you to a -programmed instruction sequence. + To learn how to use Info, type the command `h' while using the Info +program. It brings you to a programmed instruction sequence. * Menu: @@ -816,24 +817,24 @@ learn how to install an Info file after you have created one.  Tag Table: Node: Top1067 -Node: Getting Started1565 -Node: Help-Small-Screen2313 -Node: Help4062 -Node: Help-P5092 -Node: Help-^L5954 -Node: Help-M8832 -Node: Help-FOO14812 -Node: Help-Adv15550 -Node: Help-Cross18225 -Node: Help-Q18871 -Node: Advanced Info19498 -Node: Expert20476 -Node: Add22990 -Node: Menus26350 -Node: Cross-refs29224 -Node: Tags29926 -Node: Checking31228 -Node: Emacs Info Variables32181 -Node: Creating an Info File33170 +Node: Getting Started1612 +Node: Help-Small-Screen2360 +Node: Help4109 +Node: Help-P5139 +Node: Help-^L6001 +Node: Help-M8879 +Node: Help-FOO14859 +Node: Help-Adv15597 +Node: Help-Cross18272 +Node: Help-Q18918 +Node: Advanced Info19545 +Node: Expert20523 +Node: Add23037 +Node: Menus26397 +Node: Cross-refs29271 +Node: Tags29973 +Node: Checking31275 +Node: Emacs Info Variables32228 +Node: Creating an Info File33217  End Tag Table diff --git a/info/texinfo.info b/info/texinfo.info index 76cc769..9f25e17 100644 --- a/info/texinfo.info +++ b/info/texinfo.info @@ -4,19 +4,19 @@ texinfo.texi. INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Update info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. +* install-info: (texinfo)Invoking install-info. Updating info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. +* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. END-INFO-DIR-ENTRY This file documents Texinfo, a documentation system that can produce -both online information and a printed manual from a single source file. +both on-line information and a printed manual from a single source file. - Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software + Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software Foundation, Inc. - This edition is for Texinfo version 4.0, 28 September 1999. + This edition is for Texinfo version 3.12. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -34,339 +34,317 @@ translation approved by the Free Software Foundation.  Indirect: -texinfo.info-1: 1493 -texinfo.info-2: 49439 -texinfo.info-3: 98206 -texinfo.info-4: 148178 -texinfo.info-5: 197140 -texinfo.info-6: 246982 -texinfo.info-7: 296539 -texinfo.info-8: 346362 -texinfo.info-9: 395696 -texinfo.info-10: 438701 -texinfo.info-11: 479038 -texinfo.info-12: 525104 -texinfo.info-13: 564169 +texinfo.info-1: 1484 +texinfo.info-2: 48703 +texinfo.info-3: 96677 +texinfo.info-4: 146069 +texinfo.info-5: 196042 +texinfo.info-6: 245134 +texinfo.info-7: 293729 +texinfo.info-8: 343544 +texinfo.info-9: 392857 +texinfo.info-10: 435235 +texinfo.info-11: 481351 +texinfo.info-12: 519511  Tag Table: (Indirect) -Node: Top1493 -Node: Copying24618 -Node: Overview26623 -Node: Overview-Footnotes27894 -Ref: Overview-Footnote-127958 -Node: Reporting Bugs28415 -Node: Using Texinfo29914 -Node: Info Files33728 -Node: Info Files-Footnotes38125 -Ref: Info Files-Footnote-138193 -Node: Printed Books38372 -Node: Printed Books-Footnotes41154 -Ref: Printed Books-Footnote-141228 -Node: Formatting Commands41562 -Node: Formatting Commands-Footnotes44559 -Ref: Formatting Commands-Footnote-144645 -Node: Conventions45253 -Node: Comments48014 -Node: Minimum49439 -Node: Six Parts51633 -Node: Short Sample53145 -Node: Acknowledgements and History57226 -Node: Texinfo Mode59241 -Node: Texinfo Mode Overview60613 -Node: Emacs Editing61398 -Node: Inserting63536 -Node: Showing the Structure67817 -Node: Updating Nodes and Menus70132 -Node: Updating Commands71205 -Node: Updating Requirements77249 -Node: Other Updating Commands79530 -Node: Info Formatting82786 -Node: Printing84046 -Node: Texinfo Mode Summary86378 -Node: Beginning a File91134 -Node: Four Parts92025 -Node: Sample Beginning93495 -Node: Header95115 -Node: First Line96519 -Node: Start of Header97493 -Node: setfilename98206 -Node: settitle100557 -Node: setchapternewpage102447 -Node: paragraphindent105299 -Node: exampleindent106606 -Node: End of Header107671 -Node: Info Summary and Permissions108508 -Node: Titlepage & Copyright Page109527 -Node: titlepage111380 -Node: titlepage-Footnotes113916 -Ref: titlepage-Footnote-1113982 -Node: titlefont center sp114256 -Node: title subtitle author115559 -Node: Copyright & Permissions118254 -Node: end titlepage120245 -Node: headings on off121951 -Node: The Top Node124011 -Node: Title of Top Node125166 -Node: Master Menu Parts126402 -Node: Software Copying Permissions128639 -Node: Ending a File129807 -Node: Printing Indices & Menus130662 -Node: Contents133010 -Node: File End136308 -Node: Structuring136981 -Node: Tree Structuring138638 -Node: Structuring Command Types140061 -Node: makeinfo top142383 -Node: chapter143163 -Node: unnumbered & appendix144187 -Node: majorheading & chapheading145032 -Node: section145853 -Node: unnumberedsec appendixsec heading146617 -Node: subsection147606 -Node: unnumberedsubsec appendixsubsec subheading148178 -Node: subsubsection149131 -Node: Raise/lower sections150681 -Node: Nodes152816 -Node: Two Paths153824 -Node: Node Menu Illustration155154 -Node: node158966 -Node: Node Names161787 -Node: Writing a Node163154 -Node: Node Line Tips165190 -Node: Node Line Requirements165984 -Node: First Node167765 -Node: makeinfo top command169209 -Node: Top Node Summary170388 -Node: makeinfo Pointer Creation171838 -Node: anchor172947 -Node: Menus174417 -Node: Menus-Footnotes175570 -Ref: Menus-Footnote-1175628 -Node: Menu Location175921 -Node: Writing a Menu177281 -Node: Menu Parts178344 -Node: Less Cluttered Menu Entry179502 -Node: Menu Example180127 -Node: Other Info Files181648 -Node: Cross References183494 -Node: References184463 -Node: Cross Reference Commands186254 -Node: Cross Reference Parts187313 -Node: xref190163 -Node: Reference Syntax190962 -Node: One Argument192616 -Node: Two Arguments193633 -Node: Three Arguments194748 -Node: Four and Five Arguments197140 -Node: Top Node Naming199552 -Node: ref200562 -Node: pxref201978 -Node: inforef204360 -Node: uref205653 -Node: Marking Text207875 -Node: Indicating208526 -Node: Useful Highlighting210622 -Node: code212245 -Node: kbd215477 -Node: key217348 -Node: samp218681 -Node: var220151 -Node: env222115 -Node: file222678 -Node: command223289 -Node: option223983 -Node: dfn224491 -Node: cite225403 -Node: acronym225859 -Node: url226412 -Node: email227058 -Node: Emphasis227872 -Node: emph & strong228703 -Node: Smallcaps229702 -Node: Fonts231326 -Node: Quotations and Examples232382 -Node: Block Enclosing Commands233993 -Node: quotation235893 -Node: example236983 -Node: noindent238982 -Node: lisp240438 -Node: lisp-Footnotes241105 -Ref: lisp-Footnote-1241161 -Node: small241279 -Node: display243204 -Node: format243998 -Node: exdent244636 -Node: flushleft & flushright245716 -Node: cartouche246982 -Node: Lists and Tables247742 -Node: Introducing Lists248418 -Node: itemize250095 -Node: enumerate252370 -Node: Two-column Tables254903 -Node: table255592 -Node: ftable vtable258049 -Node: itemx259134 -Node: Multi-column Tables260145 -Node: Multitable Column Widths260816 -Node: Multitable Rows262283 -Node: Indices264059 -Node: Index Entries265191 -Node: Predefined Indices266324 -Node: Indexing Commands267321 -Node: Combining Indices271116 -Node: syncodeindex272479 -Node: synindex274141 -Node: New Indices274666 -Node: Insertions276491 -Node: Braces Atsigns277733 -Node: Inserting An Atsign278285 -Node: Inserting Braces278559 -Node: Inserting Space278922 -Node: Not Ending a Sentence279426 -Node: Ending a Sentence280742 -Node: Multiple Spaces281762 -Node: dmn282981 -Node: Inserting Accents284194 -Node: Dots Bullets285971 -Node: dots286779 -Node: bullet287330 -Node: TeX and copyright287727 -Node: tex288294 -Node: copyright symbol288684 -Node: pounds288944 -Node: minus289308 -Node: math290230 -Node: Glyphs290956 -Node: Glyphs Summary292072 -Node: result292700 -Node: expansion293185 -Node: Print Glyph294141 -Node: Error Glyph295018 -Node: Equivalence295851 -Node: Point Glyph296539 -Node: Footnotes298104 -Node: Footnotes-Footnotes298480 -Ref: Footnotes-Footnote-1298546 -Node: Footnote Commands298826 -Node: Footnote Commands-Footnotes300441 -Ref: Footnote Commands-Footnote-1300523 -Node: Footnote Styles300559 -Node: Images303129 -Node: Breaks305394 -Node: Break Commands306825 -Node: Line Breaks307658 -Node: - and hyphenation308676 -Node: w309926 -Node: sp310539 -Node: page310948 -Node: group311325 -Node: need313068 -Node: Definition Commands313798 -Node: Def Cmd Template315372 -Node: Optional Arguments318369 -Node: deffnx319957 -Node: Def Cmds in Detail320898 -Node: Functions Commands322008 -Node: Variables Commands325011 -Node: Typed Functions327094 -Node: Typed Variables330636 -Node: Abstract Objects332619 -Node: Data Types338447 -Node: Def Cmd Conventions339702 -Node: Sample Function Definition340265 -Node: Conditionals343134 -Node: Conditional Commands344239 -Node: Conditional Not Commands345584 -Node: Raw Formatter Commands346362 -Node: set clear value348195 -Node: ifset ifclear349002 -Node: set value352223 -Node: value Example353881 -Node: Internationalization355603 -Node: documentlanguage356135 -Node: documentencoding360438 -Node: Defining New Texinfo Commands361051 -Node: Defining Macros362220 -Node: Invoking Macros364355 -Node: Macro Details366056 -Node: alias367101 -Node: definfoenclose368300 -Node: Hardcopy371050 -Node: Use TeX373074 -Node: Format with tex/texindex373662 -Node: Format with texi2dvi378036 -Node: Print with lpr379477 -Node: Within Emacs381694 -Node: Texinfo Mode Printing382587 -Node: Compile-Command386345 -Node: Requirements Summary387219 -Node: Preparing for TeX388544 -Node: Preparing for TeX-Footnotes392166 -Ref: Preparing for TeX-Footnote-1392248 -Node: Overfull hboxes392347 -Node: smallbook394500 -Node: A4 Paper395696 -Node: pagesizes396588 -Node: Cropmarks and Magnification397773 -Node: PDF Output399832 -Node: Creating and Installing Info Files401043 -Node: Creating an Info File401427 -Node: makeinfo advantages402700 -Node: Invoking makeinfo403624 -Node: makeinfo options404298 -Node: Pointer Validation411542 -Node: makeinfo in Emacs414682 -Node: texinfo-format commands417234 -Node: Batch Formatting418507 -Node: Tag and Split Files419724 -Node: makeinfo html423134 -Node: Install an Info File425154 -Node: Directory File425984 -Node: New Info File427768 -Node: New Info File-Footnotes428867 -Ref: New Info File-Footnote-1428941 -Node: Other Info Directories429022 -Node: Other Info Directories-Footnotes433343 -Ref: Other Info Directories-Footnote-1433435 -Ref: Other Info Directories-Footnote-2433562 -Node: Installing Dir Entries433623 -Node: Invoking install-info435842 -Node: Command List438701 -Node: Tips479038 -Node: Sample Texinfo File490447 -Node: Sample Permissions492566 -Node: Inserting Permissions493608 -Node: ifinfo Permissions495904 -Node: Titlepage Permissions497525 -Node: Include Files498787 -Node: Using Include Files499874 -Node: texinfo-multiple-files-update501829 -Node: Include File Requirements504190 -Node: Sample Include File505435 -Node: Include Files Evolution506942 -Node: Headings508916 -Node: Headings Introduced509553 -Node: Heading Format511441 -Node: Heading Choice513893 -Node: Custom Headings515265 -Node: Catching Mistakes519564 -Node: makeinfo Preferred520853 -Node: Debugging with Info521758 -Node: Debugging with TeX525104 -Node: Using texinfo-show-structure529367 -Node: Using occur532463 -Node: Running Info-Validate533998 -Node: Using Info-validate535059 -Node: Unsplit536889 -Node: Tagifying537935 -Node: Splitting538787 -Node: Refilling Paragraphs540405 -Node: Refilling Paragraphs-Footnotes542059 -Ref: Refilling Paragraphs-Footnote-1542147 -Node: Command Syntax542310 -Node: Obtaining TeX545267 -Node: Command and Variable Index546309 -Node: Concept Index564169 +Node: Top1484 +Node: Copying23799 +Node: Overview25804 +Node: Overview-Footnotes27233 +Ref: Overview-Footnote-127297 +Node: Using Texinfo27769 +Node: Info Files30252 +Node: Info Files-Footnotes34288 +Ref: Info Files-Footnote-134356 +Node: Printed Books34535 +Node: Printed Books-Footnotes37207 +Ref: Printed Books-Footnote-137281 +Node: Formatting Commands37491 +Node: Formatting Commands-Footnotes40318 +Ref: Formatting Commands-Footnote-140404 +Node: Conventions41020 +Node: Comments43582 +Node: Minimum45005 +Node: Six Parts47191 +Node: Short Sample48703 +Node: Acknowledgements52839 +Node: Texinfo Mode53674 +Node: Texinfo Mode Overview55046 +Node: Emacs Editing55822 +Node: Inserting57952 +Node: Showing the Structure62233 +Node: Updating Nodes and Menus64760 +Node: Updating Commands65833 +Node: Updating Requirements71894 +Node: Other Updating Commands74191 +Node: Info Formatting77459 +Node: Printing78717 +Node: Texinfo Mode Summary81062 +Node: Beginning a File85816 +Node: Four Parts86707 +Node: Sample Beginning88177 +Node: Header89797 +Node: First Line91149 +Node: Start of Header92138 +Node: setfilename92851 +Node: settitle94787 +Node: setchapternewpage96677 +Node: paragraphindent99438 +Node: End of Header100920 +Node: Info Summary and Permissions101759 +Node: Titlepage & Copyright Page102778 +Node: titlepage104384 +Node: titlepage-Footnotes106666 +Ref: titlepage-Footnote-1106732 +Node: titlefont center sp107006 +Node: title subtitle author108232 +Node: Copyright & Permissions110504 +Node: end titlepage112505 +Node: headings on off114211 +Node: The Top Node116256 +Node: Title of Top Node117411 +Node: Master Menu Parts118664 +Node: Software Copying Permissions120901 +Node: Ending a File122069 +Node: Printing Indices & Menus122917 +Node: Contents125226 +Node: File End127566 +Node: Structuring128239 +Node: Tree Structuring129896 +Node: Structuring Command Types131339 +Node: makeinfo top133666 +Node: chapter134199 +Node: unnumbered & appendix135223 +Node: majorheading & chapheading136062 +Node: section136883 +Node: unnumberedsec appendixsec heading137647 +Node: subsection138636 +Node: unnumberedsubsec appendixsubsec subheading139208 +Node: subsubsection140161 +Node: Raise/lower sections141711 +Node: Nodes143846 +Node: Two Paths144783 +Node: Node Menu Illustration146069 +Node: node149764 +Node: Node Names152460 +Node: Writing a Node153536 +Node: Node Line Tips155554 +Node: Node Line Requirements156348 +Node: First Node157949 +Node: makeinfo top command159393 +Node: Top Node Summary160572 +Node: makeinfo Pointer Creation162022 +Node: Menus163269 +Node: Menus-Footnotes164208 +Ref: Menus-Footnote-1164266 +Node: Menu Location164559 +Node: Writing a Menu166236 +Node: Menu Parts167202 +Node: Less Cluttered Menu Entry168360 +Node: Menu Example168985 +Node: Other Info Files170506 +Node: Cross References172362 +Node: References173319 +Node: Cross Reference Commands175066 +Node: Cross Reference Parts176125 +Node: xref178961 +Node: Reference Syntax179760 +Node: One Argument181414 +Node: Two Arguments182426 +Node: Three Arguments183541 +Node: Four and Five Arguments185932 +Node: Top Node Naming188344 +Node: ref189354 +Node: pxref190744 +Node: inforef193126 +Node: uref194419 +Node: Marking Text195418 +Node: Indicating196042 +Node: Useful Highlighting197947 +Node: code199336 +Node: kbd202374 +Node: key204244 +Node: samp205577 +Node: var207164 +Node: file208957 +Node: dfn209564 +Node: cite210474 +Node: url210928 +Node: email211492 +Node: Emphasis212304 +Node: emph & strong213204 +Node: Smallcaps214190 +Node: Fonts215517 +Node: Customized Highlighting216605 +Node: Customized Highlighting-Footnotes219420 +Ref: Customized Highlighting-Footnote-1219514 +Node: Quotations and Examples219640 +Node: Block Enclosing Commands221262 +Node: quotation223287 +Node: example224377 +Node: noindent226432 +Node: Lisp Example227896 +Node: Lisp Example-Footnotes228598 +Ref: Lisp Example-Footnote-1228670 +Node: smallexample & smalllisp228788 +Node: display230813 +Node: format231445 +Node: exdent231906 +Node: flushleft & flushright232986 +Node: cartouche234252 +Node: Lists and Tables235019 +Node: Introducing Lists235695 +Node: itemize237360 +Node: enumerate239507 +Node: Two-column Tables242012 +Node: table242701 +Node: ftable vtable245134 +Node: itemx246235 +Node: Multi-column Tables247246 +Node: Multitable Column Widths247917 +Node: Multitable Rows249371 +Node: Indices251148 +Node: Index Entries252298 +Node: Predefined Indices253431 +Node: Indexing Commands254428 +Node: Combining Indices258968 +Node: syncodeindex260331 +Node: synindex261993 +Node: New Indices262518 +Node: Insertions264343 +Node: Braces Atsigns265527 +Node: Inserting An Atsign266079 +Node: Inserting Braces266353 +Node: Inserting Space266716 +Node: Not Ending a Sentence267220 +Node: Ending a Sentence268574 +Node: Multiple Spaces269703 +Node: dmn270922 +Node: Inserting Accents272129 +Node: Dots Bullets273886 +Node: dots274708 +Node: bullet275232 +Node: TeX and copyright275629 +Node: tex276196 +Node: copyright symbol276612 +Node: pounds276872 +Node: minus277236 +Node: math278158 +Node: Glyphs278886 +Node: Glyphs Summary279999 +Node: result280627 +Node: expansion281112 +Node: Print Glyph282068 +Node: Error Glyph282945 +Node: Equivalence283778 +Node: Point Glyph284466 +Node: Images286023 +Node: Breaks287690 +Node: Break Commands289121 +Node: Line Breaks289962 +Node: - and hyphenation290980 +Node: w292230 +Node: sp292943 +Node: page293352 +Node: group293729 +Node: need295472 +Node: Definition Commands296202 +Node: Def Cmd Template297773 +Node: Optional Arguments300770 +Node: deffnx302358 +Node: Def Cmds in Detail303313 +Node: Functions Commands304423 +Node: Variables Commands307428 +Node: Typed Functions309514 +Node: Typed Variables313056 +Node: Abstract Objects315039 +Node: Data Types320264 +Node: Def Cmd Conventions321519 +Node: Sample Function Definition322082 +Node: Footnotes324966 +Node: Footnotes-Footnotes325354 +Ref: Footnotes-Footnote-1325420 +Node: Footnote Commands325700 +Node: Footnote Commands-Footnotes327197 +Ref: Footnote Commands-Footnote-1327279 +Node: Footnote Styles327315 +Node: Conditionals329901 +Node: Conditional Commands330712 +Node: Conditional Not Commands332205 +Node: Raw Formatter Commands332950 +Node: set clear value334780 +Node: ifset ifclear335581 +Node: value338760 +Node: value Example340172 +Node: Macros341750 +Node: Defining Macros342455 +Node: Invoking Macros343544 +Node: Format/Print Hardcopy344650 +Node: Use TeX346487 +Node: Format with tex/texindex347115 +Node: Format with texi2dvi350756 +Node: Print with lpr351347 +Node: Within Emacs352201 +Node: Texinfo Mode Printing353120 +Node: Compile-Command356530 +Node: Requirements Summary357418 +Node: Preparing for TeX358731 +Node: Overfull hboxes361518 +Node: smallbook363077 +Node: A4 Paper364595 +Node: Cropmarks and Magnification365820 +Node: Create an Info File367761 +Node: makeinfo advantages369064 +Node: Invoking makeinfo369980 +Node: makeinfo options370668 +Node: Pointer Validation376152 +Node: makeinfo in Emacs377496 +Node: texinfo-format commands380054 +Node: Batch Formatting381325 +Node: Tag and Split Files382541 +Node: Install an Info File385895 +Node: Directory file386713 +Node: New Info File388581 +Node: Other Info Directories389642 +Node: Installing Dir Entries392857 +Node: Invoking install-info394850 +Node: Command List397265 +Node: Tips435235 +Node: Sample Texinfo File446645 +Node: Sample Permissions448764 +Node: Inserting Permissions449807 +Node: ifinfo Permissions452113 +Node: Titlepage Permissions453734 +Node: Include Files454996 +Node: Using Include Files456083 +Node: texinfo-multiple-files-update458038 +Node: Include File Requirements460399 +Node: Sample Include File461644 +Node: Include Files Evolution463163 +Node: Headings465134 +Node: Headings Introduced465771 +Node: Heading Format467659 +Node: Heading Choice470111 +Node: Custom Headings471483 +Node: Catching Mistakes475811 +Node: makeinfo Preferred477100 +Node: Debugging with Info478005 +Node: Debugging with TeX481351 +Node: Using texinfo-show-structure485631 +Node: Using occur488730 +Node: Running Info-Validate490267 +Node: Using Info-validate491328 +Node: Unsplit493170 +Node: Tagifying494216 +Node: Splitting495068 +Node: Refilling Paragraphs496684 +Node: Refilling Paragraphs-Footnotes498338 +Ref: Refilling Paragraphs-Footnote-1498426 +Node: Command Syntax498589 +Node: Obtaining TeX501546 +Node: Command and Variable Index503659 +Node: Concept Index519511  End Tag Table diff --git a/info/texinfo.info-1 b/info/texinfo.info-1 index 0d1e560..f31fc03 100644 --- a/info/texinfo.info-1 +++ b/info/texinfo.info-1 @@ -4,19 +4,19 @@ texinfo.texi. INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Update info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. +* install-info: (texinfo)Invoking install-info. Updating info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. +* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. END-INFO-DIR-ENTRY This file documents Texinfo, a documentation system that can produce -both online information and a printed manual from a single source file. +both on-line information and a printed manual from a single source file. - Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software + Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software Foundation, Inc. - This edition is for Texinfo version 4.0, 28 September 1999. + This edition is for Texinfo version 3.12. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -33,19 +33,19 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -File: texinfo.info, Node: Top, Next: Copying, Up: (dir) +File: texinfo.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) Texinfo ******* Texinfo is a documentation system that uses a single source file to -produce both online information and printed output. +produce both on-line information and printed output. The first part of this master menu lists the major nodes in this Info document, including the @-command and concept indices. The rest of the menu lists all the lower level nodes in the document. - This is Edition 4.0 of the Texinfo manual, updated 28 September 1999. + This is Edition 3.12 of the Texinfo documentation, 27 February 1998. * Menu: @@ -69,12 +69,13 @@ menu lists all the lower level nodes in the document. * Breaks:: How to force and prevent line and page breaks. * Definition Commands:: How to describe functions and the like in a uniform manner. +* Footnotes:: How to write footnotes. * Conditionals:: How to specify text for either TeX or Info. -* Internationalization:: -* Defining New Texinfo Commands:: -* Hardcopy:: How to convert a Texinfo file to a file +* Macros:: Defining new Texinfo commands. +* Format/Print Hardcopy:: How to convert a Texinfo file to a file for printing and how to print that file. -* Creating and Installing Info Files:: +* Create an Info File:: Convert a Texinfo file into an Info file. +* Install an Info File:: Make an Info file accessible to users. * Command List:: All the Texinfo @-commands. * Tips:: Hints on how to write a Texinfo document. * Sample Texinfo File:: A sample Texinfo file to look at. @@ -94,17 +95,18 @@ menu lists all the lower level nodes in the document. Overview of Texinfo -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. +* Using Texinfo:: Create a conventional printed book + or an Info file. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* Acknowledgements:: Using Texinfo Mode @@ -145,8 +147,7 @@ The Texinfo File Header * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* exampleindent:: Specify environment indentation. +* paragraphindent:: An option to specify paragraph indentation. * End of Header:: Formatting a region requires this. The Title and Copyright Pages @@ -195,9 +196,8 @@ Nodes * Two Paths:: Different commands to structure Info output and printed output. * Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. +* node:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'. The `@node' Command @@ -246,26 +246,23 @@ Marking Words and Phrases Indicating Definitions, Commands, etc. * Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: Showing a literal sequence of characters. -* var:: Indicating metasyntactic variables. -* env:: Indicating environment variables. -* file:: Indicating file names. -* command:: Indicating command names. -* option:: Indicating option names. -* dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. -* acronym:: Indicating acronyms. -* url:: Indicating a World Wide Web reference. -* email:: Indicating an electronic mail address. +* code:: How to indicate code. +* kbd:: How to show keyboard input. +* key:: How to specify keys. +* samp:: How to show a literal sequence of characters. +* var:: How to indicate a metasyntactic variable. +* file:: How to indicate the name of a file. +* dfn:: How to specify a definition. +* cite:: How to refer to a book that is not in Info. +* url:: How to indicate a world wide web reference. +* email:: How to indicate an electronic mail address. Emphasizing Text * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. Quotations and Examples @@ -274,8 +271,8 @@ Quotations and Examples * quotation:: How to write a quotation. * example:: How to write an example in a fixed-width font. * noindent:: How to prevent paragraph indentation. -* lisp:: How to illustrate Lisp code. -* small:: Forms for `@smallbook'. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the `@smallbook' option. * display:: How to write an example in the current font. * format:: How to write an example that does not narrow the margins. @@ -302,7 +299,7 @@ Multi-column Tables * Multitable Column Widths:: Defining multitable column widths. * Multitable Rows:: Defining multitable rows, with examples. -Indices +Creating Indices * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds @@ -332,7 +329,6 @@ Special Insertions * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. -* Footnotes:: How to include footnotes. * Images:: How to include graphics. Inserting @ and Braces @@ -376,11 +372,6 @@ Glyphs Summary * Equivalence:: * Point Glyph:: -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - Making and Preventing Breaks * Break Commands:: Cause and prevent splits. @@ -411,6 +402,11 @@ The Definition Commands * Abstract Objects:: Commands for object-oriented programming. * Data Types:: The definition command for data types. +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. + Conditionally Visible Text * Conditional Commands:: Specifying text for HTML, Info, or TeX. @@ -423,45 +419,30 @@ Conditionally Visible Text `@set', `@clear', and `@value' * ifset ifclear:: Format a region if a flag is set. -* set value:: Expand a flag variable to a string. +* value:: Replace a flag with a string. * value Example:: An easy way to update edition information. -Internationalization +Macros: Defining New Texinfo Commands -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. - -Defining New Texinfo Commands - -* Defining Macros:: Defining and undefining new commands. +* Defining Macros:: Both defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Beyond basic macro usage. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. -Formatting and Printing Hardcopy +Format and Print Hardcopy * Use TeX:: Use TeX to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. +* Format with tex/texindex:: How to format in a shell. +* Format with texi2dvi:: A simpler way to use the shell. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: TeX formatting requirements summary. -* Preparing for TeX:: What to do before you use TeX. +* Preparing for TeX:: What you need to do to use TeX. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on European A4 paper. -* pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. - -Creating and Installing Info Files - -* Creating an Info File:: -* Install an Info File:: Creating an Info File @@ -476,11 +457,10 @@ Creating an Info File * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. -* makeinfo html:: Generating HTML output. Installing an Info File -* Directory File:: The top level menu for all Info files. +* Directory file:: The top level menu for all Info files. * New Info File:: Listing a new info file. * Other Info Directories:: How to specify Info files that are located in other directories. @@ -528,8 +508,7 @@ Finding Badly Referenced Nodes * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. - Documentation is like sex: when it is good, it is very, very good; - and when it is bad, it is better than nothing. --Dick Brandon +How to Obtain TeX  File: texinfo.info, Node: Copying, Next: Overview, Prev: Top, Up: Top @@ -577,80 +556,43 @@ File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: T Overview of Texinfo ******************* - "Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system -that uses a single source file to produce both online information and + "Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system +that uses a single source file to produce both on-line information and printed output. This means that instead of writing two different -documents, one for the online information and the other for a printed -work, you need write only one document. Therefore, when the work is -revised, you need revise only that one document. +documents, one for the on-line help or other on-line information and +the other for a typeset manual or other printed work, you need write +only one document. When the work is revised, you need revise only one +document. (You can read the on-line information, known as an "Info +file", with an Info documentation-reading program.) * Menu: -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. +* Using Texinfo:: Create a conventional printed book + or an Info file. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* Acknowledgements::  File: texinfo.info, Node: Overview-Footnotes, Up: Overview - (1) The first syllable of "Texinfo" is pronounced like "speck", not -"hex". This odd pronunciation is derived from, but is not the same as, -the pronunciation of TeX. In the word TeX, the `X' is actually the -Greek letter "chi" rather than the English letter "ex". Pronounce TeX -as if the `X' were the last sound in the name `Bach'; but pronounce -Texinfo as if the `x' were a `k'. Spell "Texinfo" with a capital "T" -and the other letters in lower case. - - -File: texinfo.info, Node: Reporting Bugs, Next: Using Texinfo, Up: Overview - -Reporting Bugs -============== - - We welcome bug reports or suggestions for the Texinfo system, both -programs and documentation. Please email them to -. You can get the latest version of Texinfo from -`ftp://ftp.gnu.org/gnu/texinfo/' and its mirrors worldwide. - - For bug reports, please include enough information for the maintainers -to reproduce the problem. Generally speaking, that means: - - * the version number of Texinfo and the program(s) or manual(s) - involved. - - * hardware, operating system, and compiler versions. - - * any unusual options you gave to `configure'. - - * the contents of any input files necessary to reproduce the bug. - - * a description of the problem and samples of any erroneous output. - - * anything else that you think would be helpful. - - When in doubt whether something is needed or not, include it. It's -better to include too much than to leave out something important. - - Patches are most welcome; if possible, please make them with -`diff -c' (*note Overview: (diffutils)Top.) and include `ChangeLog' -entries (*note Change Log: (emacs)Change Log.). - - When sending email, please do not encode or split the messages in any -way if possible; it's much easier to deal with one plain text message, -however large, than many small ones. GNU shar -(ftp://ftp.gnu.org/gnu/sharutils/) is a convenient way of packaging -multiple and/or binary files for email. + (1) Note that the first syllable of "Texinfo" is pronounced like +"speck", not "hex". This odd pronunciation is derived from, but is not +the same as, the pronunciation of TeX. In the word TeX, the `X' is +actually the Greek letter "chi" rather than the English letter "ex". +Pronounce TeX as if the `X' were the last sound in the name `Bach'; but +pronounce Texinfo as if the `x' were a `k'. Spell "Texinfo" with a +capital "T" and write the other letters in lower case.  -File: texinfo.info, Node: Using Texinfo, Next: Info Files, Prev: Reporting Bugs, Up: Overview +File: texinfo.info, Node: Using Texinfo, Next: Info Files, Prev: Overview, Up: Overview Using Texinfo ============= @@ -658,71 +600,47 @@ Using Texinfo Using Texinfo, you can create a printed document with the normal features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create a -menu-driven, online Info file with nodes, menus, cross references, and -indices. You can also create from that same source file an HTML output -file suitable for use with a web browser. `The GNU Emacs Manual' is a -good example of a Texinfo file, as is this manual. +menu-driven, on-line Info file with nodes, menus, cross references, and +indices. You can, if you wish, make the chapters and sections of the +printed document correspond to the nodes of the on-line information; +and you use the same cross references and indices for both the Info +file and the printed work. `The GNU Emacs Manual' is a good example of +a Texinfo file, as is this manual. To make a printed document, you process a Texinfo source file with the -TeX typesetting program (but the Texinfo language is very different -from TeX's usual language, plain TeX). This creates a DVI file that -you can typeset and print as a book or report (*note Hardcopy::). - - To output an Info file, process your Texinfo source with the -`makeinfo' utility or Emacs's `texinfo-format-buffer' command. You can -install the result in your Info tree (*note Install an Info File::). - - To output an HTML file, process your Texinfo source with `makeinfo' -using the `--html' option. You can (for example) install the result on -your web site. - - If you are a programmer and would like to contribute to the GNU -project by implementing additional output formats for Texinfo, that -would be excellent. But please do not write a separate translator -texi2foo for your favorite format foo! That is the hard way to do the -job, and makes extra work in subsequent maintenance, since the Texinfo -language is continually being enhanced and updated. Instead, the best -approach is modify `makeinfo' to generate the new format, as it does -now for Info and HTML. - - TeX works with virtually all printers; Info works with virtually all -computer terminals; the HTML output works with virtually all web -browsers. Thus Texinfo can be used by almost any computer user. - - A Texinfo source file is a plain ASCII file containing text and -"@-commands" (words preceded by an `@') that tell the typesetting and -formatting programs what to do. You may edit a Texinfo file with any -text editor; but it is especially convenient to use GNU Emacs since -that editor has a special mode, called Texinfo mode, that provides -various Texinfo-related features. (*Note Texinfo Mode::.) - - Before writing a Texinfo source file, you should learn about nodes, -menus, cross references, and the rest, for example by reading this -manual. - - You can use Texinfo to create both online help and printed manuals; +TeX typesetting program. This creates a DVI file that you can typeset +and print as a book or report. (Note that the Texinfo language is +completely different from TeX's usual language, plain TeX.) If you do +not have TeX, but do have `troff' or `nroff', you can use the +`texi2roff' program instead. + + To make an Info file, you process a Texinfo source file with the +`makeinfo' utility or Emacs's `texinfo-format-buffer' command; this +creates an Info file that you can install on-line. + + TeX and `texi2roff' work with many types of printers; similarly, Info +works with almost every type of computer terminal. This power makes +Texinfo a general purpose system, but brings with it a constraint, +which is that a Texinfo file may contain only the customary +"typewriter" characters (letters, numbers, spaces, and punctuation +marks) but no special graphics. + + A Texinfo file is a plain ASCII file containing text and "@-commands" +(words preceded by an `@') that tell the typesetting and formatting +programs what to do. You may edit a Texinfo file with any text editor; +but it is especially convenient to use GNU Emacs since that editor has +a special mode, called Texinfo mode, that provides various +Texinfo-related features. (*Note Texinfo Mode::.) + + Before writing a Texinfo source file, you should become familiar with +the Info documentation reading program and learn about nodes, menus, +cross references, and the rest. (*note info: (info)Top, for more +information.) + + You can use Texinfo to create both on-line help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the official documentation format of the GNU project. More -information is available at the GNU documentation web page -(http://www.gnu.org/doc/). - - From time to time, proposals are made to generate traditional Unix man -pages from Texinfo source. This is not likely to ever be supported, -because man pages have a very strict conventional format. Merely -enhancing `makeinfo' to output troff format would be insufficient. -Generating a good man page therefore requires a completely different -source than the typical Texinfo applications of generating a good user -manual or a good reference manual. This makes generating man pages -incompatible with the Texinfo design goal of not having to document the -same information in different ways for different output formats. You -might as well just write the man page directly. - - If you wish to support man pages, the program `help2man' may be -useful; it generates a traditional man page from the `--help' output of -a program. In fact, this is currently used to generate man pages for -the Texinfo programs themselves. It is free software written by -Brendan O'Dea, available from -`http://www.ozemail.com.au/~bod/help2man.tar.gz'. +is the format in which documentation for GNU utilities and libraries is +written.  File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Using Texinfo, Up: Overview @@ -802,15 +720,6 @@ with the advanced Info command `g *'. (*note Advanced Info commands: for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system. - If you wish to refer to an Info file in a URI, you can use the -(unofficial) syntax exemplified in the following. This works with -Emacs/W3, for example: - info:///usr/info/emacs#Dissociated%20Press - info:emacs#Dissociated%20Press - info://localhost/usr/info/emacs#Dissociated%20Press - - The `info' program itself does not follow URI's of any kind. -  File: texinfo.info, Node: Info Files-Footnotes, Up: Info Files @@ -834,19 +743,17 @@ as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices. You can use Texinfo to write a book without ever having the intention -of converting it into online information. You can use Texinfo for +of converting it into on-line information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier. TeX is a general purpose typesetting program. Texinfo provides a -file `texinfo.tex' that contains information (definitions or "macros") -that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells -TeX how to convert the Texinfo @-commands to TeX commands, which TeX -can then process to create the typeset document.) `texinfo.tex' -contains the specifications for printing a document. You can get the -latest version of `texinfo.tex' from -`ftp://ftp.gnu.org/gnu/texinfo.tex'. +file called `texinfo.tex' that contains information (definitions or +"macros") that TeX uses when it typesets a Texinfo file. +(`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX +commands, which TeX can then process to create the typeset document.) +`texinfo.tex' contains the specifications for printing a document. Most often, documents are printed on 8.5 inch by 11 inch pages (216mm by 280mm; this is the default size), but you can also print for 7 inch @@ -865,23 +772,22 @@ light-hearted, young and cheery. TeX is freely distributable. It is written in a superset of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the TeX distribution) in C. (*Note -TeX Mode: (emacs)TeX Mode, for information about TeX.) +TeX Mode: (xemacs)TeX Mode, for information about TeX.) TeX is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited. - To get a copy of TeX, see *Note How to Obtain TeX: Obtaining TeX. + *Note How to Obtain TeX: Obtaining TeX.  File: texinfo.info, Node: Printed Books-Footnotes, Up: Printed Books - (1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz) -program if you do not have TeX; since Texinfo is designed for use with -TeX, `texi2roff' is not described here. `texi2roff' is not part of the -standard GNU distribution and is not maintained or up-to-date with all -the Texinfo features described in this manual. + (1) You can also use the `texi2roff' program if you do not have TeX; +since Texinfo is designed for use with TeX, `texi2roff' is not +described here. `texi2roff' is not part of the standard GNU +distribution.  File: texinfo.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview @@ -926,14 +832,11 @@ of their own or as part of sentences: this example, between the braces. (`@code' marks text as being code.) - * Write a command such as `@example' on a line of its own; write the - body-text on following lines; and write the matching `@end' - command, `@end example' in this case, at the on a line of its own - after the body-text. (`@example' ... `@end example' indents and - typesets body-text as an example.) It's usually ok to indent - environment commands like this, but in complicated and - hard-to-define circumstances the extra spaces cause extra space to - appear in the output, so beware. + * Write a command such as `@example' at the beginning of a line of + its own; write the body-text on following lines; and write the + matching `@end' command, `@end example' in this case, at the + beginning of a line of its own after the body-text. (`@example' + ... `@end example' indents and typesets body-text as an example.) As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it starts a line of its own. The @@ -950,14 +853,14 @@ exactly the same syntax. (For details about @-command syntax, see File: texinfo.info, Node: Formatting Commands-Footnotes, Up: Formatting Commands (1) The word "argument" comes from the way it is used in mathematics -and does not refer to a dispute between two people; it refers to the +and does not refer to a disputation between two people; it refers to the information presented to the command. According to the `Oxford English Dictionary', the word derives from the Latin for "to make clear, prove"; thus it came to mean `the evidence offered as proof', which is to say, `the information offered', which led to its mathematical meaning. In its other thread of derivation, the word came to mean `to assert in a manner against which others may make counter assertions', -which led to the meaning of `argument' as a dispute. +which led to the meaning of `argument' as a disputation.  File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview @@ -965,43 +868,37 @@ File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Comma General Syntactic Conventions ============================= - This section describes the general conventions used in all Texinfo -documents. - - * All printable ASCII characters except `@', `{' and `}' can appear - in a Texinfo file and stand for themselves. `@' is the escape - character which introduces commands. `{' and `}' should be used - only to surround arguments to certain commands. To put one of - these special characters into the document, put an `@' character - in front of it, like this: `@@', `@{', and `@}'. - - * It is customary in TeX to use doubled single-quote characters to - begin and end quotations: ` ` and ' ' (but without a space between - the two single-quote characters). This convention should be - followed in Texinfo files. TeX converts doubled single-quote - characters to left- and right-hand doubled quotation marks and - Info converts doubled single-quote characters to ASCII - double-quotes: ` ` and ' ' to " . - - * Use three hyphens in a row, `---', for a dash--like this. In TeX, - a single or double hyphen produces a printed dash that is shorter - than the usual typeset dash. Info reduces three hyphens to two for - display on the screen. - - * To prevent a paragraph from being indented in the printed manual, - put the command `@noindent' on a line by itself before the - paragraph. - - * If you mark off a region of the Texinfo file with the `@iftex' and - `@end iftex' commands, that region will appear only in the printed - copy; in that region, you can use certain commands borrowed from - plain TeX that you cannot use in Info. Likewise, if you mark off - a region with the `@ifinfo' and `@end ifinfo' commands, that - region will appear only in the Info file; in that region, you can - use Info commands that you cannot use in TeX. Similarly for - `@ifhtml ... @end ifhtml', `@ifnothtml ... @end ifnothtml', - `@ifnotinfo ... @end ifnotinfo', `@ifnottex ... @end ifnottex'. - *Note Conditionals::. + All printable ASCII characters except `@', `{' and `}' can appear in +a Texinfo file and stand for themselves. `@' is the escape character +which introduces commands. `{' and `}' should be used only to surround +arguments to certain commands. To put one of these special characters +into the document, put an `@' character in front of it, like this: +`@@', `@{', and `@}'. + + It is customary in TeX to use doubled single-quote characters to +begin and end quotations: ` ` and ' ' (but without a space between the +two single-quote characters). This convention should be followed in +Texinfo files. TeX converts doubled single-quote characters to left- +and right-hand doubled quotation marks and Info converts doubled +single-quote characters to ASCII double-quotes: ` ` and ' ' to " . + + Use three hyphens in a row, `---', for a dash--like this. In TeX, a +single or double hyphen produces a printed dash that is shorter than +the usual typeset dash. Info reduces three hyphens to two for display +on the screen. + + To prevent a paragraph from being indented in the printed manual, put +the command `@noindent' on a line by itself before the paragraph. + + If you mark off a region of the Texinfo file with the `@iftex' and +`@end iftex' commands, that region will appear only in the printed +copy; in that region, you can use certain commands borrowed from plain +TeX that you cannot use in Info. Likewise, if you mark off a region +with the `@ifinfo' and `@end ifinfo' commands, that region will appear +only in the Info file; in that region, you can use Info commands that +you cannot use in TeX. Similarly for `@ifhtml ... @end ifhtml', +`@ifnothtml ... @end ifnothtml', `@ifnotinfo ... @end ifnotinfo', +`@ifnottex ... @end ifnottex', *Note Conditionals::. *Caution:* Do not use tabs in a Texinfo file! TeX uses variable-width fonts, which means that it cannot predefine a tab @@ -1016,6 +913,8 @@ documents. Also, you can run `untabify' in Emacs to convert tabs in a region to multiple spaces. + Don't use tabs. +  File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview @@ -1025,14 +924,14 @@ Comments You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the `@comment' command (which may be abbreviated to `@c'). Such comments are for the -person who revises the Texinfo file. All the text on a line that -follows either `@comment' or `@c' is a comment; the rest of the line -does not appear in either the Info file or the printed manual. (Often, -you can write the `@comment' or `@c' in the middle of a line, and only -the text that follows after the `@comment' or `@c' command does not -appear; but some commands, such as `@settitle' and `@setfilename', work -on a whole line. You cannot use `@comment' or `@c' in a line beginning -with such a command.) +person who reads the Texinfo file. All the text on a line that follows +either `@comment' or `@c' is a comment; the rest of the line does not +appear in either the Info file or the printed manual. (Often, you can +write the `@comment' or `@c' in the middle of a line, and only the text +that follows after the `@comment' or `@c' command does not appear; but +some commands, such as `@settitle' and `@setfilename', work on a whole +line. You cannot use `@comment' or `@c' in a line beginning with such +a command.) You can write long stretches of text that will not appear in either the Info file or the printed manual by using the `@ignore' and `@end @@ -1044,3 +943,100 @@ two commands does not appear in the processed output. You can use applies to the Texinfo source file of a document, but not to the Info or printed version of the document. + +File: texinfo.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview + +What a Texinfo File Must Have +============================= + + By convention, the names of Texinfo files end with one of the +extensions `.texinfo', `.texi', or `.tex'. The longer extension is +preferred since it describes more clearly to a human reader the nature +of the file. The shorter extensions are for operating systems that +cannot handle long file names. + + In order to be made into a printed manual and an Info file, a Texinfo +file *must* begin with lines like this: + + \input texinfo + @setfilename INFO-FILE-NAME + @settitle NAME-OF-MANUAL + +The contents of the file follow this beginning, and then you *must* end +a Texinfo file with a line like this: + + @bye + +The `\input texinfo' line tells TeX to use the `texinfo.tex' file, +which tells TeX how to translate the Texinfo @-commands into TeX +typesetting commands. (Note the use of the backslash, `\'; this is +correct for TeX.) The `@setfilename' line provides a name for the Info +file and tells TeX to open auxiliary files. The `@settitle' line +specifies a title for the page headers (or footers) of the printed +manual. + + The `@bye' line at the end of the file on a line of its own tells the +formatters that the file is ended and to stop formatting. + + Usually, you will not use quite such a spare format, but will include +mode setting and start-of-header and end-of-header lines at the +beginning of a Texinfo file, like this: + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename INFO-FILE-NAME + @settitle NAME-OF-MANUAL + @c %**end of header + +In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo +mode when you edit the file. + + The `@c' lines which surround the `@setfilename' and `@settitle' +lines are optional, but you need them in order to run TeX or Info on +just part of the file. (*Note Start of Header::, for more information.) + + Furthermore, you will usually provide a Texinfo file with a title +page, indices, and the like. But the minimum, which can be useful for +short documents, is just the three lines at the beginning and the one +line at the end. + + +File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview + +Six Parts of a Texinfo File +=========================== + + Generally, a Texinfo file contains more than the minimal beginning +and end--it usually contains six parts: + +1. Header + The "Header" names the file, tells TeX which definitions' file to + use, and performs other "housekeeping" tasks. + +2. Summary Description and Copyright + The "Summary Description and Copyright" segment describes the + document and contains the copyright notice and copying permissions + for the Info file. The segment must be enclosed between `@ifinfo' + and `@end ifinfo' commands so that the formatters place it only in + the Info file. + +3. Title and Copyright + The "Title and Copyright" segment contains the title and copyright + pages and copying permissions for the printed manual. The segment + must be enclosed between `@titlepage' and `@end titlepage' + commands. The title and copyright page appear only in the printed + manual. + +4. `Top' Node and Master Menu + The "Master Menu" contains a complete menu of all the nodes in the + whole Info file. It appears only in the Info file, in the `Top' + node. + +5. Body + The "Body" of the document may be structured like a traditional + book or encyclopedia or it may be free form. + +6. End + The "End" contains commands for printing indices and generating + the table of contents, and the `@bye' command on a line of its own. + diff --git a/info/texinfo.info-2 b/info/texinfo.info-2 index b309e1a..fc54512 100644 --- a/info/texinfo.info-2 +++ b/info/texinfo.info-2 @@ -4,19 +4,19 @@ texinfo.texi. INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Update info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. +* install-info: (texinfo)Invoking install-info. Updating info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. +* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. END-INFO-DIR-ENTRY This file documents Texinfo, a documentation system that can produce -both online information and a printed manual from a single source file. +both on-line information and a printed manual from a single source file. - Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software + Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software Foundation, Inc. - This edition is for Texinfo version 4.0, 28 September 1999. + This edition is for Texinfo version 3.12. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -33,104 +33,7 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -File: texinfo.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview - -What a Texinfo File Must Have -============================= - - By convention, the names of Texinfo files end with one of the -extensions `.texinfo', `.texi', `.txi', or `.tex'. The longer -extension is preferred since it describes more clearly to a human -reader the nature of the file. The shorter extensions are for -operating systems that cannot handle long file names. - - In order to be made into a printed manual and an Info file, a Texinfo -file *must* begin with lines like this: - - \input texinfo - @setfilename INFO-FILE-NAME - @settitle NAME-OF-MANUAL - -The contents of the file follow this beginning, and then you *must* end -a Texinfo file with a line like this: - - @bye - -The `\input texinfo' line tells TeX to use the `texinfo.tex' file, -which tells TeX how to translate the Texinfo @-commands into TeX -typesetting commands. (Note the use of the backslash, `\'; this is -correct for TeX.) The `@setfilename' line provides a name for the Info -file and tells TeX to open auxiliary files. The `@settitle' line -specifies a title for the page headers (or footers) of the printed -manual. - - The `@bye' line at the end of the file on a line of its own tells the -formatters that the file is ended and to stop formatting. - - Usually, you will not use quite such a spare format, but will include -mode setting and start-of-header and end-of-header lines at the -beginning of a Texinfo file, like this: - - \input texinfo @c -*-texinfo-*- - @c %**start of header - @setfilename INFO-FILE-NAME - @settitle NAME-OF-MANUAL - @c %**end of header - -In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo -mode when you edit the file. - - The `@c' lines which surround the `@setfilename' and `@settitle' -lines are optional, but you need them in order to run TeX or Info on -just part of the file. (*Note Start of Header::, for more information.) - - Furthermore, you will usually provide a Texinfo file with a title -page, indices, and the like. But the minimum, which can be useful for -short documents, is just the three lines at the beginning and the one -line at the end. - - -File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview - -Six Parts of a Texinfo File -=========================== - - Generally, a Texinfo file contains more than the minimal beginning -and end--it usually contains six parts: - -1. Header - The "Header" names the file, tells TeX which definitions' file to - use, and performs other "housekeeping" tasks. - -2. Summary Description and Copyright - The "Summary Description and Copyright" segment describes the - document and contains the copyright notice and copying permissions - for the Info file. The segment must be enclosed between `@ifinfo' - and `@end ifinfo' commands so that the formatters place it only in - the Info file. - -3. Title and Copyright - The "Title and Copyright" segment contains the title and copyright - pages and copying permissions for the printed manual. The segment - must be enclosed between `@titlepage' and `@end titlepage' - commands. The title and copyright page appear only in the printed - manual. - -4. `Top' Node and Master Menu - The "Master Menu" contains a complete menu of all the nodes in the - whole Info file. It appears only in the Info file, in the `Top' - node. - -5. Body - The "Body" of the document may be structured like a traditional - book or encyclopedia or it may be free form. - -6. End - The "End" contains commands for printing indices and generating - the table of contents, and the `@bye' command on a line of its own. - - -File: texinfo.info, Node: Short Sample, Next: Acknowledgements and History, Prev: Six Parts, Up: Overview +File: texinfo.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview A Short Sample Texinfo File =========================== @@ -141,7 +44,7 @@ titlepage', look more intimidating than they are. Most of the material is standard boilerplate; when you write a manual, simply insert the names for your own manual in this segment. (*Note Beginning a File::.) - In the following, the sample text is _indented_; comments on it are +In the following, the sample text is _indented_; comments on it are not. The complete file, without any comments, is shown in *Note Sample Texinfo File::. @@ -156,8 +59,9 @@ file and the title used in the header. @c %**start of header @setfilename sample.info @settitle Sample Document - @setchapternewpage odd @c %**end of header + + @setchapternewpage odd Part 2: Summary Description and Copyright ----------------------------------------- @@ -236,11 +140,13 @@ chapter containing an enumerated list. Part 6: The End of the Document ------------------------------- -The end segment contains commands for generating an index in a node and -unnumbered chapter of its own, (usually) for generating the table of -contents, and the `@bye' command that marks the end of the document. +The end segment contains commands both for generating an index in a node +and unnumbered chapter of its own and for generating the table of +contents; and it contains the `@bye' command that marks the end of the +document. @node Concept Index, , First Chapter, Top + @comment node-name, next, previous, up @unnumbered Concept Index @printindex cp @@ -268,44 +174,29 @@ like: for a printed manual.  -File: texinfo.info, Node: Acknowledgements and History, Prev: Short Sample, Up: Overview +File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview -Acknowledgements and History -============================ +Acknowledgements +================ - Richard M. Stallman invented the Texinfo format, wrote the initial -processors, and created Edition 1.0 of this manual. Robert J. Chassell -greatly revised and extended the manual, starting with Edition 1.1. -Brian Fox was responsible for the standalone Texinfo distribution until -version 3.8, and wrote the standalone `makeinfo' and `info'. Karl -Berry has made the updates since Texinfo 3.8 and subsequent releases, -starting with Edition 2.22 of the manual. + Richard M. Stallman wrote Edition 1.0 of this manual. +Robert J. Chassell revised and extended it, starting with Edition 1.1. +Karl Berry made updates for the Texinfo 3.8 and subsequent releases, +starting with Edition 2.22. Our thanks go out to all who helped improve this work, particularly to Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and reported mistakes and obscurities; our special thanks go to Melissa Weisshaus for her frequent and often tedious reviews of nearly similar -editions. The indefatigable Eli Zaretskii and Andreas Schwab have -provided patches beyond counting. Zack Weinberg did the impossible by -implementing the macro syntax in `texinfo.tex'. Dozens of others have -contributed patches and suggestions, they are gratefully acknowledged -in the `ChangeLog' file. Our mistakes are our own. - - A bit of history: in the 1970's at CMU, Brian Reid developed a program -and format named Scribe to mark up documents for printing. It used the -`@' character to introduce commands as Texinfo does and strived to -describe document contents rather than formatting. - - Meanwhile, people at MIT developed another, not too dissimilar format -called Bolio. This then was converted to using TeX as its typesetting -language: BoTeX. - - BoTeX could only be used as a markup language for documents to be -printed, not for online documents. Richard Stallman (RMS) worked on -both Bolio and BoTeX. He also developed a nifty on-line help format -called Info, and then combined BoTeX and Info to create Texinfo, a mark -up language for text that is intended to be read both on line and as -printed hard copy. +editions. Our mistakes are our own. + + Please send suggestions and corrections to: + + Internet address: + bug-texinfo@gnu.org + +Please include the manual's edition number and update date in your +messages.  File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top @@ -342,8 +233,7 @@ File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: T Texinfo Mode Overview ===================== - Texinfo mode provides special features for working with Texinfo files. -You can: + Texinfo mode provides special features for working with Texinfo files: * Insert frequently used @-commands. @@ -388,18 +278,17 @@ such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the `C-x ]' (`forward-page') and `C-x [' (`backward-page') commands and narrow to a chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages: -(emacs)Pages, for details about the page commands.) +(xemacs)Pages, for details about the page commands.) You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the extensions `.texinfo', `.texi', -`.txi', or `.tex'. A longer extension is preferred, since it is +end a Texinfo file name with one of the three extensions `.texinfo', +`.texi', or `.tex'. A longer extension is preferred, since it is explicit, but a shorter extension may be necessary for operating systems that limit the length of file names. GNU Emacs automatically -enters Texinfo mode when you visit a file with a `.texinfo', `.texi' or -`.txi' extension. Also, Emacs switches to Texinfo mode when you visit a -file that has `-*-texinfo-*-' in its first line. If ever you are in -another mode and wish to switch to Texinfo mode, type `M-x -texinfo-mode'. +enters Texinfo mode when you visit a file with a `.texinfo' or `.texi' +extension. Also, Emacs switches to Texinfo mode when you visit a file +that has `-*-texinfo-*-' in its first line. If ever you are in another +mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'. Like all other Emacs features, you can customize or enhance Texinfo mode as you wish. In particular, the keybindings are very easy to @@ -548,16 +437,19 @@ corresponding spot in the Texinfo file. If you call `texinfo-show-structure' with a prefix argument by typing `C-u C-c C-s', it will list not only those lines with the @-commands for `@chapter', `@section', and the like, but also the `@node' lines. -You can use `texinfo-show-structure' with a prefix argument to check -whether the `Next', `Previous', and `Up' pointers of an `@node' line -are correct. +(This is how the `texinfo-show-structure' command worked without an +argument in the first version of Texinfo. It was changed because +`@node' lines clutter up the `*Occur*' buffer and are usually not +needed.) You can use `texinfo-show-structure' with a prefix argument +to check whether the `Next', `Previous', and `Up' pointers of an +`@node' line are correct. Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in by using the `C-x n n' (`narrow-to-region') command and `texinfo-show-structure' will work on only that region. To see the whole buffer again, use -`C-x n w' (`widen'). (*Note Narrowing: (emacs)Narrowing, for more +`C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more information about the narrowing commands.) In addition to providing the `texinfo-show-structure' command, @@ -565,7 +457,7 @@ Texinfo mode sets the value of the page delimiter variable to match the chapter-level @-commands. This enables you to use the `C-x ]' (`forward-page') and `C-x [' (`backward-page') commands to move forward and backward by chapter, and to use the `C-x p' (`narrow-to-page') -command to narrow to a chapter. *Note Pages: (emacs)Pages, for more +command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more information about the page commands.  @@ -599,14 +491,14 @@ File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Pre The Updating Commands --------------------- - You can use the updating commands to: + You can use the updating commands - * insert or update the `Next', `Previous', and `Up' pointers of a + * to insert or update the `Next', `Previous', and `Up' pointers of a node, - * insert or update the menu for a section, and + * to insert or update the menu for a section, and - * create a master menu for a Texinfo source file. + * to create a master menu for a Texinfo source file. You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file. @@ -625,11 +517,11 @@ structuring command line; and you may interpose only an `@comment' line or an `@ifinfo' line. Commands which work on a whole buffer require that the `Top' node be -followed by a node with an `@chapter' or equivalent-level command. The -menu updating commands will not create a main or master menu for a -Texinfo file that has only `@chapter'-level nodes! The menu updating -commands only create menus _within_ nodes for lower level nodes. To -create a menu of chapters, you must provide a `Top' node. +followed by a node with an `@chapter' or equivalent-level command. +Note that the menu updating commands will not create a main or master +menu for a Texinfo file that has only `@chapter'-level nodes! The menu +updating commands only create menus _within_ nodes for lower level +nodes. To create a menu of chapters, you must provide a `Top' node. The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. @@ -669,7 +561,7 @@ menu in the whole Texinfo file. This updates all the nodes and menus completely and all at once. The other major updating commands do smaller jobs and are designed for -the person who updates nodes and menus as he or she writes a Texinfo +the person who updates nodes and menus as he or she writes a Texinfo file. The commands are: @@ -727,8 +619,8 @@ file. which menu descriptions are indented. By default, the value is 32 although it is often useful to reduce it to as low as 24. You can set the variable with the `M-x edit-options' command (*note Editing -Variable Values: (emacs)Edit Options.) or with the `M-x set-variable' -command (*note Examining and Setting Variables: (emacs)Examining.). +Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable' +command (*note Examining and Setting Variables: (xemacs)Examining.). Also, the `texinfo-indent-menu-description' command may be used to indent existing menu descriptions to a specified column. Finally, if @@ -770,7 +662,7 @@ In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an -`@comment' line, you may also write an `@ifinfo' line.) +`@comment' line, you can write an `@ifinfo' line.) If a file has a `Top' node, it must be called `top' or `Top' and be the first node in the file. @@ -782,10 +674,10 @@ must have a `Top' node if you want a menu of chapters. Incidentally, the `makeinfo' command will create an Info file for a hierarchically organized Texinfo file that lacks `Next', `Previous' and `Up' pointers. Thus, if you can be sure that your Texinfo file will be -formatted with `makeinfo', you have no need for the update node -commands. (*Note Creating an Info File::, for more information about -`makeinfo'.) However, both `makeinfo' and the `texinfo-format-...' -commands require that you insert menus in the file. +formatted with `makeinfo', you have no need for the `update node' +commands. (*Note Creating an Info File: Create an Info File, for more +information about `makeinfo'.) However, both `makeinfo' and the +`texinfo-format-...' commands require that you insert menus in the file.  File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus @@ -814,11 +706,11 @@ possesses several less frequently used updating commands: C-x h C-u M-x texinfo-insert-node-lines - This command inserts titles as node names in `@node' lines; the - `texinfo-start-menu-description' command (*note Inserting - Frequently Used Commands: Inserting.) inserts titles as - descriptions in menu entries, a different action. However, in - both cases, you need to edit the inserted text. + (Note that this command inserts titles as node names in `@node' + lines; the `texinfo-start-menu-description' command (*note + Inserting Frequently Used Commands: Inserting.) inserts titles as + descriptions in menu entries, a different action. However, in both + cases, you need to edit the inserted text.) `M-x texinfo-multiple-files-update' Update nodes and menus in a document built from several separate @@ -897,7 +789,7 @@ or For TeX or the Info formatting commands to work, the file _must_ include a line that has `@setfilename' in its header. - *Note Creating an Info File::, for details about Info formatting. + *Note Create an Info File::, for details about Info formatting.  File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode @@ -950,8 +842,8 @@ _must_ start with a `\input texinfo' line and must include an (When you use `texinfo-tex-region', you must surround the `@settitle' line with start-of-header and end-of-header lines.) - *Note Hardcopy::, for a description of the other TeX related -commands, such as `tex-show-print-queue'. + *Note Format/Print Hardcopy::, for a description of the other TeX +related commands, such as `tex-show-print-queue'.  File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode @@ -1078,8 +970,8 @@ C-t' and then another control command: `C-r' for `texinfo-tex-region', Other Updating Commands ----------------------- - The remaining updating commands do not have standard keybindings -because they are rarely used. + The `other updating commands' do not have standard keybindings because +they are rarely used. M-x texinfo-insert-node-lines Insert missing `@node' lines in region. @@ -1252,12 +1144,11 @@ or else like this: * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* exampleindent:: Specify environment indentation. +* paragraphindent:: An option to specify paragraph indentation. * End of Header:: Formatting a region requires this.  -File: texinfo.info, Node: First Line, Next: Start of Header, Up: Header +File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header The First Line of a Texinfo File -------------------------------- @@ -1303,3 +1194,91 @@ typeset part for printing. The odd string of characters, `%**', is to ensure that no other comment is accidentally taken for a start-of-header line. + +File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header + +`@setfilename' +-------------- + + In order to serve as the primary input file for either `makeinfo' or +TeX, a Texinfo file must contain a line that looks like this: + + @setfilename INFO-FILE-NAME + + Write the `@setfilename' command at the beginning of a line and +follow it on the same line by the Info file name. Do not write anything +else on the line; anything on the line after the command is considered +part of the file name, including what would otherwise be a comment. + + The `@setfilename' line specifies the name of the Info file to be +generated. This name should be different from the name of the Texinfo +file. There are two conventions for choosing the name: you can either +remove the `.texi' extension from the input file name, or replace it +with the `.info' extension. + + Some operating systems cannot handle long file names. You can run +into a problem even when the file name you specify is itself short +enough. This occurs because the Info formatters split a long Info file +into short indirect subfiles, and name them by appending `-1', `-2', +..., `-10', `-11', and so on, to the original file name. (*Note Tag +Files and Split Files: Tag and Split Files.) The subfile name +`texinfo.info-10', for example, is too long for some systems; so the +Info file name for this document is `texinfo' rather than +`texinfo.info'. + + The Info formatting commands ignore everything written before the +`@setfilename' line, which is why the very first line of the file (the +`\input' line) does not show up in the output. + + The `@setfilename' line produces no output when you typeset a manual +with TeX, but it nevertheless is essential: it opens the index, +cross-reference, and other auxiliary files used by Texinfo, and also +reads `texinfo.cnf' if that file is present on your system (*note +Preparing to Use TeX: Preparing for TeX.). + + +File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header + +`@settitle' +----------- + + In order to be made into a printed manual, a Texinfo file must contain +a line that looks like this: + + @settitle TITLE + + Write the `@settitle' command at the beginning of a line and follow +it on the same line by the title. This tells TeX the title to use in a +header or footer. Do not write anything else on the line; anything on +the line after the command is considered part of the title, including a +comment. + + Conventionally, when TeX formats a Texinfo file for double-sided +output, the title is printed in the left-hand (even-numbered) page +headings and the current chapter title is printed in the right-hand +(odd-numbered) page headings. (TeX learns the title of each chapter +from each `@chapter' command.) Page footers are not printed. + + Even if you are printing in a single-sided style, TeX looks for an +`@settitle' command line, in case you include the manual title in the +heading. + + The `@settitle' command should precede everything that generates +actual output in TeX. + + Although the title in the `@settitle' command is usually the same as +the title on the title page, it does not affect the title as it appears +on the title page. Thus, the two do not need not match exactly; and +the title in the `@settitle' command can be a shortened or expanded +version of the title as it appears on the title page. (*Note +`@titlepage': titlepage.) + + TeX prints page headings only for that text that comes after the +`@end titlepage' command in the Texinfo file, or that comes after an +`@headings' command that turns on headings. (*Note The `@headings' +Command: headings on off, for more information.) + + You may, if you wish, create your own, customized headings and +footings. *Note Page Headings: Headings, for a detailed discussion of +this process. + diff --git a/info/xemacs-faq.info b/info/xemacs-faq.info index 981e994..cd678b0 100644 --- a/info/xemacs-faq.info +++ b/info/xemacs-faq.info @@ -9,241 +9,258 @@ END-INFO-DIR-ENTRY  Indirect: xemacs-faq.info-1: 195 -xemacs-faq.info-2: 48836 -xemacs-faq.info-3: 95929 -xemacs-faq.info-4: 145764 -xemacs-faq.info-5: 195594 +xemacs-faq.info-2: 47856 +xemacs-faq.info-3: 94965 +xemacs-faq.info-4: 144800 +xemacs-faq.info-5: 194688  Tag Table: (Indirect) Node: Top195 -Node: Introduction15648 -Node: Q1.0.119167 -Node: Q1.0.219703 -Node: Q1.0.320139 -Node: Q1.0.420397 -Node: Q1.0.521829 -Node: Q1.0.622518 -Node: Q1.0.723649 -Node: Q1.0.824048 -Node: Q1.0.924244 -Node: Q1.0.1024522 -Node: Q1.0.1125971 -Node: Q1.0.1226428 -Node: Q1.0.1326796 -Node: Q1.0.1427031 -Node: Q1.1.127575 -Node: Q1.1.228770 -Node: Q1.1.329145 -Node: Q1.2.130096 -Node: Q1.2.231152 -Node: Q1.2.331586 -Node: Q1.3.132537 -Node: Q1.3.236455 -Node: Q1.3.337164 -Node: Q1.3.437405 -Node: Q1.3.538169 -Node: Q1.3.640584 -Node: Q1.3.742079 -Node: Q1.4.143014 -Node: Q1.4.243876 -Node: Q1.4.344217 -Node: Q1.4.444859 -Node: Q1.4.546399 -Node: Q1.4.646703 -Node: Q1.4.747711 -Node: Installation48836 -Node: Q2.0.151242 -Node: Q2.0.252115 -Node: Q2.0.359318 -Node: Q2.0.460616 -Node: Q2.0.561208 -Node: Q2.0.661576 -Node: Q2.0.761957 -Node: Q2.0.862338 -Node: Q2.0.963916 -Node: Q2.0.1065354 -Node: Q2.0.1166198 -Node: Q2.0.1267139 -Node: Q2.0.1368662 -Node: Q2.0.1469320 -Node: Q2.1.169888 -Node: Q2.1.272630 -Node: Q2.1.373807 -Node: Q2.1.475100 -Node: Q2.1.575899 -Node: Q2.1.676261 -Node: Q2.1.776738 -Node: Q2.1.877091 -Node: Q2.1.978607 -Node: Q2.1.1079029 -Node: Q2.1.1179786 -Node: Q2.1.1280651 -Node: Q2.1.1381606 -Node: Q2.1.1482637 -Node: Q2.1.1583748 -Node: Q2.1.1689706 -Node: Q2.1.1790384 -Node: Q2.1.1890981 -Node: Q2.1.1992778 -Node: Q2.1.2093308 -Node: Q2.1.2193690 -Node: Q2.1.2293980 -Node: Q2.1.2395277 -Node: Customization95929 -Node: Q3.0.1100816 -Node: Q3.0.2101522 -Node: Q3.0.3102086 -Node: Q3.0.4102503 -Node: Q3.0.5103336 -Node: Q3.0.6104117 -Node: Q3.0.7104697 -Node: Q3.0.8105361 -Node: Q3.0.9106207 -Node: Q3.1.1106768 -Node: Q3.1.2107505 -Node: Q3.1.3107936 -Node: Q3.1.4108521 -Node: Q3.1.5109057 -Node: Q3.1.6109441 -Node: Q3.1.7110122 -Node: Q3.1.8112346 -Node: Q3.2.1112888 -Node: Q3.2.2114296 -Node: Q3.2.3115095 -Node: Q3.2.4115697 -Node: Q3.2.5116731 -Node: Q3.2.6117198 -Node: Q3.3.1118160 -Node: Q3.3.2118553 -Node: Q3.3.3119184 -Node: Q3.3.4119565 -Node: Q3.3.5120659 -Node: Q3.4.1122153 -Node: Q3.4.2122796 -Node: Q3.5.1123308 -Node: Q3.5.2124762 -Node: Q3.5.3125180 -Node: Q3.5.4126020 -Node: Q3.5.5126852 -Node: Q3.5.6127992 -Node: Q3.5.7128982 -Node: Q3.5.8130334 -Node: Q3.5.9131081 -Node: Q3.5.10131861 -Node: Q3.5.11132497 -Node: Q3.6.1133050 -Node: Q3.6.2133790 -Node: Q3.6.3134218 -Node: Q3.7.1134718 -Node: Q3.7.2135606 -Node: Q3.7.3136265 -Node: Q3.7.4136687 -Node: Q3.7.5137030 -Node: Q3.7.6137498 -Node: Q3.7.7138213 -Node: Q3.7.8139233 -Node: Q3.8.1139652 -Node: Q3.8.2140112 -Node: Q3.8.3140575 -Node: Q3.8.4141181 -Node: Q3.8.5141900 -Node: Q3.9.1142685 -Node: Q3.9.2143625 -Node: Q3.9.3144223 -Node: Q3.9.4144885 -Node: Q3.10.1145764 -Node: Q3.10.2146582 -Node: Q3.10.3147363 -Node: Q3.10.4148091 -Node: Q3.10.5148474 -Node: Subsystems149484 -Node: Q4.0.1151969 -Node: Q4.0.2152494 -Node: Q4.0.3153052 -Node: Q4.0.4153373 -Node: Q4.0.5153615 -Node: Q4.0.6153846 -Node: Q4.0.7154427 -Node: Q4.0.8154752 -Node: Q4.0.9155979 -Node: Q4.0.10158017 -Node: Q4.0.11158471 -Node: Q4.0.12159321 -Node: Q4.1.1160294 -Node: Q4.1.2160697 -Node: Q4.1.3161024 -Node: Q4.2.1161333 -Node: Q4.2.2161963 -Node: Q4.2.3162203 -Node: Q4.2.4162747 -Node: Q4.3.1163400 -Node: Q4.3.2163984 -Node: Q4.3.3165700 -Node: Q4.3.4165972 -Node: Q4.3.5166649 -Node: Q4.4.1167277 -Node: Q4.4.2168777 -Node: Q4.5.1169981 -Node: Q4.6.1170750 -Node: Q4.7.1176010 -Node: Q4.7.2176965 -Node: Q4.7.3177262 -Node: Q4.7.4177608 -Node: Q4.7.5178492 -Node: Q4.7.6180134 -Node: Miscellaneous180678 -Node: Q5.0.1184102 -Node: Q5.0.2184836 -Node: Q5.0.3185690 -Node: Q5.0.4186392 -Node: Q5.0.5187331 -Node: Q5.0.6189311 -Node: Q5.0.7189968 -Node: Q5.0.8190573 -Node: Q5.0.9191092 -Node: Q5.0.10191606 -Node: Q5.0.11191854 -Node: Q5.0.12192415 -Node: Q5.0.13193332 -Node: Q5.0.14194016 -Node: Q5.0.15194781 -Node: Q5.0.16195082 -Node: Q5.0.17195594 -Node: Q5.0.18195859 -Node: Q5.0.19196385 -Node: Q5.0.20196809 -Node: Q5.1.1197724 -Node: Q5.1.2199793 -Node: Q5.1.3200529 -Node: Q5.1.4203923 -Node: Q5.1.5204458 -Node: Q5.1.6206552 -Node: Q5.1.7207941 -Node: Q5.1.8209542 -Node: Q5.1.9210094 -Node: Q5.1.10210979 -Node: Q5.1.11212110 -Node: Q5.2.1212659 -Node: Q5.2.2213230 -Node: Q5.2.3213647 -Node: Q5.2.4213882 -Node: Q5.3.1214792 -Node: Q5.3.2216013 -Node: Q5.3.3216789 -Node: Q5.3.4217273 -Node: Q5.3.5217940 -Node: Q5.3.6218809 -Node: Q5.3.7219054 -Node: Q5.3.8221244 -Node: Q5.3.9221491 -Node: Q5.3.10222444 -Node: Q5.3.11224639 -Node: Q5.3.12226188 -Node: Current Events227462 -Node: Q6.0.1228119 -Node: Q6.0.2228758 -Node: Q6.0.3229832 -Node: Q6.0.4230060 +Node: Introduction16711 +Node: Q1.0.120230 +Node: Q1.0.220766 +Node: Q1.0.321261 +Node: Q1.0.421523 +Node: Q1.0.522973 +Node: Q1.0.623662 +Node: Q1.0.724668 +Node: Q1.0.824917 +Node: Q1.0.925132 +Node: Q1.0.1025410 +Node: Q1.0.1125653 +Node: Q1.0.1226110 +Node: Q1.0.1326478 +Node: Q1.0.1426713 +Node: Q1.1.127187 +Node: Q1.1.228149 +Node: Q1.1.328542 +Node: Q1.2.129493 +Node: Q1.2.230549 +Node: Q1.2.330983 +Node: Q1.3.131934 +Node: Q1.3.235852 +Node: Q1.3.336407 +Node: Q1.3.436648 +Node: Q1.3.537412 +Node: Q1.3.639827 +Node: Q1.3.741322 +Node: Q1.4.142257 +Node: Q1.4.243119 +Node: Q1.4.343460 +Node: Q1.4.443879 +Node: Q1.4.545419 +Node: Q1.4.645723 +Node: Q1.4.746731 +Node: Installation47856 +Node: Q2.0.150262 +Node: Q2.0.251135 +Node: Q2.0.358338 +Node: Q2.0.459636 +Node: Q2.0.560228 +Node: Q2.0.660596 +Node: Q2.0.760977 +Node: Q2.0.861358 +Node: Q2.0.962936 +Node: Q2.0.1064374 +Node: Q2.0.1165218 +Node: Q2.0.1266159 +Node: Q2.0.1367682 +Node: Q2.0.1468340 +Node: Q2.1.168908 +Node: Q2.1.271650 +Node: Q2.1.372827 +Node: Q2.1.474120 +Node: Q2.1.574919 +Node: Q2.1.675281 +Node: Q2.1.775758 +Node: Q2.1.876111 +Node: Q2.1.977627 +Node: Q2.1.1078049 +Node: Q2.1.1178806 +Node: Q2.1.1279671 +Node: Q2.1.1380626 +Node: Q2.1.1481657 +Node: Q2.1.1582768 +Node: Q2.1.1688726 +Node: Q2.1.1789420 +Node: Q2.1.1890017 +Node: Q2.1.1991814 +Node: Q2.1.2092344 +Node: Q2.1.2192726 +Node: Q2.1.2293016 +Node: Q2.1.2394313 +Node: Customization94965 +Node: Q3.0.199852 +Node: Q3.0.2100558 +Node: Q3.0.3101122 +Node: Q3.0.4101539 +Node: Q3.0.5102372 +Node: Q3.0.6103153 +Node: Q3.0.7103733 +Node: Q3.0.8104397 +Node: Q3.0.9105243 +Node: Q3.1.1105804 +Node: Q3.1.2106541 +Node: Q3.1.3106972 +Node: Q3.1.4107557 +Node: Q3.1.5108093 +Node: Q3.1.6108477 +Node: Q3.1.7109158 +Node: Q3.1.8111382 +Node: Q3.2.1111924 +Node: Q3.2.2113332 +Node: Q3.2.3114131 +Node: Q3.2.4114733 +Node: Q3.2.5115767 +Node: Q3.2.6116234 +Node: Q3.3.1117196 +Node: Q3.3.2117589 +Node: Q3.3.3118220 +Node: Q3.3.4118601 +Node: Q3.3.5119695 +Node: Q3.4.1121189 +Node: Q3.4.2121832 +Node: Q3.5.1122344 +Node: Q3.5.2123798 +Node: Q3.5.3124216 +Node: Q3.5.4125056 +Node: Q3.5.5125888 +Node: Q3.5.6127028 +Node: Q3.5.7128018 +Node: Q3.5.8129370 +Node: Q3.5.9130117 +Node: Q3.5.10130897 +Node: Q3.5.11131533 +Node: Q3.6.1132086 +Node: Q3.6.2132826 +Node: Q3.6.3133254 +Node: Q3.7.1133754 +Node: Q3.7.2134642 +Node: Q3.7.3135301 +Node: Q3.7.4135723 +Node: Q3.7.5136066 +Node: Q3.7.6136534 +Node: Q3.7.7137249 +Node: Q3.7.8138269 +Node: Q3.8.1138688 +Node: Q3.8.2139148 +Node: Q3.8.3139611 +Node: Q3.8.4140217 +Node: Q3.8.5140936 +Node: Q3.9.1141721 +Node: Q3.9.2142661 +Node: Q3.9.3143259 +Node: Q3.9.4143921 +Node: Q3.10.1144800 +Node: Q3.10.2145618 +Node: Q3.10.3146399 +Node: Q3.10.4147127 +Node: Q3.10.5147510 +Node: Subsystems148520 +Node: Q4.0.1151005 +Node: Q4.0.2151530 +Node: Q4.0.3152088 +Node: Q4.0.4152409 +Node: Q4.0.5152651 +Node: Q4.0.6152882 +Node: Q4.0.7153463 +Node: Q4.0.8153788 +Node: Q4.0.9155015 +Node: Q4.0.10157053 +Node: Q4.0.11157507 +Node: Q4.0.12158357 +Node: Q4.1.1159330 +Node: Q4.1.2159733 +Node: Q4.1.3160060 +Node: Q4.2.1160369 +Node: Q4.2.2160999 +Node: Q4.2.3161239 +Node: Q4.2.4161783 +Node: Q4.3.1162436 +Node: Q4.3.2163020 +Node: Q4.3.3164501 +Node: Q4.3.4164773 +Node: Q4.3.5165450 +Node: Q4.4.1166078 +Node: Q4.4.2167564 +Node: Q4.5.1168768 +Node: Q4.6.1169537 +Node: Q4.7.1174797 +Node: Q4.7.2175752 +Node: Q4.7.3176049 +Node: Q4.7.4176395 +Node: Q4.7.5177279 +Node: Q4.7.6178921 +Node: Miscellaneous179515 +Node: Q5.0.1182935 +Node: Q5.0.2183669 +Node: Q5.0.3184523 +Node: Q5.0.4185225 +Node: Q5.0.5186164 +Node: Q5.0.6188144 +Node: Q5.0.7188801 +Node: Q5.0.8189406 +Node: Q5.0.9189925 +Node: Q5.0.10190439 +Node: Q5.0.11190687 +Node: Q5.0.12191248 +Node: Q5.0.13192165 +Node: Q5.0.14192849 +Node: Q5.0.15193614 +Node: Q5.0.16193911 +Node: Q5.0.17194423 +Node: Q5.0.18194688 +Node: Q5.0.19195214 +Node: Q5.0.20195638 +Node: Q5.1.1196553 +Node: Q5.1.2198622 +Node: Q5.1.3199358 +Node: Q5.1.4202752 +Node: Q5.1.5203287 +Node: Q5.1.6205381 +Node: Q5.1.7206770 +Node: Q5.1.8208371 +Node: Q5.1.9208923 +Node: Q5.1.10209808 +Node: Q5.1.11210939 +Node: Q5.2.1211488 +Node: Q5.2.2212059 +Node: Q5.2.3212476 +Node: Q5.2.4212711 +Node: Q5.3.1213621 +Node: Q5.3.2214842 +Node: Q5.3.3215618 +Node: Q5.3.4216102 +Node: Q5.3.5216769 +Node: Q5.3.6217638 +Node: Q5.3.7217883 +Node: Q5.3.8220073 +Node: Q5.3.9220320 +Node: Q5.3.10221273 +Node: Q5.3.11223357 +Node: Q5.3.12224906 +Node: MS Windows226180 +Node: Q6.0.1227511 +Node: Q6.0.2228258 +Node: Q6.0.3228723 +Node: Q6.0.4229003 +Node: Q6.1.1231284 +Node: Q6.1.2232155 +Node: Q6.1.3232436 +Node: Q6.1.4232718 +Node: Q6.1.5233096 +Node: Q6.1.6233928 +Node: Q6.2.1234512 +Node: Q6.2.2235413 +Node: Q6.2.3235814 +Node: Q6.3.1236103 +Node: Q6.3.2237197 +Node: Q6.3.3240378 +Node: Current Events240632 +Node: Q7.0.1241286 +Node: Q7.0.2241925 +Node: Q7.0.3242999 +Node: Q7.0.4243227  End Tag Table diff --git a/info/xemacs-faq.info-1 b/info/xemacs-faq.info-1 index 4102ba3..6d7aef0 100644 --- a/info/xemacs-faq.info-1 +++ b/info/xemacs-faq.info-1 @@ -39,6 +39,7 @@ archives. * Customization:: Customization and Options. * Subsystems:: Major Subsystems. * Miscellaneous:: The Miscellaneous Stuff. +* MS Windows:: XEmacs on Microsoft Windows. * Current Events:: What the Future Holds. @@ -327,12 +328,38 @@ Miscellaneous: * Q5.3.11:: How do I add new Info directories? * Q5.3.12:: What do I need to change to make printing work? -What the Future Holds +XEmacs on MS Windows -* Q6.0.1:: What is new in 20.2? -* Q6.0.2:: What is new in 20.3? -* Q6.0.3:: What is new in 20.4? -* Q6.0.4:: Procedural changes in XEmacs development. +General Info: +* Q6.0.1:: What is the status of the XEmacs port to Windows? +* Q6.0.2:: What flavors of MS Windows are supported? +* Q6.0.3:: Are binary kits available? +* Q6.0.4:: Does XEmacs on MS Windows require an X server to run? + +Building XEmacs on MS Windows: +* Q6.1.1:: I decided to run with X. Where do I get an X server? +* Q6.1.2:: What compiler do I need to compile XEmacs? +* Q6.1.3:: How do I compile for the native port? +* Q6.1.4:: How do I compile for the X port? +* Q6.1.5:: How do I compile for Cygnus' Cygwin? +* Q6.1.6:: What do I need for Cygwin? + +Customization and User Interface: +* Q6.2.1:: How will the port cope with differences in the Windows user interface? +* Q6.2.2:: How do I change fonts in XEmacs on MS Windows? +* Q6.2.3:: Where do I put my `.emacs' file? + +Miscellaneous: +* Q6.3.1:: Will XEmacs rename all the win32-* symbols to w32-*? +* Q6.3.2:: What are the differences between the various MS Windows emacsen? +* Q6.3.3:: What is the porting team doing at the moment? + +Current Events: + +* Q7.0.1:: What is new in 20.2? +* Q7.0.2:: What is new in 20.3? +* Q7.0.3:: What is new in 20.4? +* Q7.0.4:: Procedural changes in XEmacs development.  File: xemacs-faq.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top @@ -436,6 +463,8 @@ File: xemacs-faq.info, Node: Q1.0.2, Next: Q1.0.3, Prev: Q1.0.1, Up: Introdu Q1.0.2: What is the current version of XEmacs? ---------------------------------------------- + XEmacs 21.1.8 is the current stable version of XEmacs. + XEmacs 20.4 is a minor upgrade from 20.3, containing many bugfixes. It was released in February 1998. @@ -448,7 +477,7 @@ File: xemacs-faq.info, Node: Q1.0.3, Next: Q1.0.4, Prev: Q1.0.2, Up: Introdu Q1.0.3: Where can I find it? ---------------------------- - The canonical source and binaries is found via anonymous FTP at: + The canonical source and binaries can be found via anonymous FTP at: `ftp://ftp.xemacs.org/pub/xemacs/' @@ -460,7 +489,7 @@ Q1.0.4: Why Another Version of Emacs? For a detailed description of the differences between GNU Emacs and XEmacs and a detailed history of XEmacs, check out the - NEWS file (http://www.xemacs.org/NEWS.html) + NEWS file (http://www.xemacs.org/About/XEmacsVsGNUemacs.html) However, here is a list of some of the reasons why we think you might consider using it: @@ -528,28 +557,22 @@ Q1.0.6: Where can I get help? ----------------------------- Probably the easiest way, if everything is installed, is to use -info, by pressing `C-h i', or selecting `Manuals->Info' from the Help -Menu. - - Also, `M-x apropos' will look for commands for you. +Info, by pressing `C-h i', or selecting `Manuals->Info' from the Help +Menu. `M-x apropos' can be used to look for particular commands. - Try reading this FAQ, examining the regular GNU Emacs FAQ (which can -be found with the Emacs 19 distribution) as well as at -`http://www.eecs.nwu.edu/emacs/faq/' and reading the Usenet group -comp.emacs.xemacs. + For items not found in the manual, try reading this FAQ and reading +the Usenet group comp.emacs.xemacs. - If that does not help, try posting your question to -comp.emacs.xemacs. Please *do not* post XEmacs related questions to + If you choose to post to a newsgroup, *please use +comp.emacs.xemacs*. Please do not post XEmacs related questions to gnu.emacs.help. If you cannot post or read Usenet news, there is a corresponding mailing list which is available. It can be subscribed to by sending a -message with a subject of `subscribe' to -for subscription information and to send messages -to the list. - - To cancel a subscription, you *must* use the xemacs-request address. -Send a message with a subject of `unsubscribe' to be removed. +message to with `subscribe' in the body of +the message. Send to the list at . list. To +cancel a subscription, you *must* use the xemacs-request address. Send +a message with a subject of `unsubscribe' to be removed.  File: xemacs-faq.info, Node: Q1.0.7, Next: Q1.0.8, Prev: Q1.0.6, Up: Introduction @@ -557,11 +580,7 @@ File: xemacs-faq.info, Node: Q1.0.7, Next: Q1.0.8, Prev: Q1.0.6, Up: Introdu Q1.0.7: Where is the mailing list archived? ------------------------------------------- - The mailing list was archived in the directory - `ftp://ftp.xemacs.org/pub/mlists/'. - - However, this archive is out of date. The current mailing list -server supports an `archive' feature, which may be utilized. + The archives can be found at `http://www.xemacs.org/Lists/Archive'  File: xemacs-faq.info, Node: Q1.0.8, Next: Q1.0.9, Prev: Q1.0.7, Up: Introduction @@ -569,7 +588,7 @@ File: xemacs-faq.info, Node: Q1.0.8, Next: Q1.0.9, Prev: Q1.0.7, Up: Introdu Q1.0.8: How do you pronounce XEmacs? ------------------------------------ - I pronounce it `Eks eemax'. + The most common pronounciation is `Eks eemax'.  File: xemacs-faq.info, Node: Q1.0.9, Next: Q1.0.10, Prev: Q1.0.8, Up: Introduction @@ -586,33 +605,7 @@ File: xemacs-faq.info, Node: Q1.0.10, Next: Q1.0.11, Prev: Q1.0.9, Up: Intro Q1.0.10: Is there a port of XEmacs to Microsoft ('95 or NT)? ------------------------------------------------------------ - Thanks to efforts of many people, coordinated by David Hobley - and Marc Paquette , beta versions of -XEmacs now run on 32-bit Windows platforms (NT and 95). The current -betas require having an X server to run XEmacs; however, a native NT/95 -port is in alpha, thanks to Jonathan Harris . - - Although some features are still unimplemented, XEmacs 21.0 will -support MS-Windows. - - The NT development is now coordinated by a mailing list at -. - - If you are willing to contribute or want to follow the progress, -mail to to subscribe. - - Furthermore, Altrasoft is seeking corporate and government sponsors -to help fund a fully native port of XEmacs to Windows 95 and NT using -full-time, senior-level staff working under a professionally managed -project structure. See the Altrasoft web site -(http://www.altrasoft.com/) for more details or contact Altrasoft -directly at 1-888-ALTSOFT. - - The closest existing port is "Win-Emacs", which is based on Lucid -Emacs 19.6. Available from `http://www.pearlsoft.com/'. - - There's a port of GNU Emacs (not XEmacs) at - `http://www.cs.washington.edu/homes/voelker/ntemacs.html'. + Yes, *Note MS Windows::.  File: xemacs-faq.info, Node: Q1.0.11, Next: Q1.0.12, Prev: Q1.0.10, Up: Introduction @@ -651,13 +644,11 @@ File: xemacs-faq.info, Node: Q1.0.14, Next: Q1.1.1, Prev: Q1.0.13, Up: Intro Q1.0.14: Where can I obtain a printed copy of the XEmacs users manual? ---------------------------------------------------------------------- - Altrasoft Associates, a firm specializing in Emacs-related support -and development, will be maintaining the XEmacs user manual. The firm -plans to begin publishing printed copies of the manual soon. + Pre-printed manuals are not available. If you are familiar with +TeX, you can generate your own manual from the XEmacs sources. - Web: `http://www.xemacs.com' - E-mail: - Tel: +1 408 243 3300 + HTML and Postscript versions of XEmacs manuals may be available from +the XEmacs web site in the future.  File: xemacs-faq.info, Node: Q1.1.1, Next: Q1.1.2, Prev: Q1.0.14, Up: Introduction @@ -669,19 +660,12 @@ Q1.1.1: What is the FAQ editorial policy? ----------------------------------------- The FAQ is actively maintained and modified regularly. All links -should be up to date. - - Changes are displayed on a monthly basis. "Months", for this -purpose are defined as the 5th of the month through the 5th of the -month. Preexisting questions that have been changed are marked as such. -Brand new questions are tagged. - - All submissions are welcome. E-mail submissions to Christian Nyb/o -. +should be up to date. All submissions are welcome. E-mail submissions +to XEmacs FAQ maintainers . Please make sure that `XEmacs FAQ' appears on the Subject: line. If you think you have a better way of answering a question, or think a -question should be included, I'd like to hear about it. Questions and +question should be included, we'd like to hear about it. Questions and answers included into the FAQ will be edited for spelling and grammar, and will be attributed. Answers appearing without attribution are either from versions of the FAQ dated before May 1996, or are from one @@ -695,8 +679,8 @@ File: xemacs-faq.info, Node: Q1.1.2, Next: Q1.1.3, Prev: Q1.1.1, Up: Introdu Q1.1.2: How do I become a Beta Tester? -------------------------------------- - Send an email message to with a -subject line of `subscribe'. + Send an email message to with the +line `subscribe' in the body of the message. Be prepared to get your hands dirty, as beta testers are expected to identify problems as best they can. @@ -910,15 +894,12 @@ File: xemacs-faq.info, Node: Q1.3.2, Next: Q1.3.3, Prev: Q1.3.1, Up: Introdu Q1.3.2: What is the status of Asian-language support, aka MULE? --------------------------------------------------------------- - The MULE support works OK but still needs a fair amount of work -before it's really solid. We could definitely use some help here, esp. -people who speak Japanese and will use XEmacs/MULE to work with -Japanese and have some experience with E-Lisp. + MULE support is now available for UNIX versions of XEmacs. - As the fundings on Mule have stopped, the Mule part of XEmacs is -currently looking for a full-time maintainer. If you can provide help -here, or are willing to fund the work, please mail to -. + If you would like to help, you may want to join the + mailing list. Especially needed are people +who speak/write languages other than English, who are willing to use +XEmacs/MULE regularly, and have some experience with Elisp. *Note Q1.1.2::. @@ -1108,13 +1089,6 @@ Q1.4.3: Any good tutorials around? available in a non-english language, type `C-u C-h t TAB', type the first letters of your preferred language, then type . - There's an Emacs Lisp tutorial at - - `ftp://prep.ai.mit.edu/pub/gnu/emacs-lisp-intro-1.04.tar.gz'. - - Erik Sundermann has made a tutorial web page -at `http://petaxp.rug.ac.be/~erik/xemacs/'. -  File: xemacs-faq.info, Node: Q1.4.4, Next: Q1.4.5, Prev: Q1.4.3, Up: Introduction diff --git a/info/xemacs-faq.info-2 b/info/xemacs-faq.info-2 index 08629dc..2ea10ef 100644 --- a/info/xemacs-faq.info-2 +++ b/info/xemacs-faq.info-2 @@ -1040,8 +1040,8 @@ File: xemacs-faq.info, Node: Q2.1.16, Next: Q2.1.17, Prev: Q2.1.15, Up: Inst Q2.1.16: XEmacs crashes in `strcat' on HP/UX 10 ----------------------------------------------- - >From the problems database (through -`http://support.mayfield.hp.com/'): + From the problems database (through the former address +http://support.mayfield.hp.com/): Problem Report: 5003302299 Status: Open diff --git a/lib-src/ChangeLog b/lib-src/ChangeLog index 83ebc43..9ddbcbc 100644 --- a/lib-src/ChangeLog +++ b/lib-src/ChangeLog @@ -1,3 +1,12 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-11-29 Andreas Jaeger + + * Makefile.in.in (INSTALLABLE_SCRIPTS): Removed pstogif. + pstogif: Moved to package tm. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/lib-src/Makefile.in.in b/lib-src/Makefile.in.in index 9c1b864..7730260 100644 --- a/lib-src/Makefile.in.in +++ b/lib-src/Makefile.in.in @@ -80,7 +80,7 @@ INSTALLABLES_BASE = etags ctags b2m ootags #else INSTALLABLES_BASE = etags ctags b2m gnuclient ootags #endif -INSTALLABLE_SCRIPTS = rcs-checkin pstogif gnudoit gnuattach +INSTALLABLE_SCRIPTS = rcs-checkin gnudoit gnuattach #ifdef HAVE_SHLIB #ifdef HAVE_MS_WINDOWS INSTALLABLES = $(INSTALLABLES_BASE) runxemacs rungnuclient ellcc diff --git a/lib-src/mmencode.c b/lib-src/mmencode.c index 3609a5e..6287ca2 100644 --- a/lib-src/mmencode.c +++ b/lib-src/mmencode.c @@ -18,6 +18,7 @@ WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. #include #include #include +#include static void output64chunk(int c1, int c2, int c3, int pads, FILE *outfile); diff --git a/lib-src/rcs2log b/lib-src/rcs2log index 2a9e7d1..8fa12d9 100755 --- a/lib-src/rcs2log +++ b/lib-src/rcs2log @@ -28,7 +28,7 @@ Options: Report bugs to .' -Id='$Id: rcs2log,v 1.37 1997/03/21 22:19:30 eggert Exp $' +Id='$Id: rcs2log,v 1.2 1997/07/09 04:31:03 steve Exp $' # Copyright 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation, Inc. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index d3b49d9..7896576 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,76 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-11-06 Jason R Mastaler + + * package-get.el (package-get-download-sites): Removed several + defunct download sites, added many new ones, and corrected a few + incorrect directory-on-site entries. Added physical locations to + site-description. + +1999-11-30 Gunnar Evermann + + * finder.el (finder-commentary): add DOC string and fix + interactive spec + +1999-12-04 Hrvoje Niksic + + * help.el (describe-function): Don't forget to intern the string + completing-read returns. + (describe-variable): Ditto. + +1999-11-16 Adrian Aichner + + * hyper-apropos.el (hyper-apropos-this-symbol): Handle + `hyper-apropos-help-mode' here to find symbol to customize + irregardless of cursor position and simplify + `hyper-apropos-set-variable', `hyper-apropos-find-function', and + `hyper-apropos-popup-menu'. + +1999-11-21 Yoshiki Hayashi + + * apropos.el (apropos-mode-map): Add return to call + apropos-follow. + (apropos-print): Call apropos-mode to have better + command reference. Put keymap text-poperty to + symbole name. + +1999-11-22 Alastair Burt + + * help.el: (describe-bindings-1): Added handling of keymaps for + the extents at point. + +1999-12-02 Mark Thomas + + * gutter-items.el (buffers-tab-items): Wrap the function in a + save-match-data + +1999-12-04 Hrvoje Niksic + + * help.el (describe-function): Use the DEFAULT argument to + completing-read. + (describe-variable): Ditto. + +1999-11-26 Yoshiki Hayashi + + * minibuf.el (read-from-minibuffer): Add optional argument + DEFAULT to have better mini-buffer history support. + (completing-read): Pass default to read-from-minibuffer. + (read-buffer): Pass default to completing-read. + +1999-12-04 Hrvoje Niksic + + * font-lock.el (font-lock-doc-string-face): Document the + `font-lock-lisp-like' property. + +1999-11-29 Hrvoje Niksic + + * lisp-mode.el: Specify `font-lock-lisp-like'. + + * font-lock.el (font-lock-lisp-like): New function. + (font-lock-fontify-syntactically-region): Use it. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/lisp/about.el b/lisp/about.el index d76b533..0adcec7 100644 --- a/lisp/about.el +++ b/lisp/about.el @@ -89,7 +89,7 @@ (stig "Jonathan Stigelman" "stig@hackvan.com") (stigb "Stig Bjorlykke" "stigb@tihlde.hist.no") (thiessel "Marcus Thiessel" "marcus@xemacs.org") - (vladimir "Vladimir Ivanovic" "vladimir@mri.com") + (vladimir "Vladimir Ivanovic" "vladimir@acm.com") (wing "Ben Wing" "ben@xemacs.org") (wmperry "William Perry" "wmperry@aventail.com")) "Alist of XEmacs hackers.") @@ -659,8 +659,8 @@ Come visit his glorified .plan file at\n\n") (widget-insert "Cars are evil. Ride a bike.\n")) (vladimir (widget-insert "\ -Former technical lead for XEmacs at Sun. He is now with Microtec -Research Inc., working on embedded systems development tools.\n")) +Former technical lead for XEmacs at Sun. He is now with a startup +marketing embedded Java databases.\n")) (stig (widget-insert "\ Stig is sort of a tool fetishist. He has a hate/love relationship @@ -1042,8 +1042,8 @@ Like most free software, XEmacs is a collaborative effort. These are some of the contributors. We have no doubt forgotten someone; we apologize! You can see some of our faces under the links.\n\n") (about-show-linked-info 'vladimir "\ -Former technical lead for XEmacs at Sun Microsystems. He is now with -Microtec Research Inc., working on embedded systems development tools.\n") +Former technical lead for XEmacs at Sun. He is now with a startup +marketing embedded Java databases.\n") (about-show-linked-info 'stig "\ Peripatetic uninominal Emacs hacker. Stig sometimes operates out of a big white van set up for nomadic living and hacking. Implemented the diff --git a/lisp/apropos.el b/lisp/apropos.el index f324ab0..9dee743 100644 --- a/lisp/apropos.el +++ b/lisp/apropos.el @@ -107,6 +107,7 @@ This looks good, but slows down the commands several times.") (defvar apropos-mode-map (let ((map (make-sparse-keymap))) (define-key map [(control m)] 'apropos-follow) + (define-key map [return] 'apropos-follow) (define-key map [(button2up)] 'apropos-mouse-follow) (define-key map [(button2)] 'undefined) map) @@ -508,6 +509,9 @@ found." (let ((p apropos-accumulator) (old-buffer (current-buffer)) symbol item point1 point2) + ;; Mostly useless but to provide better keymap + ;; explanation. help-mode-map will be used instead. + (use-local-map apropos-mode-map) ;; XEmacs change from (if window-system (if (device-on-window-system-p) (progn @@ -575,6 +579,8 @@ found." apropos-item)) (if apropos-symbol-face (put-text-property point1 point2 'face apropos-symbol-face)) + ;; Add text-property on symbol, too. + (put-text-property point1 point2 'keymap apropos-mode-map) (apropos-print-doc 'describe-function 1 (if (commandp symbol) "Command" diff --git a/lisp/finder.el b/lisp/finder.el index 8c9594a..b0fa4de 100644 --- a/lisp/finder.el +++ b/lisp/finder.el @@ -285,8 +285,12 @@ arguments compiles from `load-path'." found))) (defun finder-commentary (file) - (interactive) - (let* ((str (lm-commentary (finder-find-library file)))) + "Display FILE's commentary section. +FILE should be in a form suitable for passing to `locate-library'." + (interactive "sLibrary name: ") + (let* ((str (lm-commentary (or (finder-find-library file) + (finder-find-library (concat file ".el")) + (error "Can't find library %s" file))))) (if (null str) (error "Can't find any Commentary section")) (pop-to-buffer "*Finder*") diff --git a/lisp/font-lock.el b/lisp/font-lock.el index aba0a22..928ab0a 100644 --- a/lisp/font-lock.el +++ b/lisp/font-lock.el @@ -1284,6 +1284,16 @@ This can take a while for large buffers." ; ;; Clean up. ; (and prev (remove-text-properties prev end '(face nil))))) +(defun font-lock-lisp-like (mode) + ;; Note: (or (get mode 'font-lock-lisp-like) (string-match ...)) is + ;; not enough because the property needs to be able to specify a nil + ;; value. + (if (plist-member (symbol-plist mode) 'font-lock-lisp-like) + (get mode 'font-lock-lisp-like) + ;; If the property is not specified, guess. Similar logic exists + ;; in add-log, but I think this encompasses more modes. + (string-match "lisp\\|scheme" (symbol-name mode)))) + (defun font-lock-fontify-syntactically-region (start end &optional loudly) "Put proper face on each string and comment between START and END. START should be at the beginning of a line." @@ -1296,21 +1306,24 @@ START should be at the beginning of a line." (font-lock-unfontify-region start end loudly) (goto-char start) (if (> end (point-max)) (setq end (point-max))) - (syntactically-sectionize - #'(lambda (s e context depth) - (let (face) - (cond ((eq context 'string) - ;;#### Should only do this is Lisp-like modes! - (setq face - (if (= depth 1) - ;; really we should only use this if - ;; in position 3 depth 1, but that's - ;; too expensive to compute. - 'font-lock-doc-string-face - 'font-lock-string-face))) - ((or (eq context 'comment) - (eq context 'block-comment)) - (setq face 'font-lock-comment-face) + (let ((lisp-like (font-lock-lisp-like major-mode))) + (syntactically-sectionize + #'(lambda (s e context depth) + (let (face) + (cond ((eq context 'string) + (setq face + ;; #### It would be nice if we handled + ;; Python and other non-Lisp languages with + ;; docstrings correctly. + (if (and lisp-like (= depth 1)) + ;; really we should only use this if + ;; in position 3 depth 1, but that's + ;; too expensive to compute. + 'font-lock-doc-string-face + 'font-lock-string-face))) + ((or (eq context 'comment) + (eq context 'block-comment)) + (setq face 'font-lock-comment-face) ; ;; Don't fontify whitespace at the beginning of lines; ; ;; otherwise comment blocks may not line up with code. ; ;; (This is sometimes a good idea, sometimes not; in any @@ -1323,9 +1336,9 @@ START should be at the beginning of a line." ; (skip-chars-forward " \t\n") ; (setq s (point))) )) - (font-lock-set-face s e face))) - start end) - )) + (font-lock-set-face s e face))) + start end) + ))) ;;; Additional text property functions. diff --git a/lisp/gutter-items.el b/lisp/gutter-items.el index ef6cabe..6b0b8f0 100644 --- a/lisp/gutter-items.el +++ b/lisp/gutter-items.el @@ -205,24 +205,25 @@ Only the most-recently-used few buffers will be listed on the tab, for efficiency reasons. You can control how many buffers will be shown by setting `buffers-tab-max-size'. You can control the text of the tab items by redefining the function `format-buffers-menu-line'." - (let* ((buffers (delete-if buffers-tab-omit-function (buffer-list frame))) - (first-buf (car buffers))) - ;; if we're in deletion ignore the current buffer - (when in-deletion - (setq buffers (delq (current-buffer) buffers)) - (setq first-buf (car buffers))) - ;; group buffers by mode - (when buffers-tab-selection-function - (delete-if-not #'(lambda (buf) - (funcall buffers-tab-selection-function - first-buf buf)) buffers)) - (and (integerp buffers-tab-max-size) - (> buffers-tab-max-size 1) - (> (length buffers) buffers-tab-max-size) - ;; shorten list of buffers - (setcdr (nthcdr buffers-tab-max-size buffers) nil)) - (setq buffers (build-buffers-tab-internal buffers)) - buffers)) + (save-match-data + (let* ((buffers (delete-if buffers-tab-omit-function (buffer-list frame))) + (first-buf (car buffers))) + ;; if we're in deletion ignore the current buffer + (when in-deletion + (setq buffers (delq (current-buffer) buffers)) + (setq first-buf (car buffers))) + ;; group buffers by mode + (when buffers-tab-selection-function + (delete-if-not #'(lambda (buf) + (funcall buffers-tab-selection-function + first-buf buf)) buffers)) + (and (integerp buffers-tab-max-size) + (> buffers-tab-max-size 1) + (> (length buffers) buffers-tab-max-size) + ;; shorten list of buffers + (setcdr (nthcdr buffers-tab-max-size buffers) nil)) + (setq buffers (build-buffers-tab-internal buffers)) + buffers))) (defun add-tab-to-gutter () "Put a tab control in the gutter area to hold the most recent buffers." diff --git a/lisp/help.el b/lisp/help.el index d482b53..8651aab 100644 --- a/lisp/help.el +++ b/lisp/help.el @@ -657,9 +657,20 @@ then only the mouse bindings are displayed." (gettext "key binding\n--- -------\n"))) (buffer (current-buffer)) (minor minor-mode-map-alist) + (extent-maps (mapcar-extents + 'extent-keymap + nil (current-buffer) (point) (point) nil 'keymap)) (local (current-local-map)) (shadow '())) (set-buffer standard-output) + (while extent-maps + (insert "Bindings for Text Region:\n" + heading) + (describe-bindings-internal + (car extent-maps) nil shadow prefix mouse-only-p) + (insert "\n") + (setq shadow (cons (car extent-maps) shadow) + extent-maps (cdr extent-maps))) (while minor (let ((sym (car (car minor))) (map (cdr (car minor)))) @@ -937,8 +948,9 @@ When run interactively, it defaults to any function found by (format (gettext "Describe function (default %s): ") fn) (gettext "Describe function: ")) - obarray 'fboundp t nil 'function-history)))) - (list (if (equal val "") fn (intern val))))) + obarray 'fboundp t nil 'function-history + (symbol-name fn))))) + (list (intern val)))) (with-displaying-help-buffer (lambda () (describe-function-1 function) @@ -1226,8 +1238,9 @@ part of the documentation of internal subroutines." (if v (format "Describe variable (default %s): " v) (gettext "Describe variable: ")) - obarray 'boundp t nil 'variable-history)))) - (list (if (equal val "") v (intern val))))) + obarray 'boundp t nil 'variable-history + (symbol-name v))))) + (list (intern val)))) (with-displaying-help-buffer (lambda () (let ((origvar variable) diff --git a/lisp/hyper-apropos.el b/lisp/hyper-apropos.el index b735091..af739d8 100644 --- a/lisp/hyper-apropos.el +++ b/lisp/hyper-apropos.el @@ -1079,6 +1079,12 @@ Deletes lines which match PATTERN." nil (forward-char 3) (read (point-marker)))) + ((and + (eq major-mode 'hyper-apropos-help-mode) + (> (point) (point-min))) + (save-excursion + (goto-char (point-min)) + (hyper-apropos-this-symbol))) (t (let* ((st (progn (skip-syntax-backward "w_") @@ -1121,11 +1127,6 @@ Deletes lines which match PATTERN." (interactive (let ((var (hyper-apropos-this-symbol))) (or (and var (boundp var)) - (and (setq var (and (eq major-mode 'hyper-apropos-help-mode) - (save-excursion - (goto-char (point-min)) - (hyper-apropos-this-symbol)))) - (boundp var)) (setq var nil)) (list var (hyper-apropos-read-variable-value var)))) (and var @@ -1175,7 +1176,10 @@ Deletes lines which match PATTERN." (defun hyper-apropos-customize-variable () (interactive) (let ((var (hyper-apropos-this-symbol))) - (customize-variable var))) + (and + (or (and var (boundp var)) + (setq var nil)) + (customize-variable var)))) ;; ---------------------------------------------------------------------- ;; @@ -1197,11 +1201,6 @@ window. (See also `find-function'.)" (interactive (let ((fn (hyper-apropos-this-symbol))) (or (fboundp fn) - (and (setq fn (and (eq major-mode 'hyper-apropos-help-mode) - (save-excursion - (goto-char (point-min)) - (hyper-apropos-this-symbol)))) - (fboundp fn)) (setq fn nil)) (list fn))) (if fn @@ -1257,11 +1256,7 @@ window. (See also `find-function'.)" (defun hyper-apropos-popup-menu (event) (interactive "e") (mouse-set-point event) - (let* ((sym (or (hyper-apropos-this-symbol) - (and (eq major-mode 'hyper-apropos-help-mode) - (save-excursion - (goto-char (point-min)) - (hyper-apropos-this-symbol))))) + (let* ((sym (hyper-apropos-this-symbol)) (notjunk (not (null sym))) (command-p (if (commandp sym) t)) (variable-p (and sym (boundp sym))) diff --git a/lisp/itimer.el b/lisp/itimer.el index aab95e4..32f93ff 100644 --- a/lisp/itimer.el +++ b/lisp/itimer.el @@ -20,6 +20,8 @@ (provide 'itimer) +(require 'lisp-float-type) + ;; `itimer' feature means Emacs-Lisp programmers get: ;; itimerp ;; itimer-live-p @@ -46,7 +48,7 @@ ;; ;; See the doc strings of these functions for more information. -(defvar itimer-version "1.07" +(defvar itimer-version "1.08" "Version number of the itimer package.") (defvar itimer-list nil @@ -62,7 +64,7 @@ is not being used to drive the system.") (defvar itimer-timer-last-wakeup nil "The time the timer driver function last ran.") -(defvar itimer-short-interval (if (featurep 'lisp-float-type) 1e-3 1) +(defvar itimer-short-interval 1e-3 "Interval used for scheduling an event a very short time in the future. Used internally to make the scheduler wake up early. Unit is seconds.") @@ -159,7 +161,7 @@ This is a macro." ;; Functions to access and modify itimer attributes. (defun itimerp (obj) - "Return t if OBJ is an itimer." + "Return non-nil if OBJ is an itimer." (and (consp obj) (eq (length obj) 8))) (defun itimer-live-p (obj) @@ -181,7 +183,7 @@ Itimers started with `start-itimer' are automatically active." (defun itimer-restart (itimer) "Return the value to which ITIMER will be set at restart. -Return nil if this itimer doesn't restart." +The value nil is returned if this itimer isn't set to restart." (check-itimer itimer) (nth 2 itimer)) @@ -194,8 +196,8 @@ This function is called each time ITIMER expires." (defun itimer-is-idle (itimer) "Return non-nil if ITIMER is an idle timer. Normal timers expire after a set interval. Idle timers expire -only after Emacs has been idle for a specific interval. -``Idle'' means no command events occur within the interval." +only after Emacs has been idle for a specific interval. ``Idle'' +means no command events have occurred within the interval." (check-itimer itimer) (nth 4 itimer)) @@ -208,7 +210,7 @@ The arguments themselves are retrievable with `itimer-function-arguments'." (defun itimer-function-arguments (itimer) "Return the function arguments of ITIMER as a list. -ITIMER's function is called with these argument each time ITIMER expires." +ITIMER's function is called with these arguments each time ITIMER expires." (check-itimer itimer) (nth 6 itimer)) @@ -302,7 +304,7 @@ minibuffer as initial user input." (get-itimer (completing-read prompt itimer-list nil 'confirm initial-input))) (defun delete-itimer (itimer) - "Delete ITIMER. ITIMER may be an itimer or the name of one." + "Deletes ITIMER. ITIMER may be an itimer or the name of one." (check-itimer-coerce-string itimer) (setq itimer-list (delq itimer itimer-list))) @@ -327,13 +329,13 @@ VALUE is the number of seconds until this itimer expires. must be an integer. Optional fourth arg RESTART non-nil means that this itimer should be restarted automatically after its function is called. Normally an itimer - is deleted at expiration after its function has returned. - If non-nil, RESTART should be a number indicating the value at which - the itimer should be set at restart time. + is deleted at expiration after its function has returned. + If non-nil RESTART should be a number indicating the value at which the + itimer should be set at restart time. Optional fifth arg IS-IDLE specifies if this is an idle timer. Normal timers expire after a set interval. Idle timers expire - only after Emacs has been idle for specific interval. - ``Idle'' means no command events occur within the interval. + only after Emacs has been idle for specific interval. ``Idle'' + means no command events have occurred within the interval. Returns the newly created itimer." (interactive (list (completing-read "Start itimer: " itimer-list) @@ -717,7 +719,12 @@ x start a new itimer (inhibit-quit nil) ;; for FSF Emacs timer.el emulation under XEmacs. ;; eldoc expect this to be done, apparently. - (this-command nil)) + (this-command nil) + ;; bind these variables so that the + ;; itimer function can't screw with + ;; them. + last-event-time next-wakeup + itimer itimers time-elapsed) (if (itimer-uses-arguments current-itimer) (apply (itimer-function current-itimer) (itimer-function-arguments current-itimer)) @@ -837,11 +844,9 @@ x start a new itimer secs (+ secs 65536)) (setq carry 0)) (setq 65536-secs (- (nth 0 t1) (nth 0 t2) carry)) - ;; loses for interval larger than the maximum signed Lisp integer. - ;; can't really be helped. - (+ (* 65536-secs 65536) + (+ (* 65536-secs 65536.0) secs - (/ usecs (if (featurep 'lisp-float-type) 1e6 1000000))))) + (/ usecs 1000000.0)))) (defun itimer-timer-driver (&rest ignored) ;; inhibit quit because if the user quits at an inopportune diff --git a/lisp/ldap.el b/lisp/ldap.el index 31c5be7..a0eaddf 100644 --- a/lisp/ldap.el +++ b/lisp/ldap.el @@ -5,7 +5,7 @@ ;; Author: Oscar Figueiredo ;; Maintainer: Oscar Figueiredo ;; Created: Jan 1998 -;; Version: $Revision: 1.7.2.3 $ +;; Version: $Revision: 1.7.2.6 $ ;; Keywords: help comm ;; This file is part of XEmacs diff --git a/lisp/lisp-mode.el b/lisp/lisp-mode.el index e5e97ec..fee10bd 100644 --- a/lisp/lisp-mode.el +++ b/lisp/lisp-mode.el @@ -290,6 +290,8 @@ if that value is non-nil." (lisp-mode-variables nil) (run-hooks 'emacs-lisp-mode-hook)) +(put 'emacs-lisp-mode 'font-lock-lisp-like t) + (defvar lisp-mode-map () "Keymap for ordinary Lisp mode. All commands in `shared-lisp-mode-map' are inherited by this map.") diff --git a/lisp/minibuf.el b/lisp/minibuf.el index d567f42..7b83a3c 100644 --- a/lisp/minibuf.el +++ b/lisp/minibuf.el @@ -344,7 +344,8 @@ minibuffer history if its length is less than that value." keymap readp history - abbrev-table) + abbrev-table + default) "Read a string from the minibuffer, prompting with string PROMPT. If optional second arg INITIAL-CONTENTS is non-nil, it is a string to be inserted into the minibuffer before reading input. @@ -366,6 +367,8 @@ Fifth arg HISTORY, if non-nil, specifies a history list Positions are counted starting from 1 at the beginning of the list. Sixth arg ABBREV-TABLE, if non-nil, becomes the value of `local-abbrev-table' in the minibuffer. +Seventh arg DEFAULT, if non-nil, will be returned when user enters + an empty string. See also the variable completion-highlight-first-word-only for control over completion display." @@ -490,8 +493,13 @@ See also the variable completion-highlight-first-word-only for control over (let* ((val (progn (set-buffer buffer) (if minibuffer-exit-hook (run-hooks 'minibuffer-exit-hook)) - (buffer-string))) - (histval val) + (if (and (eq (char-after (point-min)) nil) + default) + default + (buffer-string)))) + (histval (if (and default (string= val "")) + default + val)) (err nil)) (if readp (condition-case e @@ -784,7 +792,9 @@ Completion ignores case if the ambient value of minibuffer-local-completion-map minibuffer-local-must-match-map) nil - history)) + history + nil + default)) (if (and (string= ret "") default) default @@ -1434,7 +1444,8 @@ only existing buffer names are allowed." result) (while (progn (setq result (completing-read prompt alist nil require-match - nil 'buffer-history)) + nil 'buffer-history + (if default (buffer-name default)))) (cond ((not (equal result "")) nil) ((not require-match) diff --git a/lisp/package-get.el b/lisp/package-get.el index 0b70110..ab3654e 100644 --- a/lisp/package-get.el +++ b/lisp/package-get.el @@ -185,33 +185,51 @@ order until the package is found. As a special case, `site-name' can be '( ;; North America ("xemacs.org" "ftp.xemacs.org" "pub/xemacs/packages") - ("cso.uiuc.edu" "ftp.cso.uiuc.edu" "pub/packages/xemacs/packages") + ("crc.ca (Canada)" "ftp.crc.ca" "pub/packages/editors/xemacs/packages") + ("ualberta.ca (Canada)" "sunsite.ualberta.ca" "pub/Mirror/xemacs/packages") + ("uiuc.edu (United States)" "uiarchive.uiuc.edu" "pub/packages/xemacs/packages") + ("unc.edu (United States)" "metalab.unc.edu" "pub/packages/editors/xemacs/packages") + ("utk.edu (United States)" "ftp.sunsite.utk.edu" "pub/xemacs/packages") ;; South America - ("unicamp.br" "ftp.unicamp.br" "pub/xemacs/packages") + ("unicamp.br (Brazil)" "ftp.unicamp.br" "pub/xemacs/packages") ;; Europe - ("sunsite.cnlab-switch.ch" "sunsite.cnlab-switch.ch" "mirror/xemacs/packages") - ("tu-darmstadt.de" "ftp.tu-darmstadt.de" "pub/editors/xemacs/packages") - ("sunsite.auc.dk" "sunsite.auc.dk" "pub/emacs/xemacs/packages") - ("pasteur.fr" "ftp.pasteur.fr" "pub/computing/xemacs/packages") - ("cenatls.cena.dgac.fr" "ftp.cenatls.cena.dgac.fr" "pub/Emacs/xemacs/packages") - ("kfki.hu" "ftp.kfki.hu" "pub/packages/xemacs/packages") - ("uniroma2.it" "ftp.uniroma2.it" "unix/misc/dist/XEMACS/packages") - ("icm.edu.pl" "ftp.icm.edu.pl" "pub/unix/editors/xemacs/packages") - ("sunet.se" "ftp.sunet.se" "pub/gnu/xemacs/packages") - ("doc.ic.ac.uk" "sunsite.doc.ic.ac.uk" "packages/xemacs/packages") - ("srcc.msu.su" "ftp1.srcc.msu.su" "mirror/ftp.xemacs.org/packages") + ("tuwien.ac.at (Austria)" "gd.tuwien.ac.at" "editors/xemacs/packages") + ("auc.dk (Denmark)" "sunsite.auc.dk" "pub/emacs/xemacs/packages") + ("doc.ic.ac.uk (England)" "sunsite.doc.ic.ac.uk" "packages/xemacs/packages") + ("funet.fi (Finland)" "ftp.funet.fi" "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/packages") + ("cenatls.cena.dgac.fr (France)" "ftp.cenatls.cena.dgac.fr" "Emacs/xemacs/packages") + ("pasteur.fr (France)" "ftp.pasteur.fr" "pub/computing/xemacs/packages") + ("tu-darmstadt.de (Germany)" "ftp.tu-darmstadt.de" "pub/editors/xemacs/packages") + ("kfki.hu (Hungary)" "ftp.kfki.hu" "pub/packages/xemacs/packages") + ("eunet.ie (Ireland)" "ftp.eunet.ie" "mirrors/ftp.xemacs.org/pub/xemacs/packages") + ("uniroma2.it (Italy)" "ftp.uniroma2.it" "unix/misc/dist/XEMACS/packages") + ("uio.no (Norway)" "sunsite.uio.no" "pub/xemacs/packages") + ("icm.edu.pl (Poland)" "ftp.icm.edu.pl" "pub/unix/editors/xemacs/packages") + ("srcc.msu.su (Russia)" "ftp.srcc.msu.su" "mirror/ftp.xemacs.org/packages") + ("sunet.se (Sweden)" "ftp.sunet.se" "pub/gnu/xemacs/packages") + ("cnlab-switch.ch (Switzerland)" "sunsite.cnlab-switch.ch" "mirror/xemacs/packages") ;; Asia - ("usyd.edu.au" "ftp.usyd.edu.au" "pub/Xemacs/packages") - ("netlab.is.tsukuba.ac.jp" "ftp.netlab.is.tsukuba.ac.jp" "pub/GNU/xemacs/packages") - ("jaist.ac.jp" "ftp.jaist.ac.jp" "pub/GNU/xemacs/packages") - ("ring.aist.go.jp" "ring.aist.go.jp" "pub/text/xemacs/packages") - ("ring.asahi-net.or.jp" "ring.asahi-net.or.jp" "pub/text/xemacs/packages") - ("SunSITE.sut.ac.jp" "SunSITE.sut.ac.jp" "pub/archives/packages/xemacs/packages") - ("dti.ad.jp" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/packages") - ("kreonet.re.kr" "ftp.kreonet.re.kr" "pub/tools/emacs/xemacs/packages") + ("aist.go.jp (Japan)" "ring.aist.go.jp" "pub/text/xemacs/packages") + ("asahi-net.or.jp (Japan)" "ring.asahi-net.or.jp" "pub/text/xemacs/packages") + ("dti.ad.jp (Japan)" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/packages") + ("jaist.ac.jp (Japan)" "ftp.jaist.ac.jp" "pub/GNU/xemacs/packages") + ("nucba.ac.jp (Japan)" "mirror.nucba.ac.jp" "mirror/xemacs/packages") + ("sut.ac.jp (Japan)" "sunsite.sut.ac.jp" "pub/archives/packages/xemacs/packages") + ("tsukuba.ac.jp (Japan)" "ftp.netlab.is.tsukuba.ac.jp" "pub/GNU/xemacs/packages") + ("kreonet.re.kr (Korea)" "ftp.kreonet.re.kr" "pub/tools/emacs/xemacs/packages") + ("nctu.edu.tw (Taiwan)" "coda.nctu.edu.tw" "Editors/xemacs/packages") + + ;; Africa + ("sun.ac.za (South Africa)" "ftp.sun.ac.za" "xemacs/packages") + + ;; Middle East + ("isu.net.sa (Saudi Arabia)" "ftp.isu.net.sa" "pub/mirrors/ftp.xemacs.org/packages") + + ;; Australia + ("aarnet.edu.au (Australia)" "mirror.aarnet.edu.au" "pub/xemacs/packages") ) "*List of remote sites available for downloading packages. List format is '(site-description site-name directory-on-site). diff --git a/lisp/symbols.el b/lisp/symbols.el index c965f6c..d359378 100644 --- a/lisp/symbols.el +++ b/lisp/symbols.el @@ -124,7 +124,7 @@ each of the handlers." (let ((event (apply getfun harg args))) (if (event-live-p event) nil - (setq event (allocate-event)) + (setq event (make-event)) (apply setfun harg event args)) (character-to-event value event))) diff --git a/lwlib/ChangeLog b/lwlib/ChangeLog index fc91207..13b953d 100644 --- a/lwlib/ChangeLog +++ b/lwlib/ChangeLog @@ -1,3 +1,14 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-12-05 Andy Piper + + * xlwtabs.c: back up to previous rev to make syncing easier. Fix + gcc moans. + + * lwlib-Xaw.c (xaw_update_one_widget): use XtIsSubclass. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/lwlib/xlwmenu.c b/lwlib/xlwmenu.c index 4b01283..e6d31ae 100644 --- a/lwlib/xlwmenu.c +++ b/lwlib/xlwmenu.c @@ -1529,7 +1529,7 @@ label_button_size (XlwMenuWidget mw, 2 * mw->menu.vertical_margin + 2 * mw->menu.shadow_thickness); /* no left column decoration */ - *toggle_width = mw->menu.horizontal_margin + mw->menu.shadow_thickness;; + *toggle_width = mw->menu.horizontal_margin + mw->menu.shadow_thickness; *label_width = string_width_u (mw, resource_widget_value (mw, val)); *bindings_width = mw->menu.horizontal_margin + mw->menu.shadow_thickness; diff --git a/lwlib/xlwtabs.c b/lwlib/xlwtabs.c index 99918c7..559fc91 100644 --- a/lwlib/xlwtabs.c +++ b/lwlib/xlwtabs.c @@ -598,75 +598,74 @@ static Boolean TabsSetValues(Widget current, Widget request, Widget new, ArgList args, Cardinal *num_args) { - TabsWidget curtw = (TabsWidget) current ; - TabsWidget tw = (TabsWidget) new ; - Boolean needRedraw = False ; - Widget *childP ; - int i ; + TabsWidget curtw = (TabsWidget) current ; + TabsWidget tw = (TabsWidget) new ; + Boolean needRedraw = False ; + Widget *childP ; + int i ; - if( tw->tabs.font != curtw->tabs.font || - tw->tabs.internalWidth != curtw->tabs.internalWidth || - tw->tabs.internalHeight != curtw->tabs.internalHeight ) - { - tw->tabs.tab_height = 2 * tw->tabs.internalHeight + SHADWID ; - - if( tw->tabs.font != NULL ) - tw->tabs.tab_height += tw->tabs.font->max_bounds.ascent + - tw->tabs.font->max_bounds.descent ; - - /* Tab size has changed. Resize all tabs and request a new size */ - for(i=0, childP=tw->composite.children; - i < tw->composite.num_children; - ++i, ++childP) - if( XtIsManaged(*childP) ) - TabWidth(*childP) ; - PreferredSize(tw, &tw->core.width, &tw->core.height, NULL,NULL) ; - needRedraw = True ; - tw->tabs.needs_layout = True ; - } + if( tw->tabs.font != curtw->tabs.font || + tw->tabs.internalWidth != curtw->tabs.internalWidth || + tw->tabs.internalHeight != curtw->tabs.internalHeight ) + { + tw->tabs.tab_height = 2 * tw->tabs.internalHeight + SHADWID ; - /* TODO: if any color changes, need to recompute GCs and redraw */ + if( tw->tabs.font != NULL ) + tw->tabs.tab_height += tw->tabs.font->max_bounds.ascent + + tw->tabs.font->max_bounds.descent ; - if( tw->core.background_pixel != curtw->core.background_pixel || - tw->core.background_pixmap != curtw->core.background_pixmap ) - if( XtIsRealized(new) ) - { - TabsFreeGCs(tw) ; - TabsAllocGCs(tw) ; - needRedraw = True ; - } + /* Tab size has changed. Resize all tabs and request a new size */ + for(i=0, childP=tw->composite.children; + i < tw->composite.num_children; + ++i, ++childP) + if( XtIsManaged(*childP) ) + TabWidth(*childP) ; + PreferredSize(tw, &tw->core.width, &tw->core.height, NULL,NULL) ; + needRedraw = True ; + tw->tabs.needs_layout = True ; + } - if( tw->core.sensitive != curtw->core.sensitive ) - needRedraw = True ; + /* TODO: if any color changes, need to recompute GCs and redraw */ - /* If top widget changes, need to change stacking order, redraw tabs. - * Window system will handle the redraws. - */ + if( tw->core.background_pixel != curtw->core.background_pixel || + tw->core.background_pixmap != curtw->core.background_pixmap ) + if( XtIsRealized(new) ) + { + TabsFreeGCs(tw) ; + TabsAllocGCs(tw) ; + needRedraw = True ; + } - if( tw->tabs.topWidget != curtw->tabs.topWidget ) - { - if( XtIsRealized(tw->tabs.topWidget) ) - { - Widget w = tw->tabs.topWidget ; - TabsConstraints tab = (TabsConstraints) w->core.constraints ; + if( tw->core.sensitive != curtw->core.sensitive ) + needRedraw = True ; + + /* If top widget changes, need to change stacking order, redraw tabs. + * Window system will handle the redraws. + */ + + if( tw->tabs.topWidget != curtw->tabs.topWidget ) { + if( XtIsRealized(tw->tabs.topWidget) ) + { + Widget w = tw->tabs.topWidget ; + TabsConstraints tab = (TabsConstraints) w->core.constraints ; - XRaiseWindow(XtDisplay(w), XtWindow(w)) ; + XRaiseWindow(XtDisplay(w), XtWindow(w)) ; #ifdef NEED_MOTIF - XtVaSetValues(curtw->tabs.topWidget, XmNtraversalOn, False, 0) ; - XtVaSetValues(w, XmNtraversalOn, True, 0) ; + XtVaSetValues(curtw->tabs.topWidget, XmNtraversalOn, False, 0) ; + XtVaSetValues(w, XmNtraversalOn, True, 0) ; #endif - if( tab->tabs.row != tw->tabs.numRows-1 ) - TabsShuffleRows(tw) ; + if( tab->tabs.row != tw->tabs.numRows-1 ) + TabsShuffleRows(tw) ; - needRedraw = True ; - } - else - tw->tabs.needs_layout = True ; - } + needRedraw = True ; + } + } + else + tw->tabs.needs_layout = True ; - return needRedraw ; + return needRedraw ; } @@ -820,8 +819,8 @@ TabsGeometryManager(Widget w, XtWidgetGeometry *req, XtWidgetGeometry *reply) Dimension th ; /* space used by tabs */ Dimension wid,hgt ; /* Tabs widget size */ - rw = tab->tabs.wid ; - rh = tab->tabs.hgt ; + rw = cw = tab->tabs.wid ; + rh = ch = tab->tabs.hgt ; /* find out what the resulting preferred size would be */ @@ -1059,7 +1058,7 @@ static void TabsPage(Widget w, XEvent *event, String *params, Cardinal *num_params) { TabsWidget tw = (TabsWidget) w ; - Widget newtop ; + Widget newtop = NULL; Widget *childP ; int idx ; int nc = tw->composite.num_children ; @@ -1122,7 +1121,7 @@ static void TabsHighlight(Widget w, XEvent *event, String *params, Cardinal *num_params) { TabsWidget tw = (TabsWidget) w ; - Widget newhl ; + Widget newhl = NULL; Widget *childP ; int idx ; int nc = tw->composite.num_children ; diff --git a/man/ChangeLog b/man/ChangeLog index 7f276b8..14d05d4 100644 --- a/man/ChangeLog +++ b/man/ChangeLog @@ -1,3 +1,23 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-12-06 Sandra Wambold + + * xemacs-faq.texi: Added MS-Windows questions; some other changes + +1999-11-29 Martin Buchholz + + * info.texi (Top): + Remove @ifnottex, which gives old makeinfos indigestion. + * texinfo.texi (Top): + Revert to pre-texinfo-4.0 version, plus small changes to make + texinfo-3.12, texinfo-3.12f, texinfo-4.0, and TeX happy. + +1999-11-30 Sandra Wambold + + * xemacs-faq.texi: fixed and commented out bad URL links + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/man/info.texi b/man/info.texi index fea0d0d..e9eab51 100644 --- a/man/info.texi +++ b/man/info.texi @@ -3,7 +3,7 @@ @setfilename ../info/info.info @settitle Info @comment %**end of header -@comment $Id: info.texi,v 1.11 1999/04/19 21:37:23 karl Exp $ +@comment $Id: info.texi,v 1.4.2.3 1999/12/05 19:02:24 martinb Exp $ @dircategory Texinfo documentation system @direntry @@ -66,15 +66,14 @@ except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end titlepage -@ifnottex @node Top @top Info: An Introduction -Info is a program for reading documentation, which you are using now. +Info is a program for reading documentation, which you might be using +now to read this. -To learn how to use Info, type the command @kbd{h}. It brings you -to a programmed instruction sequence. -@end ifnottex +To learn how to use Info, type the command @kbd{h} while using the Info +program. It brings you to a programmed instruction sequence. @menu * Getting Started:: Getting started using an Info reader. diff --git a/man/texinfo.texi b/man/texinfo.texi index 2afcb58..73037d2 100644 --- a/man/texinfo.texi +++ b/man/texinfo.texi @@ -1,14 +1,15 @@ \input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.txi,v 1.162 1999/09/28 19:38:01 karl Exp $ +@c $Id: texinfo.texi,v 1.8.2.4 1999/12/05 19:02:24 martinb Exp $ @c %**start of header @c All text is ignored before the setfilename. @setfilename ../info/texinfo.info +@settitle Texinfo @value{edition} -@set UPDATED 28 September 1999 -@set EDITION 4.0 -@set VERSION 4.0 -@settitle Texinfo @value{VERSION} +@c Edition number is now the same as the Texinfo distribution version number. +@set edition 3.12 +@set update-month February 1998 +@set update-date 27 @value{update-month} @c Define a new index for options. @defcodeindex op @@ -21,21 +22,20 @@ @footnotestyle separate @paragraphindent 2 @finalout - @comment %**end of header +@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a +@c prefix arg). This updates the node pointers, which texinfmt.el needs. + @dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Update info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. +* install-info: (texinfo)Invoking install-info. Updating info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. +* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. @end direntry -@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a -@c prefix arg). This updates the node pointers, which texinfmt.el needs. - @c Set smallbook if printing in smallbook format so the example of the @c smallbook font is actually written using smallbook; in bigbook, a kludge @c is used for TeX output. Do this through the -t option to texi2dvi, @@ -44,20 +44,17 @@ @c set smallbook @c @@clear smallbook -@c If you like blank pages. Can add through texi2dvi -t. -@c setchapternewpage odd - @c Currently undocumented command, 5 December 1993: @c nwnode (Same as node, but no warnings; for `makeinfo'.) @ifinfo This file documents Texinfo, a documentation system that can produce -both online information and a printed manual from a single source file. +both on-line information and a printed manual from a single source file. -Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 +Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software Foundation, Inc. -This edition is for Texinfo version @value{VERSION}, @value{UPDATED}. +This edition is for Texinfo version @value{edition}. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -81,6 +78,7 @@ except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end ifinfo +@setchapternewpage odd @shorttitlepage Texinfo @@ -88,27 +86,25 @@ by the Free Software Foundation. @c use the new format for titles @title Texinfo @subtitle The GNU Documentation Format -@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} +@subtitle for Texinfo version @value{edition} +@subtitle @value{update-month} -@author Robert J. Chassell -@author Richard M. Stallman +@author Robert J.@: Chassell +@author Richard M.@: Stallman @c Include the Distribution inside the titlepage so @c that headings are turned off. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 +Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software Foundation, Inc. -This manual is for Texinfo version @value{VERSION}, @value{UPDATED}. - Published by the Free Software Foundation @* 59 Temple Place Suite 330 @* Boston, MA 02111-1307 @* USA @* -ISBN 1-882114-67-1 @c for version 4.0, September 1999. -@c ISBN 1-882114-65-5 @c for version 3.12, March 1998. +ISBN 1-882114-65-5 @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. @@ -129,22 +125,65 @@ by the Free Software Foundation. Cover art by Etienne Suvasa. @end titlepage -@summarycontents -@contents - -@ifnottex -@node Top +@ifinfo +@node Top, Copying, (dir), (dir) @top Texinfo Texinfo is a documentation system that uses a single source file to -produce both online information and printed output. +produce both on-line information and printed output.@refill The first part of this master menu lists the major nodes in this Info document, including the @@-command and concept indices. The rest of -the menu lists all the lower level nodes in the document. +the menu lists all the lower level nodes in the document.@refill + +This is Edition @value{edition} of the Texinfo documentation, +@w{@value{update-date}}. +@end ifinfo -This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. -@end ifnottex +@c Here is a spare copy of the chapter menu entry descriptions, +@c in case they are accidently deleted +@ignore +Your rights. +Texinfo in brief. +How to use Texinfo mode. +What is at the beginning of a Texinfo file? +What is at the end of a Texinfo file? +How to create chapters, sections, subsections, + appendices, and other parts. +How to provide structure for a document. +How to write nodes. +How to write menus. +How to write cross references. +How to mark words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +How to write quotations, examples, etc. +How to write lists and tables. +How to create indices. +How to insert @@-signs, braces, etc. +How to indicate results of evaluation, + expansion of macros, errors, etc. +How to force and prevent line and page breaks. +How to describe functions and the like in a uniform manner. +How to write footnotes. +How to specify text for either @TeX{} or Info. +How to print hardcopy. +How to create an Info file. +How to install an Info file +A list of all the Texinfo @@-commands. +Hints on how to write a Texinfo document. +A sample Texinfo file to look at. +Tell readers they have the right to copy + and distribute. +How to incorporate other Texinfo files. +How to write page headings and footings. +How to find formatting mistakes. +All about paragraph refilling. +A description of @@-Command syntax. +Texinfo second edition features. +A menu containing commands and variables. +A menu covering many topics. +@end ignore @menu * Copying:: Your rights. @@ -167,12 +206,13 @@ This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. * Breaks:: How to force and prevent line and page breaks. * Definition Commands:: How to describe functions and the like in a uniform manner. +* Footnotes:: How to write footnotes. * Conditionals:: How to specify text for either @TeX{} or Info. -* Internationalization:: -* Defining New Texinfo Commands:: -* Hardcopy:: How to convert a Texinfo file to a file +* Macros:: Defining new Texinfo commands. +* Format/Print Hardcopy:: How to convert a Texinfo file to a file for printing and how to print that file. -* Creating and Installing Info Files:: +* Create an Info File:: Convert a Texinfo file into an Info file. +* Install an Info File:: Make an Info file accessible to users. * Command List:: All the Texinfo @@-commands. * Tips:: Hints on how to write a Texinfo document. * Sample Texinfo File:: A sample Texinfo file to look at. @@ -193,17 +233,18 @@ This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. Overview of Texinfo -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. +* Using Texinfo:: Create a conventional printed book + or an Info file. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @@-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* Acknowledgements:: Using Texinfo Mode @@ -244,8 +285,7 @@ The Texinfo File Header * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* exampleindent:: Specify environment indentation. +* paragraphindent:: An option to specify paragraph indentation. * End of Header:: Formatting a region requires this. The Title and Copyright Pages @@ -294,9 +334,8 @@ Nodes * Two Paths:: Different commands to structure Info output and printed output. * Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. +* node:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. The @code{@@node} Command @@ -345,26 +384,23 @@ Marking Words and Phrases Indicating Definitions, Commands, etc. * Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: Showing a literal sequence of characters. -* var:: Indicating metasyntactic variables. -* env:: Indicating environment variables. -* file:: Indicating file names. -* command:: Indicating command names. -* option:: Indicating option names. -* dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. -* acronym:: Indicating acronyms. -* url:: Indicating a World Wide Web reference. -* email:: Indicating an electronic mail address. +* code:: How to indicate code. +* kbd:: How to show keyboard input. +* key:: How to specify keys. +* samp:: How to show a literal sequence of characters. +* var:: How to indicate a metasyntactic variable. +* file:: How to indicate the name of a file. +* dfn:: How to specify a definition. +* cite:: How to refer to a book that is not in Info. +* url:: How to indicate a world wide web reference. +* email:: How to indicate an electronic mail address. Emphasizing Text * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. Quotations and Examples @@ -373,8 +409,8 @@ Quotations and Examples * quotation:: How to write a quotation. * example:: How to write an example in a fixed-width font. * noindent:: How to prevent paragraph indentation. -* lisp:: How to illustrate Lisp code. -* small:: Forms for @code{@@smallbook}. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. * display:: How to write an example in the current font. * format:: How to write an example that does not narrow the margins. @@ -401,7 +437,7 @@ Multi-column Tables * Multitable Column Widths:: Defining multitable column widths. * Multitable Rows:: Defining multitable rows, with examples. -Indices +Creating Indices * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds @@ -431,7 +467,6 @@ Special Insertions * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. -* Footnotes:: How to include footnotes. * Images:: How to include graphics. Inserting @@ and Braces @@ -468,17 +503,12 @@ Glyphs for Examples Glyphs Summary -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: - -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. +* result:: +* expansion:: +* Print Glyph:: +* Error Glyph:: +* Equivalence:: +* Point Glyph:: Making and Preventing Breaks @@ -510,6 +540,11 @@ The Definition Commands * Abstract Objects:: Commands for object-oriented programming. * Data Types:: The definition command for data types. +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. + Conditionally Visible Text * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. @@ -522,45 +557,30 @@ Conditionally Visible Text @code{@@set}, @code{@@clear}, and @code{@@value} * ifset ifclear:: Format a region if a flag is set. -* set value:: Expand a flag variable to a string. +* value:: Replace a flag with a string. * value Example:: An easy way to update edition information. -Internationalization - -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. +Macros: Defining New Texinfo Commands -Defining New Texinfo Commands - -* Defining Macros:: Defining and undefining new commands. +* Defining Macros:: Both defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Beyond basic macro usage. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. -Formatting and Printing Hardcopy +Format and Print Hardcopy * Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. +* Format with tex/texindex:: How to format in a shell. +* Format with texi2dvi:: A simpler way to use the shell. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What to do before you use @TeX{}. +* Preparing for TeX:: What you need to do to use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on European A4 paper. -* pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. - -Creating and Installing Info Files - -* Creating an Info File:: -* Install an Info File:: Creating an Info File @@ -575,11 +595,10 @@ Creating an Info File * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. -* makeinfo html:: Generating HTML output. Installing an Info File -* Directory File:: The top level menu for all Info files. +* Directory file:: The top level menu for all Info files. * New Info File:: Listing a new info file. * Other Info Directories:: How to specify Info files that are located in other directories. @@ -626,19 +645,16 @@ Finding Badly Referenced Nodes * Unsplit:: How to create an unsplit file. * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. -@end detailmenu -@end menu -@c Reward readers for getting to the end of the menu :). -@c Contributed by Arnold Robbins. -@quotation -Documentation is like sex: when it is good, it is very, very good; and -when it is bad, it is better than nothing. ----Dick Brandon -@end quotation +How to Obtain @TeX{} +@c * New Texinfo Mode Commands:: The updating commands are especially useful. +@c * New Commands:: Many newly described @@-commands. +@end detailmenu +@end menu -@node Copying +@node Copying, Overview, Top, Top +@comment node-name, next, previous, up @unnumbered Texinfo Copying Conditions @cindex Copying conditions @cindex Conditions for copying Texinfo @@ -674,171 +690,100 @@ their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.@refill -The precise conditions of the licenses for the programs currently + The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public -Licenses that accompany them. - +Licenses that accompany them.@refill -@node Overview +@node Overview, Texinfo Mode, Copying, Top +@comment node-name, next, previous, up @chapter Overview of Texinfo @cindex Overview of Texinfo @cindex Texinfo overview -@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced -like ``speck'', not ``hex''. This odd pronunciation is derived from, -but is not the same as, the pronunciation of @TeX{}. In the word -@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than -the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the -last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x} -were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other -letters in lower case.} is a documentation system that uses a single -source file to produce both online information and printed output. This -means that instead of writing two different documents, one for the -online information and the other for a printed work, you need write only -one document. Therefore, when the work is revised, you need revise only -that one document. +@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is +pronounced like ``speck'', not ``hex''. This odd pronunciation is +derived from, but is not the same as, the pronunciation of @TeX{}. In +the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' +rather than the English letter ``ex''. Pronounce @TeX{} as if the +@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo +as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' +and write the other letters in lower case.} +is a documentation system that uses a single source file to produce both +on-line information and printed output. This means that instead of +writing two different documents, one for the on-line help or other on-line +information and the other for a typeset manual or other printed work, you +need write only one document. When the work is revised, you need revise +only one document. (You can read the on-line information, known as an +@dfn{Info file}, with an Info documentation-reading program.)@refill @menu -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. +* Using Texinfo:: Create a conventional printed book + or an Info file. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @@-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* Acknowledgements:: @end menu - -@node Reporting Bugs -@section Reporting Bugs - -@cindex Bugs, reporting -@cindex Suggestions for Texinfo, making -@cindex Reporting bugs -We welcome bug reports or suggestions for the Texinfo system, both -programs and documentation. Please email them to -@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo -from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. - -@cindex Checklist for bug reports -For bug reports, please include enough information for the maintainers -to reproduce the problem. Generally speaking, that means: - -@itemize @bullet -@item the version number of Texinfo and the program(s) or manual(s) involved. -@item hardware, operating system, and compiler versions. -@item any unusual options you gave to @command{configure}. -@item the contents of any input files necessary to reproduce the bug. -@item a description of the problem and samples of any erroneous output. -@item anything else that you think would be helpful. -@end itemize - -When in doubt whether something is needed or not, include it. It's -better to include too much than to leave out something important. - -Patches are most welcome; if possible, please make them with -@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and -Merging Files}) and include @file{ChangeLog} entries (@pxref{Change -Log,,, emacs, The GNU Emacs Manual}). - -When sending email, please do not encode or split the messages in any -way if possible; it's much easier to deal with one plain text message, -however large, than many small ones. -@uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of -packaging multiple and/or binary files for email. - - -@node Using Texinfo -@section Using Texinfo - -@cindex Using Texinfo in general -@cindex Texinfo, introduction to -@cindex Introduction to Texinfo +@node Using Texinfo, Info Files, Overview, Overview +@ifinfo +@heading Using Texinfo +@end ifinfo Using Texinfo, you can create a printed document with the normal -features of a book, including chapters, sections, cross references, and -indices. From the same Texinfo source file, you can create a -menu-driven, online Info file with nodes, menus, cross references, and -indices. You can also create from that same source file an HTML output -file suitable for use with a web browser. @cite{The GNU Emacs Manual} -is a good example of a Texinfo file, as is this manual. +features of a book, including chapters, sections, cross references, +and indices. From the same Texinfo source file, you can create a +menu-driven, on-line Info file with nodes, menus, cross references, +and indices. You can, if you wish, make the chapters and sections of +the printed document correspond to the nodes of the on-line +information; and you use the same cross references and indices for +both the Info file and the printed work. @cite{The GNU +Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill To make a printed document, you process a Texinfo source file with the -@TeX{} typesetting program (but the Texinfo language is very different -from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file -that you can typeset and print as a book or report (@pxref{Hardcopy}). - -@pindex makeinfo -To output an Info file, process your Texinfo source with the -@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command. -You can install the result in your Info tree (@pxref{Install an Info -File}). - -To output an HTML file, process your Texinfo source with @code{makeinfo} -using the @samp{--html} option. You can (for example) install the -result on your web site. - -@cindex Output formats, supporting more -@cindex Docbook output format -@cindex SGML-tools output format -If you are a programmer and would like to contribute to the GNU project -by implementing additional output formats for Texinfo, that would be -excellent. But please do not write a separate translator texi2foo for -your favorite format foo! That is the hard way to do the job, and makes -extra work in subsequent maintenance, since the Texinfo language is -continually being enhanced and updated. Instead, the best approach is -modify @code{makeinfo} to generate the new format, as it does now for -Info and HTML. - -@TeX{} works with virtually all printers; Info works with virtually all -computer terminals; the HTML output works with virtually all web -browsers. Thus Texinfo can be used by almost any computer user. - -@cindex Source file -A Texinfo source file is a plain @sc{ascii} file containing text and +@TeX{} typesetting program. This creates a DVI file that you can +typeset and print as a book or report. (Note that the Texinfo language +is completely different from @TeX{}'s usual language, plain @TeX{}.) If +you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you +can use the @code{texi2roff} program instead.@refill + +To make an Info file, you process a Texinfo source file with the +@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; +this creates an Info file that you can install on-line.@refill + +@TeX{} and @code{texi2roff} work with many types of printers; similarly, +Info works with almost every type of computer terminal. This power +makes Texinfo a general purpose system, but brings with it a constraint, +which is that a Texinfo file may contain only the customary +``typewriter'' characters (letters, numbers, spaces, and punctuation +marks) but no special graphics.@refill + +A Texinfo file is a plain @sc{ascii} file containing text and @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the -typesetting and formatting programs what to do. You may edit a Texinfo -file with any text editor; but it is especially convenient to use GNU -Emacs since that editor has a special mode, called Texinfo mode, that -provides various Texinfo-related features. (@xref{Texinfo Mode}.) - -Before writing a Texinfo source file, you should learn about nodes, -menus, cross references, and the rest, for example by reading this -manual. +typesetting and formatting programs what to do. You may edit a +Texinfo file with any text editor; but it is especially convenient to +use GNU Emacs since that editor has a special mode, called Texinfo +mode, that provides various Texinfo-related features. (@xref{Texinfo +Mode}.)@refill + +Before writing a Texinfo source file, you should become familiar with +the Info documentation reading program and learn about nodes, +menus, cross references, and the rest. (@inforef{Top, info, info}, +for more information.)@refill -You can use Texinfo to create both online help and printed manuals; +You can use Texinfo to create both on-line help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the official documentation format of the GNU project. More -information is available at the @uref{http://www.gnu.org/doc/, GNU -documentation web page}. - -@cindex Man page output, not supported -From time to time, proposals are made to generate traditional Unix man -pages from Texinfo source. This is not likely to ever be supported, -because man pages have a very strict conventional format. Merely -enhancing @command{makeinfo} to output troff format would be -insufficient. Generating a good man page therefore requires a -completely different source than the typical Texinfo applications of -generating a good user manual or a good reference manual. This makes -generating man pages incompatible with the Texinfo design goal of not -having to document the same information in different ways for different -output formats. You might as well just write the man page directly. - -@pindex help2man -@cindex O'Dea, Brendan -If you wish to support man pages, the program @command{help2man} may be -useful; it generates a traditional man page from the @samp{--help} -output of a program. In fact, this is currently used to generate man -pages for the Texinfo programs themselves. It is free software written -by Brendan O'Dea, available from -@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}. - - -@node Info Files +is the format in which documentation for GNU utilities and libraries is +written.@refill + +@node Info Files, Printed Books, Using Texinfo, Overview +@comment node-name, next, previous, up @section Info files @cindex Info files @@ -925,20 +870,8 @@ The @file{dir} file in the @file{info} directory serves as the departure point for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system.@refill -@cindex URI syntax for Info -If you wish to refer to an Info file in a URI, you can use the -(unofficial) syntax exemplified in the following. This works with -Emacs/W3, for example: -@example -info:///usr/info/emacs#Dissociated%20Press -info:emacs#Dissociated%20Press -info://localhost/usr/info/emacs#Dissociated%20Press -@end example - -The @command{info} program itself does not follow URI's of any kind. - - -@node Printed Books +@node Printed Books, Formatting Commands, Info Files, Overview +@comment node-name, next, previous, up @section Printed Books @cindex Printed book and manual characteristics @cindex Manual characteristics, printed @@ -950,12 +883,9 @@ The @command{info} program itself does not follow URI's of any kind. A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need @TeX{}, a powerful, sophisticated typesetting program written by Donald Knuth.@footnote{You can also use the -@pindex texi2roff@r{, unsupported software} -@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you -do not have @TeX{}; since Texinfo is designed for use with @TeX{}, -@code{texi2roff} is not described here. @code{texi2roff} is not part of -the standard GNU distribution and is not maintained or up-to-date with -all the Texinfo features described in this manual.} +@code{texi2roff} program if you do not have @TeX{}; since Texinfo is +designed for use with @TeX{}, @code{texi2roff} is not described here. +@code{texi2roff} is not part of the standard GNU distribution.} A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, @@ -963,19 +893,18 @@ as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices.@refill You can use Texinfo to write a book without ever having the intention -of converting it into online information. You can use Texinfo for +of converting it into on-line information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier.@refill @TeX{} is a general purpose typesetting program. Texinfo provides a -file @file{texinfo.tex} that contains information (definitions or +file called @file{texinfo.tex} that contains information (definitions or @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands to @TeX{} commands, which @TeX{} can then process to create the typeset document.) @file{texinfo.tex} contains the specifications for printing -a document. You can get the latest version of @file{texinfo.tex} from -@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}. +a document.@refill Most often, documents are printed on 8.5 inch by 11 inch pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you @@ -995,7 +924,7 @@ light-hearted, young and cheery.@refill @TeX{} is freely distributable. It is written in a superset of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the @TeX{} distribution) in C. -(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information +(@xref{TeX Mode, ,@TeX{} Mode, xemacs, XEmacs User's Manual}, for information about @TeX{}.)@refill @TeX{} is very powerful and has a great many features. Because a @@ -1004,8 +933,7 @@ character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited.@refill -To get a copy of @TeX{}, see -@ref{Obtaining TeX, , How to Obtain @TeX{}}. +@xref{Obtaining TeX, , How to Obtain @TeX{}}. @node Formatting Commands, Conventions, Printed Books, Overview @@ -1035,17 +963,17 @@ numeric characters. Similarly, you can print the output generated by @TeX{} on a wide variety of printers.@refill Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does not -refer to a dispute between two people; it refers to the information -presented to the command. According to the @cite{Oxford English -Dictionary}, the word derives from the Latin for @dfn{to make clear, -prove}; thus it came to mean `the evidence offered as proof', which is -to say, `the information offered', which led to its mathematical -meaning. In its other thread of derivation, the word came to mean `to -assert in a manner against which others may make counter assertions', -which led to the meaning of `argument' as a dispute.} they take, you -need to write @@-commands on lines of their own or as part of -sentences: +@dfn{argument} comes from the way it is used in mathematics and does +not refer to a disputation between two people; it refers to the +information presented to the command. According to the @cite{Oxford +English Dictionary}, the word derives from the Latin for @dfn{to make +clear, prove}; thus it came to mean `the evidence offered as proof', +which is to say, `the information offered', which led to its +mathematical meaning. In its other thread of derivation, the word +came to mean `to assert in a manner against which others may make +counter assertions', which led to the meaning of `argument' as a +disputation.} they take, you need to write @@-commands on lines of +their own or as part of sentences:@refill @itemize @bullet @item @@ -1070,14 +998,12 @@ wish (but usually within a sentence) with its argument, marks text as being code.)@refill @item -Write a command such as @code{@@example} on a line of its own; write the -body-text on following lines; and write the matching @code{@@end} -command, @code{@@end example} in this case, at the on a line of its own -after the body-text. (@code{@@example} @dots{} @code{@@end example} -indents and typesets body-text as an example.) It's usually ok to -indent environment commands like this, but in complicated and -hard-to-define circumstances the extra spaces cause extra space to -appear in the output, so beware. +Write a command such as @code{@@example} at the beginning of a line of +its own; write the body-text on following lines; and write the matching +@code{@@end} command, @code{@@end example} in this case, at the +beginning of a line of its own after the body-text. (@code{@@example} +@dots{} @code{@@end example} indents and typesets body-text as an +example.)@refill @end itemize @noindent @@ -1100,10 +1026,6 @@ syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill @cindex Syntactic conventions @cindex Conventions, syntactic -This section describes the general conventions used in all Texinfo documents. - -@itemize @bullet -@item All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and @samp{@}} can appear in a Texinfo file and stand for themselves. @samp{@@} is the escape character which introduces commands. @@ -1112,7 +1034,6 @@ certain commands. To put one of these special characters into the document, put an @samp{@@} character in front of it, like this: @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill -@item @ifinfo It is customary in @TeX{} to use doubled single-quote characters to begin and end quotations: ` ` and ' ' (but without a space between the @@ -1123,26 +1044,23 @@ single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill @end ifinfo @iftex It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This +begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This convention should be followed in Texinfo files. @TeX{} converts doubled single-quote characters to left- and right-hand doubled quotation marks, ``like this'', and Info converts doubled single-quote -characters to @sc{ascii} double-quotes: @w{@t{ `` }} and -@w{@t{ '' }} to @w{@t{ " }}.@refill +characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and +@w{@tt{ '' }} to @w{@tt{ " }}.@refill @end iftex -@item Use three hyphens in a row, @samp{---}, for a dash---like this. In @TeX{}, a single or double hyphen produces a printed dash that is shorter than the usual typeset dash. Info reduces three hyphens to two for display on the screen. -@item To prevent a paragraph from being indented in the printed manual, put the command @code{@@noindent} on a line by itself before the paragraph.@refill -@item If you mark off a region of the Texinfo file with the @code{@@iftex} and @w{@code{@@end iftex}} commands, that region will appear only in the printed copy; in that region, you can use certain commands @@ -1153,9 +1071,8 @@ region, you can use Info commands that you cannot use in @TeX{}. Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, @code{@@ifnothtml @dots{} @@end ifnothtml}, @code{@@ifnotinfo @dots{} @@end ifnotinfo}, -@code{@@ifnottex @dots{} @@end ifnottex}. +@code{@@ifnottex @dots{} @@end ifnottex}, @xref{Conditionals}. -@end itemize @cindex Tabs; don't use! @quotation @@ -1173,6 +1090,9 @@ spaces when you press the @key{TAB} key.@refill @noindent Also, you can run @code{untabify} in Emacs to convert tabs in a region to multiple spaces.@refill + +@noindent +Don't use tabs. @end quotation @node Comments, Minimum, Conventions, Overview @@ -1182,7 +1102,7 @@ to multiple spaces.@refill You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the @code{@@comment} command (which may be abbreviated to @code{@@c}). -Such comments are for the person who revises the Texinfo file. All the +Such comments are for the person who reads the Texinfo file. All the text on a line that follows either @code{@@comment} or @code{@@c} is a comment; the rest of the line does not appear in either the Info file or the printed manual. (Often, you can write the @code{@@comment} or @@ -1228,9 +1148,9 @@ within ignored text. @cindex Texinfo file minimum By convention, the names of Texinfo files end with one of the -extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. -The longer extension is preferred since it describes more clearly to a -human reader the nature of the file. The shorter extensions are for +extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer +extension is preferred since it describes more clearly to a human +reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names.@refill In order to be made into a printed manual and an Info file, a Texinfo @@ -1332,7 +1252,8 @@ the table of contents, and the @code{@@bye} command on a line of its own.@refill @end table -@node Short Sample +@node Short Sample, Acknowledgements, Six Parts, Overview +@comment node-name, next, previous, up @section A Short Sample Texinfo File @cindex Sample Texinfo file @@ -1343,6 +1264,7 @@ the material is standard boilerplate; when you write a manual, simply insert the names for your own manual in this segment. (@xref{Beginning a File}.)@refill +@noindent In the following, the sample text is @emph{indented}; comments on it are not. The complete file, without any comments, is shown in @ref{Sample Texinfo File}. @@ -1360,8 +1282,9 @@ name of the Info file and the title used in the header. @@c %**start of header @@setfilename sample.info @@settitle Sample Document -@@setchapternewpage odd @@c %**end of header + +@@setchapternewpage odd @end group @end example @@ -1470,14 +1393,15 @@ manual. @subheading Part 6: The End of the Document @noindent -The end segment contains commands for generating an index in a node and -unnumbered chapter of its own, (usually) for generating the table of -contents, and the @code{@@bye} command that marks the end of the -document.@refill +The end segment contains commands both for generating an index in a node +and unnumbered chapter of its own and for generating the table of +contents; and it contains the @code{@@bye} command that marks the end of +the document.@refill @example @group @@node Concept Index, , First Chapter, Top +@@comment node-name, next, previous, up @@unnumbered Concept Index @end group @@ -1514,61 +1438,41 @@ an Info file; and @TeX{} typesets it for a printed manual. @end quotation - -@node Acknowledgements and History -@section Acknowledgements and History +@node Acknowledgements, , Short Sample, Overview +@comment node-name, next, previous, up +@section Acknowledgements @cindex Stallman, Richard M. @cindex Chassell, Robert J. @cindex Berry, Karl -Richard M.@: Stallman invented the Texinfo format, wrote the initial -processors, and created Edition 1.0 of this manual. @w{Robert J.@: -Chassell} greatly revised and extended the manual, starting with Edition -1.1. Brian Fox was responsible for the standalone Texinfo distribution -until version 3.8, and wrote the standalone @command{makeinfo} and -@command{info}. Karl Berry has made the updates since Texinfo 3.8 and -subsequent releases, starting with Edition 2.22 of the manual. +Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@: +Chassell} revised and extended it, starting with Edition 1.1. Karl +Berry made updates for the Texinfo 3.8 and subsequent releases, starting +with Edition 2.22. @cindex Pinard, Fran@,{c}ois @cindex Zuhn, David D. @cindex Weisshaus, Melissa -@cindex Zaretskii, Eli -@cindex Schwab, Andreas -@cindex Weinberg, Zack Our thanks go out to all who helped improve this work, particularly to Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and reported mistakes and obscurities; our special thanks go to Melissa Weisshaus for her frequent and often tedious reviews of nearly similar -editions. The indefatigable Eli Zaretskii and Andreas Schwab have -provided patches beyond counting. Zack Weinberg did the impossible by -implementing the macro syntax in @file{texinfo.tex}. Dozens of others -have contributed patches and suggestions, they are gratefully -acknowledged in the @file{ChangeLog} file. Our mistakes are our own. - -@cindex Scribe -@cindex Reid, Brian -@cindex History of Texinfo -A bit of history: in the 1970's at CMU, Brian Reid developed a program -and format named Scribe to mark up documents for printing. It used the -@code{@@} character to introduce commands as Texinfo does and strived to -describe document contents rather than formatting. - -@cindex Bolio -@cindex Bo@TeX{} -Meanwhile, people at MIT developed another, not too dissimilar format -called Bolio. This then was converted to using @TeX{} as its typesetting -language: Bo@TeX{}. - -Bo@TeX{} could only be used as a markup language for documents to be -printed, not for online documents. Richard Stallman (RMS) worked on -both Bolio and Bo@TeX{}. He also developed a nifty on-line help format -called Info, and then combined Bo@TeX{} and Info to create Texinfo, a -mark up language for text that is intended to be read both on line and -as printed hard copy. - - - -@node Texinfo Mode +editions. Our mistakes are our own. + +Please send suggestions and corrections to: + +@example +@group +@r{Internet address:} + bug-texinfo@@gnu.org +@end group +@end example + +@noindent +Please include the manual's edition number and update date in your messages. + +@node Texinfo Mode, Beginning a File, Overview, Top +@comment node-name, next, previous, up @chapter Using Texinfo Mode @cindex Texinfo mode @cindex Mode, using Texinfo @@ -1605,8 +1509,7 @@ detail.@refill @end ifinfo Texinfo mode provides special features for working with Texinfo -files. -You can:@refill +files:@refill @itemize @bullet @item @@ -1658,16 +1561,16 @@ equivalents, such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) commands and narrow to a chapter with the -@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, -The GNU Emacs Manual}, for details about the page commands.)@refill +@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , , xemacs, +XEmacs User's Manual}, for details about the page commands.)@refill You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the extensions -@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer -extension is preferred, since it is explicit, but a shorter extension -may be necessary for operating systems that limit the length of file -names. GNU Emacs automatically enters Texinfo mode when you visit a -file with a @file{.texinfo}, @file{.texi} or @file{.txi} +end a Texinfo file name with one of the three extensions +@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is +preferred, since it is explicit, but a shorter extension may be +necessary for operating systems that limit the length of file names. +GNU Emacs automatically enters Texinfo mode when you visit a file with +a @file{.texinfo} or @file{.texi} extension. Also, Emacs switches to Texinfo mode when you visit a file that has @samp{-*-texinfo-*-} in its first line. If ever you are @@ -1859,10 +1762,14 @@ cursor in the @file{*Occur*} buffer.@refill If you call @code{texinfo-show-structure} with a prefix argument by typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the -@@-commands for @code{@@chapter}, @code{@@section}, and the like, but -also the @code{@@node} lines. You can use @code{texinfo-show-structure} -with a prefix argument to check whether the `Next', `Previous', and `Up' -pointers of an @code{@@node} line are correct. +@@-commands for @code{@@chapter}, @code{@@section}, and the like, +but also the @code{@@node} lines. (This is how the +@code{texinfo-show-structure} command worked without an argument in +the first version of Texinfo. It was changed because @code{@@node} +lines clutter up the @samp{*Occur*} buffer and are usually not +needed.) You can use @code{texinfo-show-structure} with a prefix +argument to check whether the `Next', `Previous', and `Up' pointers of +an @code{@@node} line are correct.@refill Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark @@ -1870,7 +1777,7 @@ off the region of the buffer that you are interested in by using the @kbd{C-x n n} (@code{narrow-to-region}) command and @code{texinfo-show-structure} will work on only that region. To see the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). -(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more +(@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more information about the narrowing commands.)@refill @vindex page-delimiter @@ -1881,7 +1788,7 @@ the chapter-level @@-commands. This enables you to use the @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) commands to move forward and backward by chapter, and to use the @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter. -@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information +@xref{Pages, , , xemacs, XEmacs User's Manual}, for more information about the page commands.@refill @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode @@ -1916,18 +1823,18 @@ node pointers by hand, which is a tedious task.@refill @subheading The Updating Commands @end ifinfo -You can use the updating commands to:@refill +You can use the updating commands@refill @itemize @bullet @item -insert or update the `Next', `Previous', and `Up' pointers of a +to insert or update the `Next', `Previous', and `Up' pointers of a node,@refill @item -insert or update the menu for a section, and@refill +to insert or update the menu for a section, and@refill @item -create a master menu for a Texinfo source file.@refill +to create a master menu for a Texinfo source file.@refill @end itemize You can also use the commands to update all the nodes and menus in a @@ -1949,11 +1856,11 @@ interpose only an @code{@@comment} line or an @code{@@ifinfo} line. Commands which work on a whole buffer require that the `Top' node be followed by a node with an @code{@@chapter} or equivalent-level command. -The menu updating commands will not create a main or master menu for a -Texinfo file that has only @code{@@chapter}-level nodes! The menu -updating commands only create menus @emph{within} nodes for lower level +Note that the menu updating commands will not create a main or master +menu for a Texinfo file that has only @code{@@chapter}-level nodes! The +menu updating commands only create menus @emph{within} nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' -node. +node.@refill The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This @@ -1999,7 +1906,7 @@ This updates all the nodes and menus completely and all at once.@refill @end table The other major updating commands do smaller jobs and are designed for -the person who updates nodes and menus as he or she writes a Texinfo +the person who updates nodes and menus as he or she writes a Texinfo file.@refill @need 1000 @@ -2068,10 +1975,9 @@ The @code{texinfo-column-for-description} variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it is often useful to reduce it to as low as 24. You can set the variable with the @kbd{M-x edit-options} command -(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs -Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, -, Examining and Setting Variables, emacs, The GNU Emacs -Manual}).@refill +(@pxref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's +Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, , +Examining and Setting Variables, xemacs, XEmacs User's Manual}).@refill Also, the @code{texinfo-indent-menu-description} command may be used to indent existing menu descriptions to a specified column. Finally, if @@ -2124,7 +2030,7 @@ In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an -@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill +@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill If a file has a `Top' node, it must be called @samp{top} or @samp{Top} and be the first node in the file.@refill @@ -2133,14 +2039,14 @@ The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a `Top' node if you want a menu of chapters.@refill -Incidentally, the @code{makeinfo} command will create an Info file for a -hierarchically organized Texinfo file that lacks `Next', `Previous' and -`Up' pointers. Thus, if you can be sure that your Texinfo file will be -formatted with @code{makeinfo}, you have no need for the update node -commands. (@xref{Creating an Info File}, for more information about -@code{makeinfo}.) However, both @code{makeinfo} and the -@code{texinfo-format-@dots{}} commands require that you insert menus in -the file. +Incidentally, the @code{makeinfo} command will create an Info file for +a hierarchically organized Texinfo file that lacks `Next', `Previous' +and `Up' pointers. Thus, if you can be sure that your Texinfo file +will be formatted with @code{makeinfo}, you have no need for the +`update node' commands. (@xref{Create an Info File, , Creating an +Info File}, for more information about @code{makeinfo}.) However, +both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands +require that you insert menus in the file.@refill @node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus @comment node-name, next, previous, up @@ -2171,11 +2077,11 @@ For example, the following marks a whole buffer as a region and inserts C-x h C-u M-x texinfo-insert-node-lines @end example -This command inserts titles as node names in @code{@@node} lines; the -@code{texinfo-start-menu-description} command (@pxref{Inserting, -Inserting Frequently Used Commands}) inserts titles as descriptions in -menu entries, a different action. However, in both cases, you need to -edit the inserted text. +(Note that this command inserts titles as node names in @code{@@node} +lines; the @code{texinfo-start-menu-description} command +(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles +as descriptions in menu entries, a different action. However, in both +cases, you need to edit the inserted text.)@refill @item M-x texinfo-multiple-files-update @findex texinfo-multiple-files-update @r{(in brief)} @@ -2275,7 +2181,7 @@ M-x makeinfo-buffer For @TeX{} or the Info formatting commands to work, the file @emph{must} include a line that has @code{@@setfilename} in its header.@refill -@xref{Creating an Info File}, for details about Info formatting.@refill +@xref{Create an Info File}, for details about Info formatting.@refill @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode @comment node-name, next, previous, up @@ -2338,7 +2244,7 @@ on a line by itself. (When you use @code{texinfo-tex-region}, you must surround the @code{@@settitle} line with start-of-header and end-of-header lines.)@refill -@xref{Hardcopy}, for a description of the other @TeX{} related +@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related commands, such as @code{tex-show-print-queue}.@refill @node Texinfo Mode Summary, , Printing, Texinfo Mode @@ -2390,7 +2296,6 @@ C-c C-s @r{List all the headings.} The @code{texinfo-master-menu} command creates a master menu; and can be used to update every node and menu in a file as well.@refill -@c Probably should use @tables in this section. @example @group C-c C-u m @@ -2492,7 +2397,7 @@ C-c C-t C-l @r{Recenter the output buffer.} @subheading Other Updating Commands -The remaining updating commands do not have standard keybindings because +The `other updating commands' do not have standard keybindings because they are rarely used. @example @@ -2703,13 +2608,12 @@ or else like this: * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* exampleindent:: Specify environment indentation. +* paragraphindent:: An option to specify paragraph indentation. * End of Header:: Formatting a region requires this. @end menu - -@node First Line +@node First Line, Start of Header, Header, Header +@comment node-name, next, previous, up @subsection The First Line of a Texinfo File @cindex First line of a Texinfo file @cindex Beginning line of a Texinfo file @@ -2764,7 +2668,8 @@ A start-of-header line looks like this:@refill The odd string of characters, @samp{%**}, is to ensure that no other comment is accidentally taken for a start-of-header line.@refill -@node setfilename +@node setfilename, settitle, Start of Header, Header +@comment node-name, next, previous, up @subsection @code{@@setfilename} @cindex Info file requires @code{@@setfilename} @findex setfilename @@ -2782,13 +2687,11 @@ else on the line; anything on the line after the command is considered part of the file name, including what would otherwise be a comment. -The @code{@@setfilename} line specifies the name of the output file to -be generated. This name should be different from the name of the -Texinfo file. There are two conventions for choosing the name: you can -either remove the extension (such as @samp{.texi}) from the input file -name, or replace it with the @samp{.info} extension. When producing -HTML output, @code{makeinfo} will replace any extension with -@samp{html}, or add @samp{.html} if the given name has no extension. +The @code{@@setfilename} line specifies the name of the Info file to be +generated. This name should be different from the name of the Texinfo +file. There are two conventions for choosing the name: you can either +remove the @samp{.texi} extension from the input file name, or replace +it with the @samp{.info} extension. Some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. @@ -2798,24 +2701,19 @@ short indirect subfiles, and name them by appending @samp{-1}, file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.) The subfile name @file{texinfo.info-10}, for example, is too long for some systems; so the Info file name for this document is @file{texinfo} -rather than @file{texinfo.info}. When @code{makeinfo} is running on -operating systems such as MS-DOS which impose grave limits on file -names, it will sometimes remove some characters from the original file -name to leave enough space for the subfile suffix, thus producing files -named @file{texin-10}, @file{gcc.i12}, etc. +rather than @file{texinfo.info}. @cindex Ignored before @code{@@setfilename} -@cindex @samp{\input} source line ignored The Info formatting commands ignore everything written before the @code{@@setfilename} line, which is why the very first line of the file (the @code{\input} line) does not show up in the output. @pindex texinfo.cnf The @code{@@setfilename} line produces no output when you typeset a -manual with @TeX{}, but it is nevertheless essential: it opens the +manual with @TeX{}, but it nevertheless is essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads @file{texinfo.cnf} if that file is present on your system -(@pxref{Preparing for TeX,, Preparing for @TeX{}}). +(@pxref{Preparing for TeX,, Preparing to Use @TeX{}}). @node settitle, setchapternewpage, setfilename, Header @@ -2867,15 +2765,15 @@ You may, if you wish, create your own, customized headings and footings. @xref{Headings, , Page Headings}, for a detailed discussion of this process.@refill - -@node setchapternewpage +@node setchapternewpage, paragraphindent, settitle, Header +@comment node-name, next, previous, up @subsection @code{@@setchapternewpage} @cindex Starting chapters @cindex Pages, starting odd @findex setchapternewpage -In an officially bound book, text is usually printed on both sides of -the paper, chapters start on right-hand pages, and right-hand pages have +In a book or a manual, text is usually printed on both sides of the +paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the @@ -2883,7 +2781,7 @@ preceding chapter, after a small amount of vertical whitespace.@refill You can use the @code{@@setchapternewpage} command with various arguments to specify how @TeX{} should start chapters and whether it -should format headers for printing on one or both sides of the paper +should typeset pages for printing on one or both sides of the paper (single-sided or double-sided printing).@refill Write the @code{@@setchapternewpage} command at the beginning of a @@ -2900,7 +2798,17 @@ You can specify one of three alternatives with the @code{@@setchapternewpage} command:@refill @table @asis +@ignore +@item No @code{@@setchapternewpage} command +If the Texinfo file does not contain an @code{@@setchapternewpage} +command before the @code{@@titlepage} command, @TeX{} automatically +begins chapters on new pages and prints headings in the standard +format for single-sided printing. This is the conventional format for +single-sided printing.@refill +The result is exactly the same as when you write +@code{@@setchapternewpage on}.@refill +@end ignore @item @code{@@setchapternewpage off} Cause @TeX{} to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause @TeX{} to @@ -2909,9 +2817,9 @@ headers format with the @code{@@headings double} command; see @ref{headings on off, , The @code{@@headings} Command}.)@refill @item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to format page +Cause @TeX{} to start new chapters on new pages and to typeset page headers for single-sided printing. This is the form most often -used for short reports or personal printing. +used for short reports.@refill This alternative is the default.@refill @@ -2921,11 +2829,13 @@ Cause @TeX{} to start new chapters on new, odd-numbered pages the form most often used for books and manuals.@refill @end table +@noindent Texinfo does not have an @code{@@setchapternewpage even} command.@refill -You can countermand or modify the effect on headers of an -@code{@@setchapternewpage} command with an @code{@@headings} command. -@xref{headings on off, , The @code{@@headings} Command}.@refill +@noindent +(You can countermand or modify an @code{@@setchapternewpage} command +with an @code{@@headings} command. @xref{headings on off, , The +@code{@@headings} Command}.)@refill At the beginning of a manual or book, pages are not numbered---for example, the title and copyright pages of a book are not numbered. @@ -2935,100 +2845,62 @@ numerals and not in sequence with the rest of the document.@refill Since an Info file does not have pages, the @code{@@setchapternewpage} command has no effect on it.@refill -We recommend not including any @code{@@setchapternewpage} command in -your manual sources at all, since the desired output is not intrinsic to -the document. Instead, if you don't want the default option (no blank -pages, same headers on all pages) use the @option{--texinfo} option to -@command{texi2dvi} to specify the output you want. +Usually, you do not write an @code{@@setchapternewpage} command for +single-sided printing, but accept the default which is to typeset for +single-sided printing and to start new chapters on new pages. Usually, +you write an @code{@@setchapternewpage odd} command for double-sided +printing.@refill - - -@node paragraphindent +@node paragraphindent, End of Header, setchapternewpage, Header +@comment node-name, next, previous, up @subsection Paragraph Indenting @cindex Indenting paragraphs @cindex Paragraph indentation @findex paragraphindent -The Texinfo processors may insert whitespace at the beginning of the -first line of each paragraph, thereby indenting that paragraph. You can -use the @code{@@paragraphindent} command to specify this indentation. -Write an @code{@@paragraphindent} command at the beginning of a line -followed by either @samp{asis} or a number: +The Info formatting commands may insert spaces at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You +can use the @code{@@paragraphindent} command to specify the +indentation. Write an @code{@@paragraphindent} command at the +beginning of a line followed by either @samp{asis} or a number. The +template is:@refill @example @@paragraphindent @var{indent} @end example -The indentation is according to the value of @var{indent}: - -@table @asis -@item @code{asis} -Do not change the existing indentation (not implemented in @TeX{}). +The Info formatting commands indent according to the value of +@var{indent}:@refill -@item 0 -Omit all indentation. +@itemize @bullet +@item +If the value of @var{indent} is @samp{asis}, the Info formatting +commands do not change the existing indentation.@refill -@item @var{n} -Indent by @var{n} space characters in Info output, by @var{n} ems in -@TeX{}. +@item +If the value of @var{indent} is zero, the Info formatting commands delete +existing indentation.@refill -@end table +@item +If the value of @var{indent} is greater than zero, the Info formatting +commands indent the paragraph by that number of spaces.@refill +@end itemize -The default value of @var{indent} is @samp{asis}. -@code{@@paragraphindent} is ignored for HTML output. +The default value of @var{indent} is @samp{asis}.@refill Write the @code{@@paragraphindent} command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the -region formatting commands indent paragraphs as specified.) +region formatting commands indent paragraphs as specified.)@refill A peculiarity of the @code{texinfo-format-buffer} and @code{texinfo-format-region} commands is that they do not indent (nor fill) paragraphs that contain @code{@@w} or @code{@@*} commands. -@xref{Refilling Paragraphs}, for further information. - - -@node exampleindent -@subsection @code{@@exampleindent}: Environment Indenting -@cindex Indenting environments -@cindex Environment indentation -@cindex Example indentation -@findex exampleindent - -The Texinfo processors indent each line of @code{@@example} and similar -environments. You can use the @code{@@exampleindent} command to specify -this indentation. Write an @code{@@exampleindent} command at the -beginning of a line followed by either @samp{asis} or a number: - -@example -@@exampleindent @var{indent} -@end example - -The indentation is according to the value of @var{indent}: - -@table @asis -@item @code{asis} -Do not change the existing indentation (not implemented in @TeX{}). - -@item 0 -Omit all indentation. - -@item @var{n} -Indent environments by @var{n} space characters in Info output, by -@var{n} ems in @TeX{}. - -@end table - -The default value of @var{indent} is 5. @code{@@exampleindent} is -ignored for HTML output. - -Write the @code{@@exampleindent} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you write -the command between the start-of-header and end-of-header lines, the -region formatting commands indent examples as specified.) - +@xref{Refilling Paragraphs}, for a detailed description of what goes +on.@refill -@node End of Header +@node End of Header, , paragraphindent, Header +@comment node-name, next, previous, up @subsection End of Header @cindex End of header line @@ -3058,8 +2930,8 @@ variables that you can change.@refill @xref{Start of Header}. @end iftex - -@node Info Summary and Permissions +@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File +@comment node-name, next, previous, up @section Summary and Copying Permissions for Info The title page and the copyright page appear only in the printed copy of @@ -3086,8 +2958,8 @@ node. This mean that a reader does @emph{not} see this text when reading the file using Info, except when using the advanced Info command @kbd{g *}. - -@node Titlepage & Copyright Page +@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File +@comment node-name, next, previous, up @section The Title and Copyright Pages A manual's name and author are usually printed on a title page. @@ -3101,12 +2973,6 @@ obscure @TeX{} typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.@refill -@cindex Titlepage, for plain text -You may wish to include titlepage-like information for plain text -output. Simply place any such leading material between @code{@@ifinfo} -and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain -text output. It will not show up in the Info readers. - @xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the standard text for the copyright permissions.@refill @@ -3124,7 +2990,6 @@ standard text for the copyright permissions.@refill and double or single sided printing. @end menu - @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page @comment node-name, next, previous, up @subsection @code{@@titlepage} @@ -3137,57 +3002,53 @@ with @code{@@titlepage} on a line by itself and end it with The @code{@@end titlepage} command starts a new page and turns on page numbering. (@xref{Headings, , Page Headings}, for details about how to -generate page headings.) All the material that you want to appear on -unnumbered pages should be put between the @code{@@titlepage} and -@code{@@end titlepage} commands. You can force the table of contents to -appear there with the @code{@@setcontentsaftertitlepage} command -(@pxref{Contents}). - -@findex page@r{, within @code{@@titlepage}} -By using the @code{@@page} command you can force a page break within the -region delineated by the @code{@@titlepage} and @code{@@end titlepage} -commands and thereby create more than one unnumbered page. This is how -the copyright page is produced. (The @code{@@titlepage} command might -perhaps have been better named the @code{@@titleandadditionalpages} -command, but that would have been rather long!) - +generate page headings.) All the material that you want to +appear on unnumbered pages should be put between the +@code{@@titlepage} and @code{@@end titlepage} commands. By using the +@code{@@page} command you can force a page break within the region +delineated by the @code{@@titlepage} and @code{@@end titlepage} +commands and thereby create more than one unnumbered page. This is +how the copyright page is produced. (The @code{@@titlepage} command +might perhaps have been better named the +@code{@@titleandadditionalpages} command, but that would have been +rather long!)@refill + +@c !!! append refill to footnote when makeinfo can handle it. When you write a manual about a computer program, you should write the -version of the program to which the manual applies on the title page. -If the manual changes more frequently than the program or is independent -of it, you should also include an edition number@footnote{We have found -that it is helpful to refer to versions of manuals as `editions' and -versions of programs as `versions'; otherwise, we find we are liable to -confuse each other in conversation by referring to both the -documentation and the software with the same words.} for the manual. -This helps readers keep track of which manual is for which version of -the program. (The `Top' node should also contain this information; see -@ref{makeinfo top, , @code{@@top}}.) +version of the program to which the manual applies on the title +page. If the manual changes more frequently than the program or is +independent of it, you should also include an edition +number@footnote{We have found that it is helpful to refer to versions +of manuals as `editions' and versions of programs as `versions'; +otherwise, we find we are liable to confuse each other in conversation +by referring to both the documentation and the software with the same +words.} for the manual. This helps readers keep track of which manual +is for which version of the program. (The `Top' node +should also contain this information; see @ref{makeinfo top, , +@code{@@top}}.)@refill Texinfo provides two main methods for creating a title page. One method uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands to generate a title page in which the words on the page are -centered. +centered.@refill The second method uses the @code{@@title}, @code{@@subtitle}, and @code{@@author} commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text -you want, and Texinfo does the formatting. - -You may use either method, or you may combine them; see the examples in -the sections below. +you want, and Texinfo does the formatting. You may use either +method.@refill @findex shorttitlepage -@cindex Bastard title page -@cindex Title page, bastard -For extremely simple applications, and for the bastard title page in -traditional book front matter, Texinfo also provides a command -@code{@@shorttitlepage} which takes a single argument as the title. The -argument is typeset on a page by itself and followed by a blank page. +For extremely simple applications, Texinfo also provides a command +@code{@@shorttitlepage} which takes a single argument as the title. +The argument is typeset on a page by itself and followed by a blank +page. -@node titlefont center sp +@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page +@comment node-name, next, previous, up @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} @findex titlefont @findex center @@ -3198,8 +3059,7 @@ commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.)@refill Use the @code{@@titlefont} command to select a large font suitable for -the title itself. You can use @code{@@titlefont} more than once if you -have an especially long title. +the title itself.@refill @need 700 For example: @@ -3246,10 +3106,10 @@ A template for this method looks like this:@refill @end group @end example -The spacing of the example fits an 8.5 by 11 inch manual.@refill +The spacing of the example fits an 8 1/2 by 11 inch manual.@refill - -@node title subtitle author +@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page +@comment node-name, next, previous, up @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} @findex title @findex subtitle @@ -3258,8 +3118,9 @@ The spacing of the example fits an 8.5 by 11 inch manual.@refill You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method -described in the previous section, in which the @code{@@sp} command is -needed to adjust vertical spacing. +described in +the previous section, in which the @code{@@sp} command is needed to +adjust vertical spacing.@refill Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} commands at the beginning of a line followed by the title, subtitle, @@ -3267,11 +3128,7 @@ or author.@refill The @code{@@title} command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. -The title is underlined with a black rule. Only a single line is -allowed; the @code{@@*} command may not be used to break the title into -two lines. To handle very long titles, you may find it profitable to -use both @code{@@title} and @code{@@titlefont}; see the final example in -this section. +The title is underlined with a black rule.@refill The @code{@@subtitle} command sets subtitles in a normal-sized font flush to the right-hand side of the page.@refill @@ -3321,28 +3178,29 @@ A template for this method looks like this:@refill @end group @end example -You may also combine the @code{@@titlefont} method described in the -previous section and @code{@@title} method described in this one. This -may be useful if you have a very long title. Here is a real-life example: +@ifinfo +@noindent +Contrast this form with the form of a title page written using the +@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill @example -@group @@titlepage -@@titlefont@{GNU Software@} +@@sp 10 +@@center @@titlefont@{Name of Manual When Printed@} +@@sp 2 +@@center Subtitle, If Any @@sp 1 -@@title for MS-Windows and MS-DOS -@@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@} -@@author by Daniel Hagerty, Melissa Weisshaus -@@author and Eli Zaretskii -@end group +@@center Second subtitle +@@sp 2 +@@center Author +@@page +@dots{} +@@end titlepage @end example +@end ifinfo -@noindent -(The use of @code{@@value} here is explained in @ref{value -Example,,@code{@@value} Example}.) - - -@node Copyright & Permissions +@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page +@comment node-name, next, previous, up @subsection Copyright Page and Permissions @cindex Copyright page @cindex Printed permissions @@ -3389,17 +3247,19 @@ Copyright @copyright{} @var{year} @var{copyright-owner} @end example It is customary to put information on how to get a manual after the -copyright notice, followed by the copying permissions for the manual. +copyright notice, followed by the copying permissions for the +manual.@refill -Permissions must be given here as well as in the summary segment within -@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the -header since this text appears only in the printed manual and the -@samp{ifinfo} text appears only in the Info file. +Note that permissions must be given here as well as in the summary +segment within @code{@@ifinfo} and @code{@@end ifinfo} that +immediately follows the header since this text appears only in the +printed manual and the @samp{ifinfo} text appears only in the Info +file.@refill @xref{Sample Permissions}, for the standard text.@refill - -@node end titlepage +@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page +@comment node-name, next, previous, up @subsection Heading Generation @findex end titlepage @cindex Headings, page, begin to appear @@ -3466,7 +3326,6 @@ Turn on page headings appropriate for single-sided printing. @refill @item @@headings double -@itemx @@headings on Turn on page headings appropriate for double-sided printing. The two commands, @code{@@headings on} and @code{@@headings double}, are synonymous.@refill @@ -3505,8 +3364,8 @@ headings.@refill You can also specify your own style of page heading and footing. @xref{Headings, , Page Headings}, for more information.@refill - -@node The Top Node +@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File +@comment node-name, next, previous, up @section The `Top' Node and Master Menu @cindex @samp{@r{Top}} node @cindex Master menu @@ -3533,9 +3392,10 @@ strictly speaking, you are not required to enclose these parts between * Master Menu Parts:: A master menu has three or more parts. @end menu - -@node Title of Top Node -@subsection `Top' Node Title +@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node +@ifinfo +@subheading `Top' Node Title +@end ifinfo Sometimes, you will want to place an @code{@@top} sectioning command line containing the title of the document immediately after the @@ -3551,7 +3411,7 @@ version information. It looks like this:@refill @dots{} @@end titlepage -@@ifnottex +@@ifinfo @@node Top, Copying, , (dir) @@top Texinfo @@ -3561,7 +3421,7 @@ Texinfo is a documentation system@dots{} @group This is edition@dots{} @dots{} -@@end ifnottex +@@end ifinfo @end group @group @@ -3698,10 +3558,10 @@ Usually, an introduction is put in an @code{@@unnumbered} section. @cindex File ending @findex bye -The end of a Texinfo file should include commands to create indices and -(usually) to generate detailed and summary tables of contents. And it -must include the @code{@@bye} command that marks the last line processed -by @TeX{}.@refill +The end of a Texinfo file should include the commands that create +indices and generate detailed and summary tables of contents. +And it must include the @code{@@bye} command that marks the last line +processed by @TeX{}.@refill @need 700 For example: @@ -3741,7 +3601,7 @@ accumulated. To generate an index, you must include the @code{@@printindex} command at the place in the document where you want the index to appear. Also, as part of the process of creating a printed manual, you must run a program called @code{texindex} -(@pxref{Hardcopy}) to sort the raw data to produce a sorted +(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted index file. The sorted index file is what is actually used to print the index.@refill @@ -3801,35 +3661,52 @@ For example: @@printindex cp @end group + +@group +@@summarycontents +@@contents +@@bye +@end group @end smallexample @noindent -Readers often prefer that the concept index come last in a book, -since that makes it easiest to find. Having just one index helps -readers also, since then they have only one place to look -(@pxref{synindex}). +(Readers often prefer that the concept index come last in a book, +since that makes it easiest to find.)@refill +@ignore +@c TeX can do sorting, just not conveniently enough to handle sorting +@c Texinfo indexes. --karl, 5may97. +In @TeX{}, the @code{@@printindex} command needs a sorted index file +to work from. @TeX{} does not know how to do sorting; this is a +deficiency. @TeX{} writes output files of raw index data; use the +@code{texindex} program to convert these files to sorted index files. +(@xref{Format/Print Hardcopy}, for more information.)@refill +@end ignore -@node Contents + +@node Contents, File End, Printing Indices & Menus, Ending a File +@comment node-name, next, previous, up @section Generating a Table of Contents @cindex Table of contents @cindex Contents, Table of -@cindex Short table of contents @findex contents @findex summarycontents @findex shortcontents The @code{@@chapter}, @code{@@section}, and other structuring commands supply the information to make up a table of contents, but they do not -cause an actual table to appear in the manual. To do this, you must use -the @code{@@contents} and/or @code{@@summarycontents} command(s). +cause an actual table to appear in the manual. To do this, you must +use the @code{@@contents} and @code{@@summarycontents} +commands:@refill @table @code @item @@contents Generate a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. (Headings generated by the @code{@@heading} -series of commands do not appear in the table of contents.) +series of commands do not appear in the table of contents.) The +@code{@@contents} command should be written on a line by +itself.@refill @item @@shortcontents @itemx @@summarycontents @@ -3841,55 +3718,42 @@ chapters (and appendices and unnumbered chapters). Omit sections, subsections and subsubsections. Only a long manual needs a short table of contents in addition to the full table of contents.@refill +Write the @code{@@shortcontents} command on a line by itself right +@emph{before} the @code{@@contents} command.@refill @end table -Both contents commands should be written on a line by themselves. -The contents commands automatically generate a chapter-like heading at -the top of the first table of contents page, so don't include any -sectioning command such as @code{@@unnumbered} before them. +The table of contents commands automatically generate a chapter-like +heading at the top of the first table of contents page. Write the table +of contents commands at the very end of a Texinfo file, just before the +@code{@@bye} command, following any index sections---anything in the +Texinfo file after the table of contents commands will be omitted from +the table of contents.@refill + +When you print a manual with a table of contents, the table of +contents are printed last and numbered with roman numerals. You need +to place those pages in their proper place, after the title page, +yourself. (This is the only collating you need to do for a printed +manual. The table of contents is printed last because it is generated +after the rest of the manual is typeset.)@refill + +@need 700 +Here is an example of where to write table of contents commands:@refill + +@example +@group +@var{indices}@dots{} +@@shortcontents +@@contents +@@bye +@end group +@end example Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the contents commands. But the contents are -included in plain text output (generated by @code{makeinfo --no-headers}). - -The contents commands can be placed either at the very end of the file, -after any indices (see the previous section) and just before the -@code{@@bye} (see the next section), or near the beginning of the file, -after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to -the former is that then the contents output is always up to date, -because it reflects the processing just done. The advantage to the -latter is that the contents are printed in the proper place, thus you do -not need to rearrange the DVI file with @command{dviselect} or shuffle -paper. However, contents commands at the beginning of the document are -ignored when outputting to standard output. - -@findex setcontentsaftertitlepage -@findex setshortcontentsaftertitlepage -@cindex Contents, after title page -@cindex Table of contents, after title page -As an author, you can put the contents commands wherever you prefer. -But if you are a user simply printing a manual, you may wish to print -the contents after the title page even if the author put the contents -commands at the end of the document (as is the case in most existing -Texinfo documents). You can do this by specifying -@code{@@setcontentsaftertitlepage} and/or -@code{@@setshortcontentsaftertitlepage}. The first prints only the main -contents after the @code{@@end titlepage}; the second prints both the -short contents and the main contents. In either case, any subsequent -@code{@@contents} or @code{@@shortcontents} is ignored (unless no -@code{@@end titlepage} is ever encountered). - -You need to include the @code{@@set@dots{}contentsaftertitlepage} -commands early in the document (just after @code{@@setfilename}, for -example). Or, if you're using @command{texi2dvi} (@pxref{Format with -texi2dvi}), you can use its @option{--texinfo} option to specify this -without altering the source file at all. For example: -@example -texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi -@end example - - -@node File End +formatting commands ignore the @code{@@contents} and +@code{@@shortcontents} commands.@refill + +@node File End, , Contents, Ending a File +@comment node-name, next, previous, up @section @code{@@bye} File Ending @findex bye @@ -3904,8 +3768,8 @@ manual; it is as if text after @code{@@bye} were within @code{@@ignore} with a local variables list. @xref{Compile-Command, , Using Local Variables and the Compile Command}, for more information.@refill - -@node Structuring +@node Structuring, Nodes, Ending a File, Top +@comment node-name, next, previous, up @chapter Chapter Structuring @cindex Chapter structuring @cindex Structuring of chapters @@ -3944,8 +3808,8 @@ heading at the top of each node---but you don't need to.@refill * Raise/lower sections:: How to change commands' hierarchical level. @end menu - -@node Tree Structuring +@node Tree Structuring, Structuring Command Types, Structuring, Structuring +@comment node-name, next, previous, up @section Tree Structure of Sections @cindex Tree structuring @@ -3988,9 +3852,9 @@ The chapter structuring commands are described in the sections that follow; the @code{@@node} and @code{@@menu} commands are described in following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill - -@node Structuring Command Types -@section Structuring Command Types +@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring +@comment node-name, next, previous, up +@section Types of Structuring Commands The chapter structuring commands fall into four groups or series, each of which contains structuring commands corresponding to the @@ -4035,43 +3899,119 @@ start new pages in the printed manual; the @code{@@heading} commands do not.@refill @end itemize +@need 1000 Here are the four groups of chapter structuring commands:@refill -@multitable @columnfractions .19 .30 .29 .22 - -@item @tab @tab @tab No new page -@item Numbered @tab Unnumbered @tab Lettered and numbered - @tab Unnumbered -@item In contents @tab In contents @tab In contents @tab Not in contents -@item @tab @code{@@top} @tab - @tab @code{@@majorheading} -@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} - @tab @code{@@chapheading} -@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} - @tab @code{@@heading} -@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} - @tab @code{@@subheading} -@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} - @tab @code{@@subsubheading} -@end multitable +@c Slightly different formatting for regular sized books and smallbooks. +@ifset smallbook +@sp 1 +@tex +{\let\rm=\indrm \let\tt=\indtt +\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& +\hskip.5em#\hfil\cr + +& & & \rm No new pages\cr +\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr +\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr + +& & & \cr + & \tt @@top& & \tt @@majorheading\cr +\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr +\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr +\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& +\tt @@subheading\cr +\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& +\tt @@subsubheading\cr}} +@end tex +@end ifset +@ifclear smallbook +@sp 1 +@tex +\vbox{ +\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& +\hskip.5em#\hfil& \hskip.5em #\hfil\cr + +& & & \cr +& & & \rm No new pages\cr +\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr +\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr + +& & & \cr + & \tt @@top& & \tt @@majorheading\cr +\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr +\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr +\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& +\tt @@subheading\cr +\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& +\tt @@subsubheading\cr}} +@end tex +@end ifclear +@ifinfo +@example +@group + @r{No new pages} +@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} +@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} + + @@top @@majorheading +@@chapter @@unnumbered @@appendix @@chapheading +@@section @@unnumberedsec @@appendixsec @@heading +@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading +@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading +@end group +@end example +@end ifinfo +@c Cannot line up columns properly inside of an example because of roman +@c proportional fonts. +@ignore +@ifset smallbook +@iftex +@smallexample +@group + @r{No new pages} +@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} +@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} + + @@top @@majorheading +@@chapter @@unnumbered @@appendix @@chapheading +@@section @@unnumberedsec @@appendixsec @@heading +@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading +@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading +@end group +@end smallexample +@end iftex +@end ifset +@ifclear smallbook +@iftex +@smallexample +@group + @r{No new pages} +@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} +@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} + + @@top @@majorheading +@@chapter @@unnumbered @@appendix @@chapheading +@@section @@unnumberedsec @@appendixsec @@heading +@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading +@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading +@end group +@end smallexample +@end iftex +@end ignore -@node makeinfo top +@node makeinfo top, chapter, Structuring Command Types, Structuring +@comment node-name, next, previous, up @section @code{@@top} The @code{@@top} command is a special sectioning command that you use only after an @samp{@@node Top} line at the beginning of a Texinfo file. -The @code{@@top} command tells the @code{makeinfo} formatter which node -is the `Top' node, so it can use it as the root of the node tree if your -manual uses implicit pointers. It has the same typesetting effect as -@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered} -and @code{@@appendix}}). For detailed information, see @ref{makeinfo -top command, , The @code{@@top} Command}. - -The @code{@@top} node and its menu (if any) is conventionally wrapped in -an @code{@@ifnottex} conditional so that it will appear only in Info and -HTML output, not @TeX{}. - +The @code{@@top} command tells the @code{makeinfo} formatter +which node is the `Top' +node. It has the same typesetting effect as @code{@@unnumbered} +(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). +For detailed information, see +@ref{makeinfo top command, , The @code{@@top} Command}.@refill @node chapter, unnumbered & appendix, makeinfo top, Structuring @comment node-name, next, previous, up @@ -4109,8 +4049,9 @@ This kind of stylistic choice is not usually offered by Texinfo. @c but the Hacker's Dictionary wanted it ... -@node unnumbered & appendix -@section @code{@@unnumbered} and @code{@@appendix} +@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring +@comment node-name, next, previous, up +@section @code{@@unnumbered}, @code{@@appendix} @findex unnumbered @findex appendix @@ -4405,11 +4346,12 @@ An attempt to raise above `chapters' reproduces chapter commands; an attempt to lower below `subsubsections' reproduces subsubsection commands. -@node Nodes +@node Nodes, Menus, Structuring, Top +@comment node-name, next, previous, up @chapter Nodes @dfn{Nodes} are the primary segments of a Texinfo file. They do not -themselves impose a hierarchical or any other kind of structure on a file. +themselves impose a hierarchic or any other kind of structure on a file. Nodes contain @dfn{node pointers} that name other nodes, and can contain @dfn{menus} which are lists of nodes. In Info, the movement commands can carry you to a pointed-to node or to a node listed in a menu. Node @@ -4421,17 +4363,17 @@ books.@refill * Two Paths:: Different commands to structure Info output and printed output. * Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. +* node:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. @end menu - -@node Two Paths -@section Two Paths +@node Two Paths, Node Menu Illustration, Nodes, Nodes +@ifinfo +@heading Two Paths +@end ifinfo The node and menu commands and the chapter structuring commands are -technically independent of each other: +independent of each other: @itemize @bullet @item @@ -4448,26 +4390,26 @@ information for cross references; they do nothing else.@refill You can use node pointers and menus to structure an Info file any way you want; and you can write a Texinfo file so that its Info output has a -different structure than its printed output. However, virtually all -Texinfo files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is neither -convenient nor understandable to the reader to do otherwise.@refill +different structure than its printed output. However, most Texinfo +files are written such that the structure for the Info output +corresponds to the structure for the printed output. It is not +convenient to do otherwise.@refill Generally, printed output is structured in a tree-like hierarchy in which the chapters are the major limbs from which the sections branch out. Similarly, node pointers and menus are organized to create a matching structure in the Info output.@refill - -@node Node Menu Illustration +@node Node Menu Illustration, node, Two Paths, Nodes +@comment node-name, next, previous, up @section Node and Menu Illustration Here is a copy of the diagram shown earlier that illustrates a Texinfo file with three chapters, each of which contains two sections.@refill -The ``root'' is at the top of the diagram and the ``leaves'' are at the -bottom. This is how such a diagram is drawn conventionally; it -illustrates an upside-down tree. For this reason, the root node is +Note that the ``root'' is at the top of the diagram and the ``leaves'' +are at the bottom. This is how such a diagram is drawn conventionally; +it illustrates an upside-down tree. For this reason, the root node is called the `Top' node, and `Up' node pointers carry you closer to the root.@refill @@ -4483,36 +4425,35 @@ root.@refill | | | | | | Section Section Section Section Section Section 1.1 1.2 2.1 2.2 3.1 3.2 + @end group @end example -The fully-written command to start Chapter 2 would be this: +Write the beginning of the node for Chapter 2 like this:@refill @example @group -@@node Chapter 2, Chapter 3, Chapter 1, Top +@@node Chapter 2, Chapter 3, Chapter 1, top @@comment node-name, next, previous, up @end group @end example @noindent -This @code{@@node} line says that the name of this node is ``Chapter -2'', the name of the `Next' node is ``Chapter 3'', the name of the -`Previous' node is ``Chapter 1'', and the name of the `Up' node is -``Top''. You can omit writing out these node names if your document is -hierarchically organized (@pxref{makeinfo Pointer Creation}), but the -pointer relationships still obtain. +This @code{@@node} line says that the name of this node is ``Chapter 2'', the +name of the `Next' node is ``Chapter 3'', the name of the `Previous' +node is ``Chapter 1'', and the name of the `Up' node is ``Top''. @quotation @strong{Please Note:} `Next' refers to the next node at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may -be at a lower level---a section-level node most often follows a -chapter-level node, for example. `Next' and `Previous' refer to nodes -at the @emph{same} hierarchical level. (The `Top' node contains the -exception to this rule. Since the `Top' node is the only node at that -level, `Next' refers to the first following node, which is almost always -a chapter or chapter-level node.)@refill +be at a lower level---a section-level node may follow a chapter-level +node, and a subsection-level node may follow a section-level node. +`Next' and `Previous' refer to nodes at the @emph{same} hierarchical +level. (The `Top' node contains the exception to this rule. Since the +`Top' node is the only node at that level, `Next' refers to the first +following node, which is almost always a chapter or chapter-level +node.)@refill @end quotation To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter @@ -4565,13 +4506,11 @@ line, an @code{@@chapter} line, and then by indexing lines.@refill @end group @end example - -@node node +@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes +@comment node-name, next, previous, up @section The @code{@@node} Command @cindex Node, defined -@findex node - A @dfn{node} is a segment of text that begins at an @code{@@node} command and continues until the next @code{@@node} command. The definition of node is different from that for chapter or section. A @@ -4586,23 +4525,19 @@ several nodes, one for each section, subsection, and subsubsection.@refill To create a node, write an @code{@@node} command at the beginning of a -line, and follow it with up to four arguments, separated by commas, on -the rest of the same line. The first argument is required; it is the -name of this node. The subsequent arguments are the names of the -`Next', `Previous', and `Up' pointers, in that order, and may be omitted -if your Texinfo document is hierarchically organized (@pxref{makeinfo -Pointer Creation}). - -You may insert spaces before each name if you wish; the spaces are -ignored. You must write the name of the node and the names of the -`Next', `Previous', and `Up' pointers all on the same line. Otherwise, +line, and follow it with four arguments, separated by commas, on the +rest of the same line. These arguments are the name of the node, and +the names of the `Next', `Previous', and `Up' pointers, in that order. +You may insert spaces before each pointer if you wish; the spaces are +ignored. You must write the name of the node, and the names of the +`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, the formatters fail. (@inforef{Top, info, info}, for more information -about nodes in Info.) +about nodes in Info.)@refill Usually, you write one of the chapter-structuring command lines immediately after an @code{@@node} line---for example, an @code{@@section} or @code{@@subsection} line. (@xref{Structuring -Command Types}.) +Command Types, , Types of Structuring Commands}.)@refill @quotation @strong{Please note:} The GNU Emacs Texinfo mode updating commands work @@ -4614,8 +4549,8 @@ structuring lines. @xref{Updating Requirements}.@refill references. For this reason, you must write @code{@@node} lines in a Texinfo file that you intend to format for printing, even if you do not intend to format it for Info. (Cross references, such as the one at the -end of this sentence, are made with @code{@@xref} and related commands; -see @ref{Cross References}.)@refill +end of this sentence, are made with @code{@@xref} and its related +commands; see @ref{Cross References}.)@refill @menu * Node Names:: How to choose node and pointer names. @@ -4627,11 +4562,11 @@ see @ref{Cross References}.)@refill * Top Node Summary:: Write a brief description for readers. @end menu +@node Node Names, Writing a Node, node, node +@ifinfo +@subheading Choosing Node and Pointer Names +@end ifinfo -@node Node Names -@subsection Choosing Node and Pointer Names - -@cindex Node names, choosing The name of a node identifies the node. The pointers enable you to reach other nodes and consist of the names of those nodes.@refill @@ -4651,14 +4586,8 @@ Also, it is helpful to include a brief description of the manual in the `Top' node. @xref{First Node}, for information on how to write the first node of a Texinfo file.@refill -Even when you explicitly specify all pointers, that does not mean you -can write the nodes in the Texinfo source file in an arbitrary order! -Because @TeX{} processes the file sequentially, irrespective of node -pointers, you must write the nodes in the order you wish them to appear -in the printed output. - - -@node Writing a Node +@node Writing a Node, Node Line Tips, Node Names, node +@comment node-name, next, previous, up @subsection How to Write an @code{@@node} Line @cindex Writing an @code{@@node} line @cindex @code{@@node} line writing @@ -4686,8 +4615,8 @@ their proper order. The comment line helps you keep track of which arguments are for which pointers. This comment line is especially useful if you are not familiar with Texinfo.@refill -The template for a fully-written-out node line with `Next', `Previous', -and `Up' pointers looks like this:@refill +The template for a node line with `Next', `Previous', and `Up' pointers +looks like this:@refill @example @@node @var{node-name}, @var{next}, @var{previous}, @var{up} @@ -4695,21 +4624,22 @@ and `Up' pointers looks like this:@refill If you wish, you can ignore @code{@@node} lines altogether in your first draft and then use the @code{texinfo-insert-node-lines} command to -create @code{@@node} lines for you. However, we do not recommend this -practice. It is better to name the node itself at the same time that -you write a segment so you can easily make cross references. A large -number of cross references are an especially important feature of a good -Info file. +create @code{@@node} lines for you. However, we do not +recommend this practice. It is better to name the node itself +at the same time that you +write a segment so you can easily make cross references. A large number +of cross references are an especially important feature of a good Info +file.@refill After you have inserted an @code{@@node} line, you should immediately write an @@-command for the chapter or section and insert its name. Next (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it -much easier for people to find the node. +much easier for people to find the node.@refill - -@node Node Line Tips +@node Node Line Tips, Node Line Requirements, Writing a Node, node +@comment node-name, next, previous, up @subsection @code{@@node} Line Tips Here are three suggestions: @@ -4733,8 +4663,8 @@ section or chapter titles---initial and significant words are capitalized; others are not.@refill @end itemize - @node Node Line Requirements, First Node, Node Line Tips, node +@comment node-name, next, previous, up @subsection @code{@@node} Line Requirements @cindex Node line requirements @@ -4742,7 +4672,7 @@ Here are several requirements for @code{@@node} lines: @itemize @bullet @cindex Unique nodename requirement -@cindex Node name must be unique +@cindex Nodename must be unique @item All the node names for a single Info file must be unique.@refill @@ -4758,15 +4688,13 @@ different.@refill A pointer name must be the name of a node.@refill The node to which a pointer points may come before or after the -node containing the pointer. +node containing the pointer.@refill -@cindex @@-commands in nodename -@cindex Node name, should not contain @@-commands +@cindex @@-command in nodename +@cindex Nodename, cannot contain @item -@w{@@-commands} used in node names generally confuse Info, so you should -avoid them. For a few rare cases when this is useful, Texinfo has -limited support for using @w{@@-commands} in node names; see -@ref{Pointer Validation}. +You cannot use any of the Texinfo @@-commands in a node name; +@w{@@-commands} confuse Info.@refill @need 750 Thus, the beginning of the section called @code{@@chapter} looks like @@ -4781,15 +4709,11 @@ this:@refill @end group @end smallexample -@item -@cindex Apostrophe in nodename -@cindex Colon in nodename @cindex Comma in nodename -@cindex Period in nodename -@cindex Characters, invalid in node name -@cindex Invalid characters in node names -Unfortunately, you cannot use periods, commas, colons or apostrophes -within a node name; these confuse @TeX{} or the Info formatters.@refill +@cindex Apostrophe in nodename +@item +You cannot use commas or apostrophes within a node name; these +confuse @TeX{} or the Info formatters.@refill @need 700 For example, the following is a section title: @@ -4908,100 +4832,69 @@ include an edition number for the manual. (The title page should also contain this information: see @ref{titlepage, , @code{@@titlepage}}.)@refill -@node makeinfo Pointer Creation +@node makeinfo Pointer Creation, , node, Nodes @section Creating Pointers with @code{makeinfo} @cindex Creating pointers with @code{makeinfo} @cindex Pointer creation with @code{makeinfo} @cindex Automatic pointer creation with @code{makeinfo} -The @code{makeinfo} program has a feature for automatically defining -node pointers for a hierarchically organized file. +The @code{makeinfo} program has a feature for automatically creating +node pointers for a hierarchically organized file that lacks +them.@refill When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. However, you must write a sectioning command, such as @code{@@chapter} or @code{@@section}, on the line immediately following each truncated -@code{@@node} line (except that comment lines may intervene). +@code{@@node} line. You cannot write a comment line after a node +line; the section line must follow it immediately.@refill -In addition, you must follow the `Top' @code{@@node} line with a line -beginning with @code{@@top} to mark the `Top' node in the -file. @xref{makeinfo top, , @code{@@top}}. +In addition, you must follow the `Top' @code{@@node} line with a line beginning +with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo +top, , @code{@@top}}. Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the -node's hierarchical level. - -This node pointer insertion feature in @code{makeinfo} relieves you from -the need to update menus and pointers manually or with Texinfo mode -commands. (@xref{Updating Nodes and Menus}.) - - -@node anchor -@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets - -@findex anchor -@cindex Anchors -@cindex Cross-reference targets, arbitrary -@cindex Targets for cross-references, arbitrary - -An @dfn{anchor} is a position in your document, labeled so that -cross-references can refer to it, just as they can to nodes. You create -an anchor with the @code{@@anchor} command, and give the label as a -normal brace-delimited argument. For example: - -@example -This marks the @@anchor@{x-spot@}spot. -@dots{} -@@xref@{x-spot,,the spot@}. -@end example - -@noindent produces: - -@example -This marks the spot. -@dots{} -See [the spot], page 1. -@end example - -As you can see, the @code{@@anchor} command itself produces no output. -This example defines an anchor `x-spot' just before the word `spot'. -You can refer to it later with an @code{@@xref} or other cross-reference -command, as shown. @xref{Cross References}, for details on the -cross-reference commands. - -It is best to put @code{@@anchor} commands just before the position you -wish to refer to; that way, the reader's eye is led on to the correct -text when they jump to the anchor. You can put the @code{@@anchor} -command on a line by itself if that helps readability of the source. -Spaces are always ignored after @code{@@anchor}. - -Anchor names and node names may not conflict. Anchors and nodes are -given similar treatment in some ways; for example, the @code{goto-node} -command in standalone Info takes either an anchor name or a node name as -an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) +node's hierarchical level.@refill +This node pointer insertion feature in @code{makeinfo} is an +alternative to the menu and pointer creation and update commands in +Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially +helpful to people who do not use GNU Emacs for writing Texinfo +documents.@refill -@node Menus +@node Menus, Cross References, Nodes, Top +@comment node-name, next, previous, up @chapter Menus @cindex Menus @findex menu -@dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can -carry you to any node, regardless of the hierarchical structure; even to -nodes in a different Info file. However, the GNU Emacs Texinfo mode -updating commands work only to create menus of subordinate nodes. -Conventionally, cross references are used to refer to other nodes.} In -Info, you use menus to go to such nodes. Menus have no effect in -printed manuals and do not appear in them. +@dfn{Menus} contain pointers to subordinate +nodes.@footnote{Menus can carry you to any node, regardless +of the hierarchical structure; even to nodes in a different +Info file. However, the GNU Emacs Texinfo mode updating +commands work only to create menus of subordinate nodes. +Conventionally, cross references are used to refer to other +nodes.} In Info, you use menus to go to such nodes. Menus +have no effect in printed manuals and do not appear in +them.@refill By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it. Furthermore, a node -that has a menu should not contain much text. If you have a lot of text -and a menu, move most of the text into a new subnode---all but a few -lines. Otherwise, a reader with a terminal that displays only a few -lines may miss the menu and its associated text. As a practical matter, -you should locate a menu within 20 lines of the beginning of the -node. +uses the menu may not see text that follows it.@refill + +@ifinfo +A node that has a menu should @emph{not} contain much text. If you +have a lot of text and a menu, move most of the text into a new +subnode---all but a few lines.@refill +@end ifinfo +@iftex +@emph{A node that has a menu should not contain much text.} If you +have a lot of text and a menu, move most of the text into a new +subnode---all but a few lines. Otherwise, a reader with a terminal +that displays only a few lines may miss the menu and its associated +text. As a practical matter, you should locate a menu within 20 lines +of the beginning of the node.@refill +@end iftex @menu * Menu Location:: Put a menu in a short node. @@ -5012,7 +4905,6 @@ node. * Other Info Files:: How to refer to a different Info file. @end menu - @node Menu Location, Writing a Menu, Menus, Menus @ifinfo @heading Menus Need Short Nodes @@ -5022,6 +4914,14 @@ node. @cindex Nodes for menus are short @cindex Short nodes for menus +@ifinfo +A reader can easily see a menu that is close to the beginning of the +node. The node should be short. As a practical matter, you should +locate a menu within 20 lines of the beginning of the node. +Otherwise, a reader with a terminal that displays only a few lines may +miss the menu and its associated text.@refill +@end ifinfo + The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an @code{@@node} line, and then an @code{@@heading} @@ -5053,8 +4953,7 @@ For example, the preceding two paragraphs follow an Info-only menu, The Texinfo file for this document contains more than a dozen examples of this procedure. One is at the beginning of this chapter; -another is at the beginning of @ref{Cross References}. @refill - +another is at the beginning of the ``Cross References'' chapter.@refill @node Writing a Menu, Menu Parts, Menu Location, Menus @section Writing a Menu @@ -5080,16 +4979,14 @@ Larger Units of Text @end group @end example -In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu -entry}. (Note the space after the asterisk.) A line that does not -start with an @w{@samp{* }} may also appear in a menu. Such a line is -not a menu entry but is a menu comment line that appears in the Info -file. In the example above, the line @samp{Larger Units of Text} is a -menu comment line; the two lines starting with @w{@samp{* }} are menu -@cindex Spaces, in menus -entries. Space characters in a menu are preserved as-is; this allows -you to format the menu as you wish. - +In a menu, every line that begins with an @w{@samp{* }} is a +@dfn{menu entry}. (Note the space after the asterisk.) A +line that does not start with an @w{@samp{* }} may also +appear in a menu. Such a line is not a menu entry but is a +menu comment line that appears in the Info file. In +the example above, the line @samp{Larger Units of Text} is a +menu comment line; the two lines starting with @w{@samp{* }} +are menu entries. @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus @section The Parts of a Menu @@ -5298,20 +5195,20 @@ For example: not a Texinfo file, but a menu entry looks the same in both types of file.)@refill -The GNU Emacs Texinfo mode menu updating commands only work with nodes -within the current buffer, so you cannot use them to create menus that -refer to other files. You must write such menus by hand. +Note that the GNU Emacs Texinfo mode menu updating commands only work +with nodes within the current buffer, so you cannot use them to create +menus that refer to other files. You must write such menus by hand.@refill - -@node Cross References +@node Cross References, Marking Text, Menus, Top +@comment node-name, next, previous, up @chapter Cross References @cindex Making cross references @cindex Cross references @cindex References @dfn{Cross references} are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes and anchors are the -places to which cross references can refer. +same or different Texinfo files. In Texinfo, nodes are the +places to which cross references can refer.@refill @menu * References:: What cross references are for. @@ -5337,7 +5234,7 @@ it.@refill However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to -provide access to such information. Also, an online help system or a +provide access to such information. Also, an on-line help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross @@ -5352,16 +5249,15 @@ In Info, a cross reference results in an entry that you can follow using the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info commands, info}.)@refill -The various cross reference commands use nodes (or anchors, -@pxref{anchor,,@code{@@anchor}}) to define cross reference locations. -This is evident in Info, in which a cross reference takes you to the -specified location. @TeX{} also uses nodes to define cross reference -locations, but the action is less obvious. When @TeX{} generates a DVI -file, it records each node's page number and uses the page numbers in making -references. Thus, if you are writing a manual that will only be -printed, and will not be used online, you must nonetheless write -@code{@@node} lines to name the places to which you make cross -references.@refill +The various cross reference commands use nodes to define cross +reference locations. This is evident in Info, in which a cross +reference takes you to the specified node. @TeX{} also uses nodes to +define cross reference locations, but the action is less obvious. When +@TeX{} generates a DVI file, it records nodes' page numbers and +uses the page numbers in making references. Thus, if you are writing +a manual that will only be printed, and will not be used on-line, you +must nonetheless write @code{@@node} lines to name the places to which +you make cross references.@refill @need 800 @node Cross Reference Commands, Cross Reference Parts, References, Cross References @@ -5462,7 +5358,7 @@ The five possible arguments for a cross reference are:@refill @enumerate @item -The node or anchor name (required). This is the location to which the +The node name (required). This is the node to which the cross reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document.@refill @@ -5552,16 +5448,16 @@ or like this @noindent In @TeX{}, a cross reference looks like this: -@quotation +@example See Section @var{section-number} [@var{node-name}], page @var{page}. -@end quotation +@end example @noindent or like this -@quotation +@example See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end quotation +@end example The @code{@@xref} command does not generate a period or comma to end the cross reference in either the Info file or the printed output. @@ -5639,9 +5535,6 @@ which produces *Note Tropical Storms::, for more info. @end example -@noindent -and - @quotation See Section 3.1 [Tropical Storms], page 24, for more info. @end quotation @@ -5689,7 +5582,7 @@ See Section 5.2 [Electrical Effects], page 57. @noindent (Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.) +period; and that the node name is printed, not the cross reference name.)@refill You can write a clause after the cross reference, like this:@refill @@ -5731,7 +5624,7 @@ within a title or other section will divide it into two arguments. In a reference, you need to write a title such as ``Clouds, Mist, and Fog'' without the commas.@refill -Also, remember to write a comma or period after the closing brace of an +Also, remember to write a comma or period after the closing brace of a @code{@@xref} to terminate the cross reference. In the following examples, a clause follows a terminating comma.@refill @@ -5981,7 +5874,6 @@ This makes it useful as the last part of a sentence.@refill @noindent For example, -@cindex Hurricanes @example For more information, see @@ref@{Hurricanes@}. @end example @@ -5990,7 +5882,7 @@ For more information, see @@ref@{Hurricanes@}. produces @example -For more information, see *Note Hurricanes::. +For more information, see *Note Hurricanes. @end example @noindent @@ -6009,7 +5901,6 @@ both the printed and the Info format.@refill @noindent For example, -@cindex Sea surges @example @group Sea surges are described in @@ref@{Hurricanes@}. @@ -6033,13 +5924,12 @@ Sea surges are described in *Note Hurricanes::. @end example @quotation -@strong{Caution:} You @emph{must} write a period, comma, or right -parenthesis immediately after an @code{@@ref} command with two or more -arguments. Otherwise, Info will not find the end of the cross reference -entry and its attempt to follow the cross reference will fail. As a -general rule, you should write a period or comma after every -@code{@@ref} command. This looks best in both the printed and the Info -output.@refill +@strong{Caution:} You @emph{must} write a period or comma immediately +after an @code{@@ref} command with two or more arguments. Otherwise, +Info will not find the end of the cross reference entry and its +attempt to follow the cross reference will fail. As a general rule, +you should write a period or comma after every @code{@@ref} command. +This looks best in both the printed and the Info output.@refill @end quotation @node pxref, inforef, ref, Cross References @@ -6084,7 +5974,6 @@ of the output and not the other.@refill With one argument, a parenthetical cross reference looks like this:@refill -@cindex Flooding @example @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} @end example @@ -6240,113 +6129,68 @@ refer to printed works for which no Info form exists. @xref{cite, , @code{@@cite}}.@refill -@node uref -@section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} +@node uref, , inforef, Cross References +@section @code{@@uref@{@var{url}[, @var{displayed-text}]@}} @findex uref @cindex Uniform resource locator, referring to @cindex URL, referring to -@cindex @code{href}, producing HTML -@code{@@uref} produces a reference to a uniform resource locator (url). -It takes one mandatory argument, the url, and two optional arguments -which control the text that is displayed. In HTML output, @code{@@uref} -produces a link you can follow. - -The second argument, if specified, is the text to display (the default -is the url itself); in Info and DVI output, but not in HTML output, the -url is also output. - -@cindex Man page, reference to -The third argument, on the other hand, if specified is also the text to -display, but the url is @emph{not} output in any format. This is useful -when the text is already sufficiently referential, as in a man page. If -the third argument is given, the second argument is ignored. - -The simple one argument form, where the url is both the target and the -text of the link: +@code{@@uref} produces a reference to a uniform resource locator (URL). +It takes one mandatory argument, the URL, and one optional argument, the +text to display (the default is the URL itself). In HTML output, +@code{@@uref} produces a link you can follow. For example: @example -The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}. +The official GNU ftp site is +@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@} @end example -@noindent produces: +@noindent +produces (in text): @display -The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. +The official GNU ftp site is +@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu} @end display - -An example of the two-argument form: +@noindent +whereas @example -The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds -programs and texts. +The official +@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu, + GNU ftp site@} holds programs and texts. @end example -@noindent produces: +@noindent +produces (in text): @display -The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds -programs and texts. -@end display - -@noindent that is, the Info output is this: -@example -The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds -programs and texts. -@end example - -@noindent and the HTML output is this: -@example -The official GNU ftp site holds +The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds programs and texts. -@end example - - -An example of the three-argument form: -@example -The @@uref@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{} -@end example - -@noindent produces: -@display -The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{} @end display -@noindent but with HTML: +@noindent +and (in HTML): @example -The ls(1) program @dots{} +The official GNU ftp +site holds programs and texts. @end example -To merely indicate a url without creating a link people can follow, use -@code{@@url} (@pxref{url, @code{@@url}}). - - -Some people prefer to display url's in the unambiguous format: - -@display - -@end display - -@noindent -@cindex }, since any software that tries to detect url's in text already -has to detect them without the @samp{} format if you wish.)@refill - -@node env -@subsection @code{@@env}@{@var{environment-variable}@} -@findex env - -Use the @code{@@env} command to indicate environment variables, as used -by many operating systems, including GNU. Do not use it for -metasyntactic variables; use @code{@@var} instead (see the previous -section). - -@code{@@env} is equivalent to @code{@@code} in its effects. -For example: - -@example -The @@env@{PATH@} environment variable sets the search path for commands. -@end example -@noindent produces -@quotation -The @env{PATH} environment variable sets the search path for commands. -@end quotation - - -@node file +@node file, dfn, var, Indicating +@comment node-name, next, previous, up @subsection @code{@@file}@{@var{file-name}@} @findex file @@ -6894,58 +6679,7 @@ The @file{.el} files are in the @file{/usr/local/emacs/lisp} directory. @end quotation - -@node command -@subsection @code{@@command}@{@var{command-name}@} -@findex command -@cindex Command names, indicating -@cindex Program names, indicating - -Use the @code{@@command} command to indicate command names, such as -@command{ls} or @command{cc}. - -@code{@@command} is equivalent to @code{@@code} in its effects. -For example: - -@example -The command @@command@{ls@} lists directory contents. -@end example -@noindent produces -@quotation -The command @command{ls} lists directory contents. -@end quotation - -You should write the name of a program in the ordinary text font, rather -than using @code{@@command}, if you regard it as a new English word, -such as `Emacs' or `Bison'. - -When writing an entire shell command invocation, as in @samp{ls -l}, -you should use either @code{@@samp} or @code{@@code} at your discretion. - - -@node option -@subsection @code{@@option}@{@var{option-name}@} -@findex option - -Use the @code{@@option} command to indicate a command-line option; for -example, @option{-l} or @option{--version} or -@option{--output=@var{filename}}. - -@code{@@option} is equivalent to @code{@@samp} in its effects. -For example: - -@example -The option @@option@{-l@} produces a long listing. -@end example -@noindent produces -@quotation -The option @option{-l} produces a long listing. -@end quotation - -In tables, putting options inside @code{@@code} produces a -more pleasing effect. - -@node dfn +@node dfn, cite, file, Indicating @comment node-name, next, previous, up @subsection @code{@@dfn}@{@var{term}@} @findex dfn @@ -6974,18 +6708,18 @@ term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition---it should make the meaning clear. -@node cite +@node cite, url, dfn, Indicating +@comment node-name, next, previous, up @subsection @code{@@cite}@{@var{reference}@} @findex cite Use the @code{@@cite} command for the name of a book that lacks a -companion Info file. The command produces italics in the printed -manual, and quotation marks in the Info file. +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file.@refill -If a book is written in Texinfo, it is better to use a cross reference +(If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. -@xref{xref, , @code{@@xref}}. - +@xref{xref, , @code{@@xref}}.)@refill @ignore @c node ctrl, , cite, Indicating @@ -7037,50 +6771,27 @@ identify that control character: an uparrow followed by the character @end ignore -@node acronym -@subsection @code{@@acronym}@{@var{acronym}@} -@findex acronym - -@cindex NASA, as acronym -@cindex F.B.I., as acronym -@cindex Abbreviations, tagging -@cindex Acronyms, tagging -Use the @code{@@acronym} command for abbreviations written in all -capital letters, such as `@acronym{NASA}'. The abbreviation is given as -the single argument in braces, as in @samp{@@acronym@{NASA@}}. As -a matter of style, or for particular abbreviations, you may prefer to -use periods, as in @samp{@@acronym@{F.B.I.@}}. - -In @TeX{} and HTML, the argument is printed in a slightly smaller font -size. In Info or plain text output, this command changes nothing. - - -@node url +@node url, email, cite, Indicating @subsection @code{@@url}@{@var{uniform-resource-locator}@} @findex url @cindex Uniform resource locator, indicating @cindex URL, indicating -Use the @code{@@url} command to indicate a uniform resource locator on -the World Wide Web. This is analogous to @code{@@file}, @code{@@var}, -etc., and is purely for markup purposes. It does not produce a link you -can follow in HTML output (use the @code{@@uref} command for that, -@pxref{uref,, @code{@@uref}}). It is useful for url's which do -not actually exist. For example: +Use the @code{@@url} to indicate a uniform resource locator on the World +Wide Web. This is analogous to @code{@@file}, @code{@@var}, etc., and +is purely for markup purposes. It does not produce a link you can +follow in HTML output (the @code{@@uref} command does, @pxref{uref,, +@code{@@uref}}). It is useful for example URL's which do not actually +exist. For example: @c Two lines because one is too long for smallbook format. @example -For example, the url might be @@url@{http://example.org/path@}. +For example, the url might be +@@url@{http://host.domain.org/path@}. @end example -@noindent which produces: - -@display -For example, the url might be @url{http://example.org/path}. -@end display - -@node email +@node email, , url, Indicating @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} @findex email @@ -7098,11 +6809,12 @@ For example: Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}. Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. @end example -@noindent produces -@display +@noindent +produces +@example Send bug reports to @email{bug-texinfo@@gnu.org}. Send suggestions to the @email{bug-texinfo@@gnu.org, same place}. -@end display +@end example @node Emphasis, , Indicating, Marking Text @@ -7116,24 +6828,27 @@ Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which @TeX{} will typeset -text. These commands have no effect on Info and only one of them, +text. These commands have no affect on Info and only one of them, the @code{@@r} command, has any regular use.@refill @menu * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. @end menu -@node emph & strong +@node emph & strong, Smallcaps, Emphasis, Emphasis +@comment node-name, next, previous, up @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} @cindex Emphasizing text, font for @findex emph @findex strong The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} produces -@emph{italics} and @code{@@strong} produces @strong{bold}. +@code{@@strong} is stronger. In printed output, @code{@@emph} +produces @emph{italics} and @code{@@strong} produces +@strong{bold}.@refill @need 800 For example, @@ -7152,7 +6867,7 @@ files in the directory. produces the following in printed output: @quotation -@strong{Caution}: @samp{rm * .[^.]*} removes @emph{all} +@strong{Caution}: @code{rm * .[^.]*} removes @emph{all} files in the directory. @end quotation @@ -7165,7 +6880,7 @@ produces: @end ifinfo @example - *Caution*: `rm * .[^.]*' removes _all_ + *Caution*: `rm * .[^.]*' removes *all* files in the directory. @end example @@ -7173,25 +6888,31 @@ The @code{@@strong} command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example. -In the Info output, @code{@@emph} surrounds the text with underscores -(@samp{_}), and @code{@@strong} puts asterisks around the text. +In the Info file, both @code{@@emph} and @code{@@strong} put asterisks +around the text.@refill @quotation -@strong{Caution:} Do not use @code{@@strong} with the word @samp{Note}; -Info will mistake the combination for a cross reference. Use a phrase -such as @strong{Please note} or @strong{Caution} instead. +@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the +word @samp{Note}; Info will mistake the combination for a cross +reference. Use a phrase such as @strong{Please note} or +@strong{Caution} instead.@refill @end quotation - -@node Smallcaps +@node Smallcaps, Fonts, emph & strong, Emphasis @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font @cindex Small caps font @findex sc @r{(small caps font)} -Use the @samp{@@sc} command to set text in the printed and the HTML -output in @sc{a small caps font} and set text in the Info file in upper -case letters. Write the text you want to be in small caps (where -possible) between braces in lower case, like this: +@iftex +Use the @samp{@@sc} command to set text in the printed output in @sc{a +small caps font} and set text in the Info file in upper case letters.@refill +@end iftex +@ifinfo +Use the @samp{@@sc} command to set text in the printed output in a +small caps font and set text in the Info file in upper case letters.@refill +@end ifinfo + +Write the text between braces in lower case, like this:@refill @example The @@sc@{acm@} and @@sc@{ieee@} are technical societies. @@ -7206,28 +6927,32 @@ The @sc{acm} and @sc{ieee} are technical societies. @TeX{} typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case---but it's usually -better to use regular mixed case anyway. The Info formatting commands -set all small caps text in upper case. In HTML, the text is upper-cased -and a smaller font is used to render it. +text easier to read than text in all upper case. The Info formatting +commands set all small caps text in upper case.@refill -If the text between the braces of an @code{@@sc} command is uppercase, -@TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals -sparingly, if ever, and since it's redundant to mark all-uppercase text -with @code{@@sc}, @command{makeinfo} warns about such usage. +@ifinfo +If the text between the braces of an @code{@@sc} command is upper case, +@TeX{} typesets in full-size capitals. Use full-size capitals +sparingly.@refill +@end ifinfo +@iftex +If the text between the braces of an @code{@@sc} command is upper case, +@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals +sparingly.@refill +@end iftex You may also use the small caps font for a jargon word such as -@sc{ato} (a @sc{nasa} word meaning `abort to orbit'). +@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill There are subtleties to using the small caps font with a jargon word such as @sc{cdr}, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the @sc{cdr} of the list), but you should use @samp{@@code} when the word refers to the Lisp function of -the same spelling. +the same spelling.@refill - -@node Fonts +@node Fonts, Customized Highlighting, Smallcaps, Emphasis +@comment node-name, next, previous, up @subsection Fonts for Printing, Not Info @cindex Fonts for printing, not for Info @findex i @r{(italic font)} @@ -7271,78 +6996,191 @@ If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.@refill -@node Quotations and Examples -@chapter Quotations and Examples +@node Customized Highlighting, , Fonts, Emphasis +@comment node-name, next, previous, up +@subsection Customized Highlighting +@cindex Highlighting, customized +@cindex Customized highlighting -Quotations and examples are blocks of text consisting of one or more -whole paragraphs that are set off from the bulk of the text and -treated differently. They are usually indented.@refill +@c I think this whole section is obsolete with the advent of macros +@c --karl, 15sep96. +You can use regular @TeX{} commands inside of @code{@@iftex} @dots{} +@code{@@end iftex} to create your own customized highlighting commands +for Texinfo. The easiest way to do this is to equate your customized +commands with pre-existing commands, such as those for italics. Such +new commands work only with @TeX{}.@refill -In Texinfo, you always begin a quotation or example by writing an -@@-command at the beginning of a line by itself, and end it by writing -an @code{@@end} command that is also at the beginning of a line by -itself. For instance, you begin an example by writing @code{@@example} -by itself at the beginning of a line and end the example by writing -@code{@@end example} on a line by itself, at the beginning of that -line.@refill -@findex end +@findex definfoenclose +@cindex Enclosure command for Info +You can use the @code{@@definfoenclose} command inside of +@code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info +with the same names as new commands for @TeX{}. +@code{@@definfoenclose} creates new commands for Info that mark text by +enclosing it in strings that precede and follow the text. +@footnote{Currently, @code{@@definfoenclose} works only with +@code{texinfo-format-buffer} and @code{texinfo-format-region}, not with +@code{makeinfo}.}@refill -@menu -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* lisp:: How to illustrate Lisp code. -* small:: Forms for @code{@@smallbook}. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. -@end menu +Here is how to create a new @@-command called @code{@@phoo} that causes +@TeX{} to typeset its argument in italics and causes Info to display the +argument between @samp{//} and @samp{\\}.@refill -@node Block Enclosing Commands -@section Block Enclosing Commands +@need 1300 +For @TeX{}, write the following to equate the @code{@@phoo} command with +the existing @code{@@i} italics command:@refill -Here are commands for quotations and examples, explained further in the -following sections: +@example +@group +@@iftex +@@global@@let@@phoo=@@i +@@end iftex +@end group +@end example -@table @code -@item @@quotation -Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default.@refill +@noindent +This defines @code{@@phoo} as a command that causes @TeX{} to typeset +the argument to @code{@@phoo} in italics. @code{@@global@@let} tells +@TeX{} to equate the next argument with the argument that follows the +equals sign. -@item @@example -Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled.@refill +@need 1300 +For Info, write the following to tell the Info formatters to enclose the +argument between @samp{//} and @samp{\\}: -@item @@smallexample -Same as @code{@@example}, except that in @TeX{} this command typesets -text in a smaller font for the @code{@@smallbook} format than for the -default 8.5 by 11 inch format. +@example +@group +@@ifinfo +@@definfoenclose phoo, //, \\ +@@end ifinfo +@end group +@end example -@item @@lisp -Like @code{@@example}, but specifically for illustrating Lisp code. The -text is printed in a fixed-width font, and indented but not filled. +@noindent +Write the @code{@@definfoenclose} command on a line and follow it with +three arguments separated by commas (commas are used as separators in an +@code{@@node} line in the same way).@refill -@item @@smalllisp -Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}. +@itemize @bullet +@item +The first argument to @code{@@definfoenclose} is the @@-command name +@strong{without} the @samp{@@}; -@item @@display -Display illustrative text. The text is indented but not filled, and -no font is selected (so, by default, the font is roman).@refill +@item +the second argument is the Info start delimiter string; and, -@item @@smalldisplay -Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}. +@item +the third argument is the Info end delimiter string. +@end itemize -@item @@format -Like @code{@@display} (the text is not filled and no font is selected), -but the text is not indented. +@noindent +The latter two arguments enclose the highlighted text in the Info file. +A delimiter string may contain spaces. Neither the start nor end +delimiter is required. However, if you do not provide a start +delimiter, you must follow the command name with two commas in a row; +otherwise, the Info formatting commands will misinterpret the end +delimiter string as a start delimiter string.@refill + +After you have defined @code{@@phoo} both for @TeX{} and for Info, you +can then write @code{@@phoo@{bar@}} to see @samp{//bar\\} +in Info and see +@ifinfo +@samp{bar} in italics in printed output. +@end ifinfo +@iftex +@i{bar} in italics in printed output. +@end iftex + +Note that each definition applies to its own formatter: one for @TeX{}, +the other for Info. + +@need 1200 +Here is another example: + +@example +@group +@@ifinfo +@@definfoenclose headword, , : +@@end ifinfo +@@iftex +@@global@@let@@headword=@@b +@@end iftex +@end group +@end example + +@noindent +This defines @code{@@headword} as an Info formatting command that +inserts nothing before and a colon after the argument and as a @TeX{} +formatting command to typeset its argument in bold. + +@node Quotations and Examples, Lists and Tables, Marking Text, Top +@comment node-name, next, previous, up +@chapter Quotations and Examples + +Quotations and examples are blocks of text consisting of one or more +whole paragraphs that are set off from the bulk of the text and +treated differently. They are usually indented.@refill + +In Texinfo, you always begin a quotation or example by writing an +@@-command at the beginning of a line by itself, and end it by writing +an @code{@@end} command that is also at the beginning of a line by +itself. For instance, you begin an example by writing @code{@@example} +by itself at the beginning of a line and end the example by writing +@code{@@end example} on a line by itself, at the beginning of that +line.@refill +@findex end + +@menu +* Block Enclosing Commands:: Use different constructs for + different purposes. +* quotation:: How to write a quotation. +* example:: How to write an example in a fixed-width font. +* noindent:: How to prevent paragraph indentation. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. +* display:: How to write an example in the current font. +* format:: How to write an example that does not narrow + the margins. +* exdent:: How to undo the indentation of a line. +* flushleft & flushright:: How to push text flushleft or flushright. +* cartouche:: How to draw cartouches around examples. +@end menu + +@node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples +@section The Block Enclosing Commands + +Here are commands for quotations and examples:@refill + +@table @code +@item @@quotation +Indicate text that is quoted. The text is filled, indented, and +printed in a roman font by default.@refill + +@item @@example +Illustrate code, commands, and the like. The text is printed +in a fixed-width font, and indented but not filled.@refill + +@item @@lisp +Illustrate Lisp code. The text is printed in a fixed-width font, +and indented but not filled.@refill + +@item @@smallexample +Illustrate code, commands, and the like. Similar to +@code{@@example}, except that in @TeX{} this command typesets text in +a smaller font for the smaller @code{@@smallbook} format than for the +8.5 by 11 inch format.@refill + +@item @@smalllisp +Illustrate Lisp code. Similar to @code{@@lisp}, except that +in @TeX{} this command typesets text in a smaller font for the smaller +@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill -@item @@smallformat -Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}. +@item @@display +Display illustrative text. The text is indented but not filled, and +no font is specified (so, by default, the font is roman).@refill + +@item @@format +Print illustrative text. The text is not indented and not filled +and no font is specified (so, by default, the font is roman).@refill @end table The @code{@@exdent} command is used within the above constructs to @@ -7357,16 +7195,18 @@ paragraph.@refill You can use the @code{@@cartouche} command within one of the above constructs to highlight the example or quotation by drawing a box with -rounded corners around it. @xref{cartouche, , Drawing Cartouches Around -Examples}. +rounded corners around it. (The @code{@@cartouche} command affects +only the printed manual; it has no effect in the Info file; see +@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@node quotation +@node quotation, example, Block Enclosing Commands, Quotations and Examples +@comment node-name, next, previous, up @section @code{@@quotation} @cindex Quotations @findex quotation -The text of a quotation is processed normally except that: +The text of a quotation is +processed normally except that:@refill @itemize @bullet @item @@ -7408,8 +7248,8 @@ produces This is a foo. @end quotation - -@node example +@node example, noindent, quotation, Quotations and Examples +@comment node-name, next, previous, up @section @code{@@example} @cindex Examples, formatting them @cindex Formatting examples @@ -7435,9 +7275,10 @@ obtained by indenting each line with five spaces. @end example Write an @code{@@example} command at the beginning of a line by itself. -Mark the end of the example +This line will disappear from the output. Mark the end of the example with an @code{@@end example} command, also written at the beginning of a -line by itself.@refill +line by itself. The @code{@@end example} will disappear from the +output.@refill @need 700 For example, @@ -7455,14 +7296,12 @@ produces mv foo bar @end example -The lines containing @code{@@example} and @code{@@end example} -will disappear from the output. -To make the output look good, -you should put a blank line before the -@code{@@example} and another blank line after the @code{@@end example}. -Note that blank lines inside the beginning +Since the lines containing @code{@@example} and @code{@@end example} +will disappear, you should put a blank line before the +@code{@@example} and another blank line after the @code{@@end +example}. (Remember that blank lines between the beginning @code{@@example} and the ending @code{@@end example} will appear in -the output.@refill +the output.)@refill @quotation @strong{Caution:} Do not use tabs in the lines of an example (or anywhere @@ -7473,7 +7312,7 @@ convert tabs in a region to multiple spaces.)@refill @end quotation Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text that continues after an example should not be +paragraph, and the text continues after an example should not be indented. The @code{@@noindent} command prevents a piece of text from being indented as if it were a new paragraph. @ifinfo @@ -7484,8 +7323,8 @@ being indented as if it were a new paragraph. embedded within sentences, not set off from preceding and following text. @xref{code, , @code{@@code}}.) - -@node noindent +@node noindent, Lisp Example, example, Quotations and Examples +@comment node-name, next, previous, up @section @code{@@noindent} @findex noindent @@ -7542,11 +7381,11 @@ Do not put braces after an @code{@@noindent} command; they are not necessary, since @code{@@noindent} is a command used outside of paragraphs (@pxref{Command Syntax}).@refill - -@node lisp +@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples +@comment node-name, next, previous, up @section @code{@@lisp} -@findex lisp @cindex Lisp example +@findex lisp The @code{@@lisp} command is used for Lisp code. It is synonymous with the @code{@@example} command. @@ -7561,43 +7400,44 @@ regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.@footnote{It would be straightforward to extend Texinfo to work -in a similar fashion for C, Fortran, or other languages.} +in a similar fashion for C, Fortran, or other languages.}@refill Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by itself.@refill - -@node small -@section @code{@@small@dots{}} Block Commands +@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@smallexample} and @code{@@smalllisp} @cindex Small book example @cindex Example for a small book @cindex Lisp example for a small book -@findex smalldisplay @findex smallexample -@findex smallformat @findex smalllisp In addition to the regular @code{@@example} and @code{@@lisp} commands, -Texinfo has ``small'' example-style commands. These are -@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and -@code{@@smalllisp}. All of these commands are designed for use with the -@code{@@smallbook} command (which causes @TeX{} to format a printed book for -a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size). - -In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller -font for the smaller @code{@@smallbook} format than for the 8.5 by 11 -inch format. Consequently, many examples containing long lines fit in a -narrower, @code{@@smallbook} page without needing to be shortened. Both -commands typeset in the normal font size when you format for the 8.5 by -11 inch size. Indeed, in this situation, the @code{@@small@dots{}} -commands are equivalent to their non-small versions. - -In Info, the @code{@@small@dots{}} commands are also equivalent to their -non-small companion commands. - -Mark the end of an @code{@@small@dots{}} block with a corresponding -@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with -@code{@@end smallexample}. +Texinfo has two other ``example-style'' commands. These are the +@code{@@smallexample} and @code{@@smalllisp} commands. Both these +commands are designed for use with the @code{@@smallbook} command that +causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format +rather than the regular 8.5 by 11 inch format.@refill + +In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands +typeset text in a smaller font for the smaller @code{@@smallbook} +format than for the 8.5 by 11 inch format. Consequently, many examples +containing long lines fit in a narrower, @code{@@smallbook} page +without needing to be shortened. Both commands typeset in the normal +font size when you format for the 8.5 by 11 inch size; indeed, +in this situation, the @code{@@smallexample} and @code{@@smalllisp} +commands are defined to be the @code{@@example} and @code{@@lisp} +commands.@refill + +In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are +equivalent to the @code{@@example} and @code{@@lisp} commands, and work +exactly the same.@refill + +Mark the end of @code{@@smallexample} or @code{@@smalllisp} with +@code{@@end smallexample} or @code{@@end smalllisp}, +respectively.@refill @iftex Here is an example written in the small font used by the @@ -7608,13 +7448,6 @@ Here is an example written in the small font used by the @tex % Remove extra vskip; this is a kludge to counter the effect of display \vskip-3\baselineskip -{\smalltt -\dots{} to make sure that you have the freedom to -distribute copies of free software (and charge for -this service if you wish), that you receive source -code or can get it if you want it, that you can -change the software or use pieces of it in new free -programs; and that you know you can do these things.} @end tex @end display @end ifclear @@ -7638,21 +7471,21 @@ this text appears in a smaller font. @end smallexample @end ifinfo -The @code{@@small@dots{}} commands make it easier to prepare smaller -format manuals without forcing you to edit examples by hand to fit them -onto narrower pages.@refill +The @code{@@smallexample} and @code{@@smalllisp} commands make it +easier to prepare smaller format manuals without forcing you to edit +examples by hand to fit them onto narrower pages.@refill -As a general rule, a printed document looks better if you use only one -of (for example) @code{@@example} or in @code{@@smallexample} -consistently within a chapter. Only occasionally should you mix the two -formats. +As a general rule, a printed document looks better if you write all the +examples in a chapter consistently in @code{@@example} or in +@code{@@smallexample}. Only occasionally should you mix the two +formats.@refill @xref{smallbook, , Printing ``Small'' Books}, for more information about the @code{@@smallbook} command.@refill - -@node display -@section @code{@@display} and @code{@@smalldisplay} +@node display, format, smallexample & smalllisp, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@display} @cindex Display formatting @findex display @@ -7670,14 +7503,9 @@ and an @code{@@end display} command. The @code{@@display} command indents the text, but does not fill it. @end display -@findex smalldisplay -Texinfo also provides a command @code{@@smalldisplay}, which is like -@code{@@display} but uses a smaller font in @code{@@smallbook} format. -@xref{small}. - - -@node format -@section @code{@@format} and @code{@@smallformat} +@node format, exdent, display, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@format} @findex format The @code{@@format} command is similar to @code{@@example} except @@ -7691,14 +7519,7 @@ from this example, the @code{@@format} command does not fill the text. @end format -@findex smallformat -Texinfo also provides a command @code{@@smallformat}, which is like -@code{@@format} but uses a smaller font in @code{@@smallbook} format. -@xref{small}. - - - -@node exdent +@node exdent, flushleft & flushright, format, Quotations and Examples @section @code{@@exdent}: Undoing a Line's Indentation @cindex Indentation undoing @findex exdent @@ -7808,8 +7629,8 @@ further highlight an example or quotation. For instance, you could write a manual in which one type of example is surrounded by a cartouche for emphasis.@refill -@code{@@cartouche} affects only the printed manual; it has no effect in -other output files. +The @code{@@cartouche} command affects only the printed manual; it has +no effect in the Info file.@refill @need 1500 For example, @@ -7861,8 +7682,8 @@ the first column; multi-column tables are also supported. * Multi-column Tables:: How to construct generalized tables. @end menu -@node Introducing Lists, itemize, Lists and Tables, Lists and Tables @ifinfo +@node Introducing Lists, itemize, Lists and Tables, Lists and Tables @heading Introducing Lists @end ifinfo @@ -7931,12 +7752,12 @@ Enumerated lists, using numbers or letters. @item @@table @itemx @@ftable @itemx @@vtable -Two-column tables, optionally with indexing. +Two-column tables with indexing. @end table - -@node itemize -@section @code{@@itemize}: Making an Itemized List +@node itemize, enumerate, Introducing Lists, Lists and Tables +@comment node-name, next, previous, up +@section Making an Itemized List @cindex Itemization @findex itemize @@ -7944,26 +7765,23 @@ The @code{@@itemize} command produces sequences of indented paragraphs, with a bullet or other mark inside the left margin at the beginning of each paragraph for which such a mark is desired.@refill -@cindex @code{@@w}, for blank items Begin an itemized list by writing @code{@@itemize} at the beginning of a line. Follow the command, on the same line, with a character or a Texinfo command that generates a mark. Usually, you will write @code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any command or character that results in a single -character in the Info file. If you don't want any mark at all, use -@code{@@w}. (When you write the mark command such as -@code{@@bullet} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.) If you don't specify a mark command, the default is -@code{@@bullet}. +@code{@@minus}, or any character or any special symbol that results in +a single character in the Info file. (When you write @code{@@bullet} +or @code{@@minus} after an @code{@@itemize} command, you may omit the +@samp{@{@}}.)@refill Write the text of the indented paragraphs themselves after the @code{@@itemize}, up to another line that says @code{@@end itemize}.@refill +Before each paragraph for which a mark in the margin is desired, write +a line that says just @code{@@item}. Do not write any other text on this +line.@refill @findex item -Before each paragraph for which a mark in the margin is desired, write a -line that says just @code{@@item}. It is ok to have text following the -@code{@@item}. Usually, you should put a blank line before an @code{@@item}. This puts a blank line in the Info file. (@TeX{} inserts the proper @@ -7971,8 +7789,8 @@ interline whitespace in either case.) Except when the entries are very brief, these blank lines make the list look better.@refill Here is an example of the use of @code{@@itemize}, followed by the -output it produces. @code{@@bullet} produces an @samp{*} in Info and a -round dot in @TeX{}. +output it produces. Note that @code{@@bullet} produces an @samp{*} in +Info and a round dot in @TeX{}.@refill @example @group @@ -8045,9 +7863,9 @@ Second outer item. @end itemize @end quotation - -@node enumerate -@section @code{@@enumerate}: Making a Numbered or Lettered List +@node enumerate, Two-column Tables, itemize, Lists and Tables +@comment node-name, next, previous, up +@section Making a Numbered or Lettered List @cindex Enumeration @findex enumerate @@ -8061,18 +7879,18 @@ letter as an option. Without an argument, @code{@@enumerate} starts the list with the number @samp{1}. With a numeric argument, such as @samp{3}, the command starts the list with that number. With an upper or lower case letter, such as @samp{a} or @samp{A}, the command starts -the list with that letter. +the list with that letter.@refill Write the text of the enumerated list in the same way you write an itemized list: put @code{@@item} on a line of its own before the start of each paragraph that you want enumerated. Do not write any other text -on the line beginning with @code{@@item}. +on the line beginning with @code{@@item}.@refill You should put a blank line between entries in the list. -This generally makes it easier to read the Info file. +This generally makes it easier to read the Info file.@refill @need 1500 -Here is an example of @code{@@enumerate} without an argument: +Here is an example of @code{@@enumerate} without an argument:@refill @example @group @@ -8179,8 +7997,8 @@ exhibits, and command-line option summaries. * itemx:: How to put more entries in the first column. @end menu -@node table, ftable vtable, Two-column Tables, Two-column Tables @ifinfo +@node table, ftable vtable, Two-column Tables, Two-column Tables @subheading Using the @code{@@table} Command Use the @code{@@table} command to produce two-column tables.@refill @@ -8209,7 +8027,6 @@ commands output the first column entries without added highlighting listed here. However, you can only use commands that normally take arguments in braces.)@refill -@findex item Begin each table entry with an @code{@@item} command at the beginning of a line. Write the first column text on the same line as the @code{@@item} command. Write the second column text on the line @@ -8217,7 +8034,8 @@ following the @code{@@item} line and on subsequent lines. (You do not need to type anything for an empty second column entry.) You may write as many lines of supporting text as you wish, even several paragraphs. But only text on the same line as the @code{@@item} will -be placed in the first column, including any footnote. +be placed in the first column.@refill +@findex item Normally, you should put a blank line before an @code{@@item} line. This puts a blank like in the Info file. Except when the entries are @@ -8255,8 +8073,8 @@ If you want to list two or more named items with a single block of text, use the @code{@@itemx} command. (@xref{itemx, , @code{@@itemx}}.)@refill - -@node ftable vtable +@node ftable vtable, itemx, table, Two-column Tables +@comment node-name, next, previous, up @subsection @code{@@ftable} and @code{@@vtable} @cindex Tables with indexes @cindex Indexing table entries automatically @@ -8270,8 +8088,8 @@ functions and @code{@@vtable} automatically enters each of the items in the first column of the table into the index of variables. This simplifies the task of creating indices. Only the items on the same line as the @code{@@item} commands are indexed, and they are indexed in -exactly the form that they appear on that line. @xref{Indices}, -for more information about indices.@refill +exactly the form that they appear on that line. @xref{Indices, , +Creating Indices}, for more information about indices.@refill Begin a two-column table using @code{@@ftable} or @code{@@vtable} by writing the @@-command at the beginning of a line, followed on the same @@ -8282,7 +8100,8 @@ itself. See the example for @code{@@table} in the previous section. -@node itemx +@node itemx, , ftable vtable, Two-column Tables +@comment node-name, next, previous, up @subsection @code{@@itemx} @cindex Two named items for @code{@@table} @findex itemx @@ -8294,6 +8113,7 @@ line of its own. Use @code{@@itemx} for all but the first entry; @code{@@itemx} command works exactly like @code{@@item} except that it does not generate extra vertical space above the first column text. +@need 1000 For example, @example @@ -8342,7 +8162,7 @@ multitable} completes the table. Details in the sections below. * Multitable Rows:: Defining multitable rows, with examples. @end menu -@node Multitable Column Widths +@node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables @subsection Multitable Column Widths @cindex Multitable column widths @cindex Column widths, defining for multitables @@ -8365,9 +8185,10 @@ To specify column widths as fractions of the line length, write @@multitable @@columnfractions .33 .33 .33 @end example -@noindent The fractions need not add up exactly to 1.0, as these do +@noindent +The fractions need not add up exactly to 1.0, as these do not. This allows you to produce tables that do not need the full line -length. You can use a leading zero if you wish. +length. @item @cindex Prototype row, column widths defined by @@ -8397,7 +8218,7 @@ particularly likely to be useful. @cindex Rows, of a multitable @findex item -@findex tab +@cindex tab After the @code{@@multitable} command defining the column widths (see the previous section), you begin each row in the body of a multitable with @code{@@item}, and separate the column entries with @code{@@tab}. @@ -8406,7 +8227,7 @@ input lines in your source file as necessary. Here is a complete example of a multi-column table (the text is from @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, -emacs, The GNU Emacs Manual}): +xemacs, XEmacs User's Manual}): @example @@multitable @@columnfractions .15 .45 .4 @@ -8426,7 +8247,8 @@ split that window. @@end multitable @end example -@noindent produces: +@noindent +produces: @multitable @columnfractions .15 .45 .4 @item Key @tab Command @tab Description @@ -8447,8 +8269,9 @@ split that window. @node Indices, Insertions, Lists and Tables, Top @comment node-name, next, previous, up -@chapter Indices +@chapter Creating Indices @cindex Indices +@cindex Creating indices Using Texinfo, you can generate indices without having to sort and collate entries manually. In an index, the entries are listed in @@ -8584,6 +8407,17 @@ command; that would be a spelling error. Whichever case convention you use, please use it consistently! +@ignore +Concept index entries consist of English text. The usual convention +is to capitalize the first word of each such index entry, unless that +word is the name of a function, variable, or other such entity that +should not be capitalized. However, if your concept index entries are +consistently short (one or two words each) it may look better for each +regular entry to start with a lower case letter, aside from proper +names and acronyms that always call for upper case letters. Whichever +convention you adapt, please be consistent! +@end ignore + Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them. @@ -8628,11 +8462,24 @@ Make an entry in the data type index for @var{data type}.@refill @quotation @strong{Caution:} Do not use a colon in an index entry. In Info, a -colon separates the menu entry name from the node name, so a colon in -the entry itself confuses Info. @xref{Menu Parts, , The Parts of a -Menu}, for more information about the structure of a menu entry. +colon separates the menu entry name from the node name. An extra +colon confuses Info. +@xref{Menu Parts, , The Parts of a Menu}, +for more information about the structure of a menu entry.@refill @end quotation +If you write several identical index entries in different places in a +Texinfo file, the index in the printed manual will list all the pages to +which those entries refer. However, the index in the Info file will +list @strong{only} the node that references the @strong{first} of those +index entries. Therefore, it is best to write indices in which each +entry refers to only one place in the Texinfo file. Fortunately, this +constraint is a feature rather than a loss since it means that the index +will be easy to use. Otherwise, you could create an index that lists +several pages for one entry and your reader would not know to which page +to turn. If you have two identical entries for one topic, change the +topics slightly, or qualify them to indicate the difference.@refill + You are not actually required to use the predefined indices for their canonical purposes. For example, suppose you wish to index some C preprocessor macros. You could put them in the function index along @@ -8824,7 +8671,8 @@ You should define new indices within or right after the end-of-header line of a Texinfo file, before any @code{@@synindex} or @code{@@syncodeindex} commands (@pxref{Header}).@refill -@node Insertions +@node Insertions, Breaks, Indices, Top +@comment node-name, next, previous, up @chapter Special Insertions @cindex Inserting special characters and symbols @cindex Special insertions @@ -8837,17 +8685,12 @@ elements that do not correspond to simple characters you can type. These are: @itemize @bullet -@item Braces and @samp{@@}. +@item Braces, @samp{@@} and periods. @item Whitespace within and around a sentence. @item Accents. @item Dots and bullets. @item The @TeX{} logo and the copyright symbol. -@item The pounds currency symbol. -@item The minus sign. @item Mathematical expressions. -@item Glyphs for evaluation, macros, errors, etc. -@item Footnotes. -@item Images. @end itemize @end iftex @@ -8864,7 +8707,6 @@ These are: * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. -* Footnotes:: How to include footnotes. * Images:: How to include graphics. @end menu @@ -8898,8 +8740,7 @@ output. Do not put braces after an @code{@@@@} command. - -@node Inserting Braces +@node Inserting Braces, , Inserting An Atsign, Braces Atsigns @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} @findex @{ @r{(single @samp{@{})} @findex @} @r{(single @samp{@}})} @@ -8914,11 +8755,12 @@ Do not put braces after either an @code{@@@{} or an @code{@@@}} command. -@node Inserting Space +@node Inserting Space, Inserting Accents, Braces Atsigns, Insertions @section Inserting Space @cindex Inserting space @cindex Spacing, inserting +@cindex Whitespace, inserting The following sections describe commands that control spacing of various kinds within and after sentences. @@ -8929,8 +8771,7 @@ kinds within and after sentences. * dmn:: How to format a dimension. @end menu - -@node Not Ending a Sentence +@node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space @subsection Not Ending a Sentence @cindex Not ending a sentence @@ -8938,13 +8779,13 @@ kinds within and after sentences. @cindex Periods, inserting Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, less or more space is inserted after -a period in a typeset manual. Since it is not always possible -to determine when a period ends a sentence and when it is used +a period in a typeset manual. Since it is not always possible for +Texinfo to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed in some circumstances. -Usually, Texinfo can guess how to handle periods, so you do not need to +(Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the -period, question mark, or exclamation mark that ends a sentence. +period, question mark, or exclamation mark that ends a sentence.) @findex : @r{(suppress widening)} Use the @code{@@:}@: command after a period, question mark, @@ -8952,6 +8793,7 @@ exclamation mark, or colon that should not be followed by extra space. For example, use @code{@@:}@: after periods that end abbreviations which are not at the ends of sentences. +@need 700 For example, @example @@ -9022,7 +8864,8 @@ In the Info file output, @code{@@.}@: is equivalent to a simple The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to work well with the Emacs sentence motion commands (@pxref{Sentences,,, -emacs, The GNU Emacs Manual}). +xemacs, XEmacs User's Manual}). This made it necessary for them to be +incompatible with some other formatting systems that use @@-commands. Do not put braces after any of these commands. @@ -9032,7 +8875,6 @@ Do not put braces after any of these commands. @cindex Multiple spaces @cindex Whitespace, inserting -@cindex Space, inserting horizontal @findex (space) @findex (tab) @findex (newline) @@ -9060,7 +8902,8 @@ Spacey@@ @@ @@ @@ example. @end example -@noindent produces +@noindent +produces @example Spacey@ @ @ @ @@ -9073,7 +8916,7 @@ Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by Do not follow any of these commands with braces. -@node dmn +@node dmn, , Multiple Spaces, Inserting Space @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension @cindex Thin space between number, dimension @cindex Dimension formatting @@ -9085,7 +8928,7 @@ At times, you may want to write @samp{12@dmn{pt}} or abbreviation for the dimension. You can use the @code{@@dmn} command to do this. On seeing the command, @TeX{} inserts just enough space for proper typesetting; the Info formatting commands insert no space -at all, since the Info file does not require it. +at all, since the Info file does not require it.@refill To use the @code{@@dmn} command, write the number and then follow it immediately, with no intervening space, by @code{@@dmn}, and then by @@ -9108,10 +8951,10 @@ In these cases, however, the formatters may insert a line break between the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if you write a period after an abbreviation within a sentence, you should write @samp{@@:} after the period to prevent @TeX{} from inserting extra -whitespace, as shown here. @xref{Not Ending a Sentence}. +whitespace, as shown here. @xref{Inserting Space}. -@node Inserting Accents +@node Inserting Accents, Dots Bullets, Inserting Space, Insertions @section Inserting Accents @cindex Inserting accents @@ -9142,7 +8985,7 @@ possible, since accented characters are very common in some languages. @findex dotaccent @cindex Dot accent @findex H -@cindex Hungarian umlaut accent +@cindex Hungariam umlaut accent @findex ringaccent @cindex Ring accent @findex tieaccent @@ -9210,22 +9053,22 @@ commonly used in languages other than English. @cindex Es-zet @cindex Sharp S @cindex German S -@multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S} +@multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S} @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? -@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle +@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash -@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures +@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S @end multitable -@node Dots Bullets -@section Inserting Ellipsis and Bullets +@node Dots Bullets, TeX and copyright, Inserting Accents, Insertions +@section Inserting Ellipsis, Dots, and Bullets @cindex Dots, inserting @cindex Bullets, inserting @cindex Ellipsis, inserting @@ -9249,10 +9092,9 @@ the braces, the formatters would be confused. @xref{Command Syntax, , @end menu -@node dots -@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{}) +@node dots, bullet, Dots Bullets, Dots Bullets +@subsection @code{@@dots}@{@} (@dots{}) @findex dots -@findex enddots @cindex Inserting dots @cindex Dots, inserting @@ -9274,7 +9116,7 @@ the dots in the ellipsis. @end iftex -@node bullet +@node bullet, , dots, Dots Bullets @subsection @code{@@bullet}@{@} (@bullet{}) @findex bullet @@ -9303,7 +9145,7 @@ braces.@refill @end menu -@node tex +@node tex, copyright symbol, TeX and copyright, TeX and copyright @subsection @code{@@TeX}@{@} (@TeX{}) @findex tex (command) @@ -9311,10 +9153,10 @@ Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed manual, this is a special logo that is different from three ordinary letters. In Info, it just looks like @samp{TeX}. The @code{@@TeX@{@}} command is unique among Texinfo commands in that the -@samp{T} and the @samp{X} are in upper case.@refill +@kbd{T} and the @kbd{X} are in upper case.@refill -@node copyright symbol +@node copyright symbol, , tex, TeX and copyright @subsection @code{@@copyright}@{@} (@copyright{}) @findex copyright @@ -9324,7 +9166,7 @@ this is @samp{(C)}.@refill @node pounds, minus, TeX and copyright, Insertions -@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling +@section @code{@@pounds@{@}} (@pounds{}): Pounds Sterling @findex pounds Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a @@ -9364,7 +9206,7 @@ an itemized list, you do not need to type the braces @node math, Glyphs, minus, Insertions -@section @code{@@math}: Inserting Mathematical Expressions +@section @code{@@math} - Inserting Mathematical Expressions @findex math @cindex Mathematical expressions @@ -9404,7 +9246,7 @@ remember to write the mathematical expression between one or two @samp{$} (dollar-signs) as appropriate. -@node Glyphs +@node Glyphs, Images, math, Insertions @section Glyphs for Examples @cindex Glyphs @@ -9461,12 +9303,12 @@ message.@refill @menu -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: +* result:: +* expansion:: +* Print Glyph:: +* Error Glyph:: +* Equivalence:: +* Point Glyph:: @end menu @node result, expansion, Glyphs Summary, Glyphs @@ -9475,7 +9317,6 @@ message.@refill @cindex Indicating evaluation @cindex Evaluation glyph @cindex Value of an expression, indicating -@findex result Use the @code{@@result@{@}} command to indicate the result of evaluating an expression.@refill @@ -9503,7 +9344,6 @@ may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. @node expansion, Print Glyph, result, Glyphs @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion @cindex Expansion, indicating it -@findex expansion When an expression is a macro call, it expands into a new expression. You can indicate the result of the expansion with the @@ -9559,7 +9399,6 @@ five spaces.@refill @node Print Glyph, Error Glyph, expansion, Glyphs @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output @cindex Printed output, indicating it -@findex print Sometimes an expression will print output during its execution. You can indicate the printed output with the @code{@@print@{@}} command.@refill @@ -9605,7 +9444,6 @@ In a Texinfo source file, this example is written as follows: @node Error Glyph, Equivalence, Print Glyph, Glyphs @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message @cindex Error message, indicating it -@findex error A piece of code may cause an error when you evaluate it. You can designate the error message with the @code{@@error@{@}} command.@refill @@ -9651,7 +9489,6 @@ Wrong type argument: integer-or-marker-p, x @node Equivalence, Point Glyph, Error Glyph, Glyphs @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence @cindex Equivalence, indicating it -@findex equiv Sometimes two expressions produce identical results. You can indicate the exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill @@ -9685,10 +9522,9 @@ This indicates that evaluating @code{(make-sparse-keymap)} produces identical results to evaluating @code{(list 'keymap)}. -@node Point Glyph +@node Point Glyph, , Equivalence, Glyphs @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer -@cindex Point, indicating in a buffer -@findex point +@cindex Point, indicating it in a buffer Sometimes you need to show an example of text in an Emacs buffer. In such examples, the convention is to include the entire contents of the @@ -9749,337 +9585,128 @@ This is the changed @@point@{@}contents of foo. @end example -@node Footnotes -@section Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon -the primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.}@refill - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu +@c this should be described with figures when we have them +@c perhaps in the quotation/example chapter. +@node Images, , Glyphs, Insertions +@section Inserting Images -@node Footnote Commands -@subsection Footnote Commands +@cindex Images, inserting +@cindex Pictures, inserting +@findex image -In Texinfo, footnotes are created with the @code{@@footnote} command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. Footnotes may -be of any length (they will be broken across pages if necessary), but -are usually short. The template is: +You can insert an image in an external file with the @code{@@image} +command: @example -ordinary text@@footnote@{@var{text of footnote}@} +@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} @end example -As shown here, the @code{@@footnote} command should come right after the -text being footnoted, with no intervening space; otherwise, the footnote -marker might end up starting a line. +@cindex Formats for images +@cindex Image formats +The @var{filename} argument is mandatory, and must not have an +extension, because the different processors support different formats: +@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript +format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for +Info output (more or less as if it was an @code{@@example}). HTML +output requires @file{@var{filename}.jpg}. -For example, this clause is followed by a sample footnote@footnote{Here -is the sample footnote.}; in the Texinfo source, it looks like -this:@refill +@cindex Width of images +@cindex Height of images +@cindex Aspect ratio of images +@cindex Distorting images +The optional @var{width} and @var{height} arguments specify the size to +scale the image to (they are ignored for Info output). If they are both +specified, the image is presented in its natural size (given in the +file); if only one is specified, the other is scaled proportionately; +and if both are specified, both are respected, thus possibly distorting +the original image by changing its aspect ratio. + +@cindex Dimensions and image sizes +The @var{width} and @var{height} may be specified using any valid @TeX{} +dimension, namely: + +@table @asis +@item pt +@cindex Points (dimension) +point (72.27pt = 1in) +@item pc +@cindex Picas +pica (1pc = 12pt) +@item bp +@cindex Big points +big point (72bp = 1in) +@item in +@cindex Inches +inch +@item cm +@cindex Centimeters +centimeter (2.54cm = 1in) +@item mm +@cindex Millimeters +millimeter (10mm = 1cm) +@item dd +@cindex Did@^ot points +did@^ot point (1157dd = 1238pt) +@item cc +@cindex Ciceros +cicero (1cc = 12dd) +@item sp +@cindex Scaled points +scaled point (65536sp = 1pt) +@end table + +@pindex ridt.eps +For example, the following will scale a file @file{ridt.eps} to one +inch vertically, with the width scaled proportionately: @example -@dots{}a sample footnote@@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} +@@image@{ridt,,1in@} @end example -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line.@refill +@pindex epsf.tex +For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be +installed somewhere that @TeX{} can find it. This file is included in +the Texinfo distribution and is available from +@uref{ftp://ftp.tug.org/tex/epsf.tex}. -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}. The -reference mark is followed by a cross-reference link to the footnote's -text. -In the HTML output, footnote references are marked with a small, -superscripted number which is rendered as a hypertext link to the -footnote text. +@node Breaks, Definition Commands, Insertions, Top +@chapter Making and Preventing Breaks +@cindex Making line and page breaks +@cindex Preventing line and page breaks -By the way, footnotes in the argument of an @code{@@item} command for a -@code{@@table} must be on the same line as the @code{@@item} -(as usual). @xref{Two-column Tables}. +Usually, a Texinfo file is processed both by @TeX{} and by one of the +Info formatting commands. Line, paragraph, or page breaks sometimes +occur in the `wrong' place in one or other form of output. You must +ensure that text looks right both in the printed manual and in the +Info file.@refill +For example, in a printed manual, page breaks may occur awkwardly in +the middle of an example; to prevent this, you can hold text together +using a grouping command that keeps the text from being split across +two pages. Conversely, you may want to force a page break where none +would occur normally. Fortunately, problems like these do not often +arise. When they do, use the break, break prevention, or pagination +commands.@refill -@node Footnote Styles -@subsection Footnote Styles +@menu +* Break Commands:: Cause and prevent splits. +* Line Breaks:: How to force a single line to use two lines. +* - and hyphenation:: How to tell TeX about hyphenation points. +* w:: How to prevent unwanted line breaks. +* sp:: How to insert blank lines. +* page:: How to force the start of a new page. +* group:: How to prevent unwanted page breaks. +* need:: Another way to prevent unwanted page breaks. +@end menu -Info has two footnote styles, which determine where the text of the -footnote is located:@refill - -@itemize @bullet -@cindex @samp{@r{End}} node footnote style -@item -In the `End' node style, all the footnotes for a single node -are placed at the end of that node. The footnotes are separated from -the rest of the node by a line of dashes with the word -@samp{Footnotes} within it. Each footnote begins with an -@samp{(@var{n})} reference mark.@refill - -@need 700 -@noindent -Here is an example of a single footnote in the end of node style:@refill - -@example -@group - --------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node.@refill - -The name of the node with the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node.@refill - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style:@refill - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) The first syllable of "Texinfo" is pronounced like "speck", not -"hex". @dots{} -@end group -@end smallexample -@end itemize - -A Texinfo file may be formatted into an Info file with either footnote -style.@refill - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{texinfo-format-buffer} and -@code{texinfo-format-region} use the `separate' style and -@code{makeinfo} uses the `end' style.@refill - -@c !!! note: makeinfo's --footnote-style option overrides footnotestyle -@ignore -If you use @code{makeinfo} to create the Info file, the -@samp{--footnote-style} option determines which style is used, -@samp{end} for the end of node style or @samp{separate} for the -separate node style. Thus, to format the Texinfo manual in the -separate node style, you would use the following shell command:@refill - -@example -makeinfo --footnote-style=separate texinfo.texi -@end example - -@noindent -To format the Texinfo manual in the end of node style, you would -type:@refill - -@example -makeinfo --footnote-style=end texinfo.texi -@end example -@end ignore -@ignore -If you use @code{texinfo-format-buffer} or -@code{texinfo-format-region} to create the Info file, the value of the -@code{texinfo-footnote-style} variable controls the footnote style. -It can be either @samp{"separate"} for the separate node style or -@samp{"end"} for the end of node style. (You can change the value of -this variable with the @kbd{M-x edit-options} command (@pxref{Edit -Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or -with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining -and Setting Variables, emacs, The GNU Emacs Manual}).@refill - -The @code{texinfo-footnote-style} variable also controls the style if -you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} -command in Emacs.@refill -@end ignore -@ifinfo -This chapter contains two footnotes.@refill -@end ifinfo - - -@c this should be described with figures when we have them -@c perhaps in the quotation/example chapter. -@node Images -@section Inserting Images - -@cindex Images, inserting -@cindex Pictures, inserting -@findex image - -You can insert an image given in an external file with the -@code{@@image} command: - -@example -@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} -@end example - -@cindex Formats for images -@cindex Image formats -The @var{filename} argument is mandatory, and must not have an -extension, because the different processors support different formats: -@itemize @bullet -@item -@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript -format). -@item -@pindex pdftex@r{, and images} -PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). -@item -@code{makeinfo} uses @file{@var{filename}.txt} verbatim for -Info output (more or less as if it was an @code{@@example}). -@item -@cindex GIF, unsupported due to patents -@cindex PNG image format -@cindex JPEG image format -@code{makeinfo} producing HTML output tries @file{@var{filename}.png}; -if that does not exist, it tries @file{@var{filename}.jpg}. If that -does not exist either, it complains. (We cannot support GIF format due -to patents.) -@end itemize - -@cindex Width of images -@cindex Height of images -@cindex Aspect ratio of images -@cindex Distorting images -The optional @var{width} and @var{height} arguments specify the size to -scale the image to (they are ignored for Info output). If neither is -specified, the image is presented in its natural size (given in the -file); if only one is specified, the other is scaled proportionately; -and if both are specified, both are respected, thus possibly distorting -the original image by changing its aspect ratio. - -@cindex Dimensions and image sizes -The @var{width} and @var{height} may be specified using any valid @TeX{} -dimension, namely: - -@table @asis -@item pt -@cindex Points (dimension) -point (72.27pt = 1in) -@item pc -@cindex Picas -pica (1pc = 12pt) -@item bp -@cindex Big points -big point (72bp = 1in) -@item in -@cindex Inches -inch -@item cm -@cindex Centimeters -centimeter (2.54cm = 1in) -@item mm -@cindex Millimeters -millimeter (10mm = 1cm) -@item dd -@cindex Did@^ot points -did@^ot point (1157dd = 1238pt) -@item cc -@cindex Ciceros -cicero (1cc = 12dd) -@item sp -@cindex Scaled points -scaled point (65536sp = 1pt) -@end table - -@pindex ridt.eps -For example, the following will scale a file @file{ridt.eps} to one -inch vertically, with the width scaled proportionately: - -@example -@@image@{ridt,,1in@} -@end example - -@pindex epsf.tex -For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be -installed somewhere that @TeX{} can find it. (The standard location is -@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a -root of your @TeX{} directory tree.) This file is included in the -Texinfo distribution and is available from -@uref{ftp://tug.org/tex/epsf.tex}. - -@code{@@image} can be used within a line as well as for displayed -figures. Therefore, if you intend it to be displayed, be sure to leave -a blank line before the command, or the output will run into the -preceding text. - - -@node Breaks -@chapter Making and Preventing Breaks -@cindex Making line and page breaks -@cindex Preventing line and page breaks - -Usually, a Texinfo file is processed both by @TeX{} and by one of the -Info formatting commands. Line, paragraph, or page breaks sometimes -occur in the `wrong' place in one or other form of output. You must -ensure that text looks right both in the printed manual and in the -Info file.@refill - -For example, in a printed manual, page breaks may occur awkwardly in -the middle of an example; to prevent this, you can hold text together -using a grouping command that keeps the text from being split across -two pages. Conversely, you may want to force a page break where none -would occur normally. Fortunately, problems like these do not often -arise. When they do, use the break, break prevention, or pagination -commands.@refill - -@menu -* Break Commands:: Cause and prevent splits. -* Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. -* w:: How to prevent unwanted line breaks. -* sp:: How to insert blank lines. -* page:: How to force the start of a new page. -* group:: How to prevent unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. -@end menu - -@node Break Commands, Line Breaks, Breaks, Breaks -@ifinfo -@heading Break Commands -@end ifinfo +@ifinfo +@node Break Commands, Line Breaks, Breaks, Breaks +@heading The Break Commands +@end ifinfo +@iftex +@sp 1 +@end iftex The break commands create or allow line and paragraph breaks:@refill @@ -10206,13 +9833,15 @@ put a @samp{-} at each hyphenation point. For example: @example @@hyphenation@{man-u-script man-u-scripts@} @end example -@noindent @TeX{} only uses the specified hyphenation points when the +@noindent +@TeX{} only uses the specified hyphenation points when the words match exactly, so give all necessary variants. @end table Info output is not hyphenated, so these commands have no effect there. -@node w +@node w, sp, - and hyphenation, Breaks +@comment node-name, next, previous, up @section @code{@@w}@{@var{text}@}: Prevent Line Breaks @findex w @r{(prevent line break)} @cindex Line breaks, preventing @@ -10223,40 +9852,38 @@ within @var{text}.@refill You can use the @code{@@w} command to prevent @TeX{} from automatically hyphenating a long name or phrase that happens to fall near the end of a -line. For example: +line.@refill @example -You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}. +You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}. @end example @noindent produces @quotation -You can copy GNU software from @w{@samp{ftp.gnu.org}}. +You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}. @end quotation -@cindex Non-breakable space -@cindex Unbreakable space -@cindex Tied space -You can also use @code{@@w} to produce a non-breakable space: - -@example -None of the formatters will break at this@@w@{ @}space. -@end example - +@quotation +@strong{Caution:} Do not write an @code{@@refill} command at the end +of a paragraph containing an @code{@@w} command; it will cause the +paragraph to be refilled and may thereby negate the effect of the +@code{@@w} command.@refill +@end quotation -@node sp +@node sp, page, w, Breaks +@comment node-name, next, previous, up @section @code{@@sp} @var{n}: Insert Blank Lines @findex sp @r{(line spacing)} -@cindex Space, inserting vertical +@cindex Spaces (blank lines) @cindex Blank lines @cindex Line spacing A line beginning with and containing only @code{@@sp @var{n}} generates @var{n} blank lines of space in both the printed manual and the Info file. @code{@@sp} also forces a paragraph break. For -example, +example,@refill @example @@sp 2 @@ -10402,8 +10029,7 @@ This paragraph is preceded by @dots{} The @code{@@need} command is useful for preventing orphans (single lines at the bottoms of printed pages).@refill - -@node Definition Commands +@node Definition Commands, Footnotes, Breaks, Top @chapter Definition Commands @cindex Definition commands @@ -10662,7 +10288,7 @@ produces These two search commands are similar except @dots{} @end deffn -Each definition command has an `x' form: @code{@@defunx}, +Each of the other definition commands has an `x' form: @code{@@defunx}, @code{@@defvrx}, @code{@@deftypefunx}, etc. The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. @@ -10790,7 +10416,7 @@ works like @code{@@defun}.@refill @item @@defspec @var{name} @var{arguments}@dots{} The @code{@@defspec} command is the definition command for special forms. (In Lisp, a special form is an entity much like a function, -@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.) +@pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.) @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} @dots{}} and works like @code{@@defun}.@refill @end table @@ -10809,8 +10435,8 @@ something like a variable---an entity that records a value. You must choose a term to describe the category of entity being defined; for example, ``Variable'' could be used if the entity is a variable. Write the @code{@@defvr} command at the beginning of a line and -follow it on the same line by the category of the entity and the -name of the entity. +followed it on the same line by the category of the entity and the +name of the entity.@refill Capitalize the category name like a title. If the name of the category contains spaces, as in the name ``User Option'', enclose it in braces. @@ -10877,7 +10503,7 @@ The template is: @cindex User options, marking The @code{@@defopt} command is the definition command for @dfn{user options}, i.e., variables intended for users to change according to -taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs +taste; Emacs has many such (@pxref{Variables,,, xemacs, XEmacs User's Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User Option@} @dots{}} and works like @code{@@defvar}.@refill @end table @@ -11173,7 +10799,7 @@ The template is: @var{name}.@refill @end table -@node Abstract Objects +@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail @subsection Object-Oriented Programming Here are the commands for formatting descriptions about abstract @@ -11208,7 +10834,8 @@ name. Thus,@refill illustrates how you would write the first line of a definition of the @code{border-pattern} class option of the class @code{Window}.@refill -The template is: +The template is + @example @group @@defcv @var{category} @var{class} @var{name} @@ -11226,6 +10853,7 @@ variables in object-oriented programming. @code{@@defivar} is equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill The template is: + @example @group @@defivar @var{class} @var{instance-variable-name} @@ -11236,20 +10864,12 @@ The template is: @code{@@defivar} creates an entry in the index of variables. -@findex deftypeivar -@item @@deftypeivar @var{class} @var{data-type} @var{name} -The @code{@@deftypeivar} command is the definition command for typed -instance variables in object-oriented programming. It is similar to -@code{@@defivar} with the addition of the @var{data-type} parameter to -specify the type of the instance variable. @code{@@deftypeivar} creates an -entry in the index of variables. - @findex defop @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} The @code{@@defop} command is the general definition command for entities that may resemble methods in object-oriented programming. -These entities take arguments, as functions do, but are associated with -particular classes of objects.@refill +These entities take arguments, as functions do, but are associated +with particular classes of objects.@refill For example, some systems have constructs called @dfn{wrappers} that are associated with classes as methods are, but that act more like @@ -11281,7 +10901,10 @@ is followed on the same line by the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any.@refill +@need 800 +@noindent The template is: + @example @group @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} @@ -11293,34 +10916,23 @@ The template is: @code{@@defop} creates an entry, such as `@code{expose} on @code{windows}', in the index of functions.@refill -@findex deftypeop -@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypeop} command is the definition command for typed -operations in object-oriented programming. It is similar to -@code{@@defop} with the addition of the @var{data-type} parameter to -specify the return type of the method. @code{@@deftypeop} creates an -entry in the index of functions. - @item @@defmethod @var{class} @var{name} @var{arguments}@dots{} @findex defmethod The @code{@@defmethod} command is the definition command for methods in object-oriented programming. A method is a kind of function that implements an operation for a particular class of objects and its -subclasses. -@ignore -@c ADR: Who cares?!? -@c KB: Oh, I don't know, I think this info is crucial! -In the Lisp Machine, methods actually were functions, but +subclasses. In the Lisp Machine, methods actually were functions, but they were usually defined with @code{defmethod}. -@end ignore @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. The command is written at the beginning of a line and is followed by the name of the class of the method, the name of the method, and its arguments, if any.@refill +@need 800 @noindent -For example: +For example, + @example @group @@defmethod @code{bar-class} bar-method argument @@ -11346,7 +10958,6 @@ The template is: @code{@@defmethod} creates an entry, such as `@code{bar-method} on @code{bar-class}', in the index of functions.@refill - @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} @findex defmethod The @code{@@deftypemethod} command is the definition command for methods @@ -11357,7 +10968,7 @@ to the @code{@@defmethod} command with the addition of the @end table -@node Data Types +@node Data Types, , Abstract Objects, Def Cmds in Detail @subsection Data Types Here is the command for data types:@refill @@ -11426,8 +11037,8 @@ commands. The name of the function follows immediately after the @code{@@defun} command and it is followed, on the same line, by the parameter list.@refill -Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs -Lisp Reference Manual}. +Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp +Reference Manual}. @quotation @defun apply function &rest arguments @@ -11467,6 +11078,7 @@ In the Texinfo source file, this example looks like this: @example @group @@defun apply function &rest arguments + @@code@{apply@} calls @@var@{function@} with @@var@{arguments@}, just like @@code@{funcall@} but with one difference: the last of @@var@{arguments@} is a list of @@ -11501,7 +11113,7 @@ sense in @@code@{apply@}. @group An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}. +in the description of @@code@{mapcar@}.@@refill @@end defun @end group @end example @@ -11514,29 +11126,202 @@ Ordinary variables and user options are described using a format like that for functions except that variables do not take arguments. -@node Conditionals -@chapter Conditionally Visible Text -@cindex Conditionally visible text -@cindex Text, conditionally visible -@cindex Visibility of conditional text -@cindex If text conditionally visible +@node Footnotes, Conditionals, Definition Commands, Top +@chapter Footnotes +@cindex Footnotes +@findex footnote + +A @dfn{footnote} is for a reference that documents or elucidates the +primary text.@footnote{A footnote should complement or expand upon +the primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see @cite{The Chicago Manual of Style}, which is published by the +University of Chicago Press.}@refill + +@menu +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. +@end menu + +@node Footnote Commands, Footnote Styles, Footnotes, Footnotes +@section Footnote Commands + +In Texinfo, footnotes are created with the @code{@@footnote} command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +@example +ordinary text@@footnote@{@var{text of footnote}@} +@end example -Sometimes it is good to use different text for different output formats. -For example, you can use the @dfn{conditional commands} to specify -different text for the printed manual and the Info output. +As shown here, the @code{@@footnote} command should come right after the +text being footnoted, with no intervening space; otherwise, the +formatters the footnote mark might end up starting up a line. -Conditional commands may not be nested. +For example, this clause is followed by a sample +footnote@footnote{Here is the sample footnote.}; in the Texinfo +source, it looks like this:@refill -The conditional commands comprise the following categories. +@example +@dots{}a sample footnote@@footnote@{Here is the sample +footnote.@}; in the Texinfo source@dots{} +@end example + +@strong{Warning:} Don't use footnotes in the argument of the +@code{@@item} command for a @code{@@table} table. This doesn't work, and +because of limitations of @TeX{}, there is no way to fix it. You must +put the footnote into the body text of the table. + +In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line.@refill + +In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: @samp{(1)}.@refill + + +@node Footnote Styles, , Footnote Commands, Footnotes +@section Footnote Styles + +Info has two footnote styles, which determine where the text of the +footnote is located:@refill @itemize @bullet -@item Commands for HTML, Info, or @TeX{}. -@item Commands for not HTML, Info, or @TeX{}. -@item Raw @TeX{} or HTML commands. +@cindex @samp{@r{End}} node footnote style @item -Substituting text for all formats, and testing if a flag is set or clear. +In the `End' node style, all the footnotes for a single node +are placed at the end of that node. The footnotes are separated from +the rest of the node by a line of dashes with the word +@samp{Footnotes} within it. Each footnote begins with an +@samp{(@var{n})} reference mark.@refill + +@need 700 +@noindent +Here is an example of a single footnote in the end of node style:@refill + +@example +@group + --------- Footnotes --------- + +(1) Here is a sample footnote. +@end group +@end example + +@cindex @samp{@r{Separate}} footnote style +@item +In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a ``footnote reference'' follows +each @samp{(@var{n})} reference mark in the body of the +node. The footnote reference is actually a cross reference +which you use to reach the footnote node.@refill + +The name of the node containing the footnotes is constructed +by appending @w{@samp{-Footnotes}} to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the @file{Footnotes} node is +@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an +`Up' node pointer that leads back to its parent node.@refill + +@noindent +Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style:@refill + +@smallexample +@group +File: texinfo.info Node: Overview-Footnotes, Up: Overview + +(1) Note that the first syllable of "Texinfo" is +pronounced like "speck", not "hex". @dots{} +@end group +@end smallexample @end itemize +A Texinfo file may be formatted into an Info file with either footnote +style.@refill + +@findex footnotestyle +Use the @code{@@footnotestyle} command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either @samp{end} for the end node style or +@samp{separate} for the separate node style. + +@need 700 +For example, + +@example +@@footnotestyle end +@end example +@noindent +or +@example +@@footnotestyle separate +@end example + +Write an @code{@@footnotestyle} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you +include the @code{@@footnotestyle} command between the start-of-header +and end-of-header lines, the region formatting commands will format +footnotes as specified.)@refill + +If you do not specify a footnote style, the formatting commands use +their default style. Currently, @code{texinfo-format-buffer} and +@code{texinfo-format-region} use the `separate' style and +@code{makeinfo} uses the `end' style.@refill + +@c !!! note: makeinfo's --footnote-style option overrides footnotestyle +@ignore +If you use @code{makeinfo} to create the Info file, the +@samp{--footnote-style} option determines which style is used, +@samp{end} for the end of node style or @samp{separate} for the +separate node style. Thus, to format the Texinfo manual in the +separate node style, you would use the following shell command:@refill + +@example +makeinfo --footnote-style=separate texinfo.texi +@end example + +@noindent +To format the Texinfo manual in the end of node style, you would +type:@refill + +@example +makeinfo --footnote-style=end texinfo.texi +@end example +@end ignore +@ignore +If you use @code{texinfo-format-buffer} or +@code{texinfo-format-region} to create the Info file, the value of the +@code{texinfo-footnote-style} variable controls the footnote style. +It can be either @samp{"separate"} for the separate node style or +@samp{"end"} for the end of node style. (You can change the value of +this variable with the @kbd{M-x edit-options} command (@pxref{Edit +Options, , Editing Variable Values, xemacs, XEmacs User's Manual}), or +with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining +and Setting Variables, xemacs, XEmacs User's Manual}).@refill + +The @code{texinfo-footnote-style} variable also controls the style if +you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} +command in Emacs.@refill +@end ignore +This chapter contains two footnotes.@refill + + +@node Conditionals, Macros, Footnotes, Top +@comment node-name, next, previous, up +@chapter Conditionally Visible Text +@cindex Conditionally visible text +@cindex Text, conditionally visible +@cindex Visibility of conditional text +@cindex If text conditionally visible + +Sometimes it is good to use different text for a printed manual and +its corresponding Info file. In this case, you can use the +@dfn{conditional commands} to specify which text is for the printed manual +and which is for the Info file.@refill + @menu * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. @@ -11546,18 +11331,21 @@ Substituting text for all formats, and testing if a flag is set or clear. flag to a string that you can insert. @end menu - -@node Conditional Commands -@section Conditional Commands +@node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals +@ifinfo +@heading Conditional Commands +@end ifinfo @findex ifinfo -@code{@@ifinfo} begins segments of text that should be ignored by @TeX{} -when it typesets the printed manual. The segment of text appears only -in the Info file. The @code{@@ifinfo} command should appear on a line -by itself; end the Info-only text with a line containing @code{@@end -ifinfo} by itself. At the beginning of a Texinfo file, the Info -permissions are contained within a region marked by @code{@@ifinfo} and -@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.) +@code{@@ifinfo} begins segments of text that should be ignored +by @TeX{} when it +typesets the printed manual. The segment of text appears only +in the Info file. +The @code{@@ifinfo} command should appear on a line by itself; end +the Info-only text with a line containing @code{@@end ifinfo} by +itself. At the beginning of a Texinfo file, the Info permissions are +contained within a region marked by @code{@@ifinfo} and @code{@@end +ifinfo}. (@xref{Info Summary and Permissions}.)@refill @findex iftex @findex ifhtml @@ -11576,9 +11364,6 @@ This text will appear only in the printed manual. @@ifinfo However, this text will appear only in Info. @@end ifinfo -@@ifhtml -And this text will only appear in HTML. -@@end ifhtml @end example @noindent @@ -11589,16 +11374,18 @@ This text will appear only in the printed manual. @ifinfo However, this text will appear only in Info. @end ifinfo -@ifhtml -And this text will only appear in HTML. -@end ifhtml @noindent -Notice that you only see one of the input lines, depending on which -version of the manual you are reading. +Note how you only see one of the two lines, depending on whether you +are reading the Info version or the printed version of this +manual.@refill + +The @code{@@titlepage} command is a special variant of @code{@@iftex} that +is used for making the title and copyright pages of the printed +manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill -@node Conditional Not Commands +@node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals @section Conditional Not Commands @findex ifnothtml @findex ifnotinfo @@ -11619,8 +11406,7 @@ If the output file is not being made for the given format, the region is included. Otherwise, it is ignored. The regions delimited by these commands are ordinary Texinfo source as -with @code{@@iftex}, not raw formatter source as with @code{@@tex} -(@pxref{Raw Formatter Commands}). +with @code{@@iftex}, not raw formatter source as with @code{@@tex}. @node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals @@ -11652,8 +11438,8 @@ overridden by Texinfo features. You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} commands, by delineating a region with the @code{@@tex} and @code{@@end tex} commands. (The @code{@@tex} command also causes Info to ignore the -region, like the @code{@@iftex} command.) The sole exception is that the -@code{@@} character still introduces a command, so that @code{@@end tex} +region, like the @code{@@iftex} command.) The sole exception is that +@code{@@} chracter still introduces a command, so that @code{@@end tex} can be recognized properly. @cindex Mathematical expressions @@ -11687,12 +11473,13 @@ $$ \chi^2 = \sum_{i=1}^N @findex html Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit a region to be included in HTML output only, and @code{@@html @dots{} -@@end html} for a region of raw HTML (again, except that @code{@@} is +@@end ifhtml} for a region of raw HTML (again, except that @code{@@} is still the escape character, so the @code{@@end} command can be recognized.) -@node set clear value +@node set clear value, , Raw Formatter Commands, Conditionals +@comment node-name, next, previous, up @section @code{@@set}, @code{@@clear}, and @code{@@value} You can direct the Texinfo formatting commands to format or ignore parts @@ -11707,12 +11494,12 @@ insert the date in several places in the Texinfo file.@refill @menu * ifset ifclear:: Format a region if a flag is set. -* set value:: Expand a flag variable to a string. +* value:: Replace a flag with a string. * value Example:: An easy way to update edition information. @end menu -@node ifset ifclear +@node ifset ifclear, value, set clear value, set clear value @subsection @code{@@ifset} and @code{@@ifclear} @findex ifset @@ -11722,10 +11509,8 @@ ifset} commands. When the @var{flag} is cleared, the Texinfo formatting commands do @emph{not} format the text. Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a -@var{flag}; a @dfn{flag} name can be any single word, containing -letters, numerals, hyphens, or underscores. - -The format for the command looks like this:@refill +@var{flag}; a @dfn{flag} can be any single word. The format for the +command looks like this:@refill @findex set @example @@ -11829,17 +11614,13 @@ format the text up to the following @code{@@end ifclear} command.@refill @end table - -@node set value -@subsection @code{@@set} and @code{@@value} +@node value, value Example, ifset ifclear, set clear value +@subsection @code{@@value} @findex value You can use the @code{@@set} command to specify a value for a flag, -which is expanded by the @code{@@value} command. A flag is an -identifier; for best results, use only letters and numerals in a flag -name, not @samp{-} or @samp{_}---they will work in some contexts, but -not all, due to limitations in @TeX{}. The value is just a string of -characters, the remainder of the input line. +which is expanded by the @code{@@value} command. The value is a string +a characters. Write the @code{@@set} command like this: @@ -11848,11 +11629,12 @@ Write the @code{@@set} command like this: @end example @noindent -This sets the value of the flag @code{foo} to ``This is a string.''. +This sets the value of @code{foo} to ``This is a string.'' + +The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with +the string to which @var{flag} is set.@refill -The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} -command with the string to which @var{flag} is set. Thus, when -@code{foo} is set as shown above, the Texinfo formatters convert +Thus, when @code{foo} is set as shown above, the Texinfo formatters convert @example @group @@ -11874,9 +11656,9 @@ If you write the @code{@@set} command like this: @noindent without specifying a string, the value of @code{foo} is an empty string. -If you clear a previously set flag with @code{@@clear @var{flag}}, a -subsequent @code{@@value@{flag@}} command is invalid and the string is -replaced with an error message that says @samp{@{No value for +If you clear a previously set flag with an @code{@@clear @var{flag}} +command, a subsequent @code{@@value@{flag@}} command is invalid and the +string is replaced with an error message that says @samp{@{No value for "@var{flag}"@}}. For example, if you set @code{foo} as follows:@refill @@ -11913,16 +11695,15 @@ It is a @{No value for "how-much"@} wet day. @end group @end example - -@node value Example +@node value Example, , value, set clear value @subsection @code{@@value} Example You can use the @code{@@value} command to limit the number of places you -need to change when you record an update to a manual. Here is how it is -done in @cite{The GNU Make Manual}: +need to change when you record an update to a manual. +Here is how it is done in @cite{The GNU Make Manual}: -@enumerate -@item +@need 1000 +@noindent Set the flags: @example @@ -11934,7 +11715,8 @@ Set the flags: @end group @end example -@item +@need 750 +@noindent Write text for the first @code{@@ifinfo} section, for people reading the Texinfo file: @@ -11943,11 +11725,12 @@ Texinfo file: This is Edition @@value@{EDITION@}, last updated @@value@{UPDATED@}, of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, version @@value@{VERSION@}. +for @@code@{make@}, Version @@value@{VERSION@}. @end group @end example -@item +@need 1000 +@noindent Write text for the title page, for people reading the printed manual: @c List only the month and the year since that looks less fussy on a @c printed cover than a date that lists the day as well. @@ -11965,7 +11748,8 @@ Write text for the title page, for people reading the printed manual: (On a printed cover, a date listing the month and the year looks less fussy than a date listing the day as well as the month and year.) -@item +@need 750 +@noindent Write text for the Top node, for people reading the Info file: @example @@ -11977,6 +11761,7 @@ for @@code@{make@} Version @@value@{VERSION@}. @end group @end example +@need 950 After you format the manual, the text in the first @code{@@ifinfo} section looks like this: @@ -11986,336 +11771,49 @@ This is Edition 0.35 Beta, last updated 14 August 1992, of `The GNU Make Manual', for `make', Version 3.63 Beta. @end group @end example -@end enumerate When you update the manual, change only the values of the flags; you do -not need to edit the three sections. - - -@node Internationalization -@chapter Internationalization - -@cindex Internationalization -Texinfo has some support for writing in languages other than English, -although this area still needs considerable work. - -For a list of the various accented and special characters Texinfo -supports, see @ref{Inserting Accents}. - -@menu -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. -@end menu - - -@node documentlanguage -@section @code{@@documentlanguage @var{cc}}: Set the Document Language - -@findex documentlanguage -@cindex Language, declaring -@cindex Document language, declaring - -The @code{@@documentlanguage} command declares the current document -language. Write it on a line by itself, with a two-letter ISO-639 -language code following (list is included below). If you have a -multilingual document, the intent is to be able to use this command -multiple times, to declare each language change. If the command is not -used at all, the default is @code{en} for English. - -@cindex @file{txi-@var{cc}.tex} -At present, this command is ignored in Info and HTML output. For -@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it -exists). Such a file appropriately redefines the various English words -used in @TeX{} output, such as `Chapter', `See', and so on. - -@cindex Hyphenation patterns, language-dependent -It would be good if this command also changed @TeX{}'s ideas of the -current hyphenation patterns (via the @TeX{} primitive -@code{\language}), but this is unfortunately not currently implemented. - -@cindex ISO 639 codes -@cindex Language codes -@cindex African languages -Here is the list of valid language codes. This list comes from -@uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free -translation project}. In the future we may wish to allow the 3-letter -POV codes described at @uref{http://www.sil.org/ethnologue/#contents}. -This will be necessary to support African languages. - -@multitable @columnfractions .06 .27 .06 .27 .06 .27 -@item -@code{aa} @tab Afar @tab -@code{ab} @tab Abkhazian @tab -@code{af} @tab Afrikaans -@item -@code{am} @tab Amharic @tab -@code{ar} @tab Arabic @tab -@code{as} @tab Assamese -@item -@code{ay} @tab Aymara @tab -@code{az} @tab Azerbaijani @tab -@code{ba} @tab Bashkir -@item -@code{be} @tab Byelorussian @tab -@code{bg} @tab Bulgarian @tab -@code{bh} @tab Bihari -@item -@code{bi} @tab Bislama @tab -@code{bn} @tab Bengali; Bangla @tab -@code{bo} @tab Tibetan -@item -@code{br} @tab Breton @tab -@code{ca} @tab Catalan @tab -@code{co} @tab Corsican -@item -@code{cs} @tab Czech @tab -@code{cy} @tab Welsh @tab -@code{da} @tab Danish -@item -@code{de} @tab German @tab -@code{dz} @tab Bhutani @tab -@code{el} @tab Greek -@item -@code{en} @tab English @tab -@code{eo} @tab Esperanto @tab -@code{es} @tab Spanish -@item -@code{et} @tab Estonian @tab -@code{eu} @tab Basque @tab -@code{fa} @tab Persian -@item -@code{fi} @tab Finnish @tab -@code{fj} @tab Fiji @tab -@code{fo} @tab Faroese -@item -@code{fr} @tab French @tab -@code{fy} @tab Frisian @tab -@code{ga} @tab Irish -@item -@code{gd} @tab Scots Gaelic @tab -@code{gl} @tab Galician @tab -@code{gn} @tab Guarani -@item -@code{gu} @tab Gujarati @tab -@code{ha} @tab Hausa @tab -@code{he} @tab Hebrew -@item -@code{hi} @tab Hindi @tab -@code{hr} @tab Croatian @tab -@code{hu} @tab Hungarian -@item -@code{hy} @tab Armenian @tab -@code{ia} @tab Interlingua @tab -@code{id} @tab Indonesian -@item -@code{ie} @tab Interlingue @tab -@code{ik} @tab Inupiak @tab -@code{is} @tab Icelandic -@item -@code{it} @tab Italian @tab -@code{iu} @tab Inuktitut @tab -@code{ja} @tab Japanese -@item -@code{jw} @tab Javanese @tab -@code{ka} @tab Georgian @tab -@code{kk} @tab Kazakh -@item -@code{kl} @tab Greenlandic @tab -@code{km} @tab Cambodian @tab -@code{kn} @tab Kannada -@item -@code{ks} @tab Kashmiri @tab -@code{ko} @tab Korean @tab -@code{ku} @tab Kurdish -@item -@code{ky} @tab Kirghiz @tab -@code{la} @tab Latin @tab -@code{ln} @tab Lingala -@item -@code{lt} @tab Lithuanian @tab -@code{lo} @tab Laothian @tab -@code{lv} @tab Latvian, Lettish -@item -@code{mg} @tab Malagasy @tab -@code{mi} @tab Maori @tab -@code{mk} @tab Macedonian -@item -@code{ml} @tab Malayalam @tab -@code{mn} @tab Mongolian @tab -@code{mo} @tab Moldavian -@item -@code{mr} @tab Marathi @tab -@code{ms} @tab Malay @tab -@code{mt} @tab Maltese -@item -@code{my} @tab Burmese @tab -@code{na} @tab Nauru @tab -@code{ne} @tab Nepali -@item -@code{nl} @tab Dutch @tab -@code{no} @tab Norwegian @tab -@code{oc} @tab Occitan -@item -@code{om} @tab (Afan) Oromo @tab -@code{or} @tab Oriya @tab -@code{pa} @tab Punjabi -@item -@code{pl} @tab Polish @tab -@code{ps} @tab Pashto, Pushto @tab -@code{pt} @tab Portuguese -@item -@code{qu} @tab Quechua @tab -@code{rm} @tab Rhaeto-Romance @tab -@code{rn} @tab Kirundi -@item -@code{ro} @tab Romanian @tab -@code{ru} @tab Russian @tab -@code{rw} @tab Kinyarwanda -@item -@code{sa} @tab Sanskrit @tab -@code{sd} @tab Sindhi @tab -@code{sg} @tab Sangro -@item -@code{sh} @tab Serbo-Croatian @tab -@code{si} @tab Sinhalese @tab -@code{sk} @tab Slovak -@item -@code{sl} @tab Slovenian @tab -@code{sm} @tab Samoan @tab -@code{sn} @tab Shona -@item -@code{so} @tab Somali @tab -@code{sq} @tab Albanian @tab -@code{sr} @tab Serbian -@item -@code{ss} @tab Siswati @tab -@code{st} @tab Sesotho @tab -@code{su} @tab Sundanese -@item -@code{sv} @tab Swedish @tab -@code{sw} @tab Swahili @tab -@code{ta} @tab Tamil -@item -@code{te} @tab Telugu @tab -@code{tg} @tab Tajik @tab -@code{th} @tab Thai -@item -@code{ti} @tab Tigrinya @tab -@code{tk} @tab Turkmen @tab -@code{tl} @tab Tagalog -@item -@code{tn} @tab Setswana @tab -@code{to} @tab Tonga @tab -@code{tr} @tab Turkish -@item -@code{ts} @tab Tsonga @tab -@code{tt} @tab Tatar @tab -@code{tw} @tab Twi -@item -@code{ug} @tab Uighur @tab -@code{uk} @tab Ukrainian @tab -@code{ur} @tab Urdu -@item -@code{uz} @tab Uzbek @tab -@code{vi} @tab Vietnamese @tab -@code{vo} @tab Volapuk -@item -@code{wo} @tab Wolof @tab -@code{xh} @tab Xhosa @tab -@code{yi} @tab Yiddish -@item -@code{yo} @tab Yoruba @tab -@code{za} @tab Zhuang @tab -@code{zh} @tab Chinese -@item -@code{zu} @tab Zulu -@end multitable - - -@node documentencoding -@section @code{@@documentencoding @var{enc}}: Set Input Encoding +not need to rewrite the three sections. -@findex documentencoding -@cindex Encoding, declaring -@cindex Input encoding, declaring -@cindex Document input encoding -The @code{@@documentencoding} command declares the input document -encoding. Write it on a line by itself, with a valid encoding -specification following, such as @samp{ISO-8859-1}. - -@cindex http-equiv, and charset -@cindex meta HTML tag, and charset -At present, this is used only in HTML output from @code{makeinfo}. If a -document encoding @var{enc} is specified, it is used in the -@samp{} tag is included in the @samp{} of the output: - -@example - -@end example - - -@node Defining New Texinfo Commands -@chapter Defining New Texinfo Commands +@node Macros, Format/Print Hardcopy, Conditionals, Top +@chapter Macros: Defining New Texinfo Commands @cindex Macros @cindex Defining new Texinfo commands @cindex New Texinfo commands, defining @cindex Texinfo commands, defining new @cindex User-defined Texinfo commands -Texinfo provides several ways to define new commands: - -@itemize @bullet -@item A Texinfo @dfn{macro} allows you to define a new Texinfo command as any sequence of text and/or existing commands (including other macros). The macro can have any number of @dfn{parameters}---text you supply each -time you use the macro. - -Incidentally, these macros have nothing to do with the @code{@@defmac} -command, which is for documenting macros in the subject of the manual -(@pxref{Def Cmd Template}). - -@item -@samp{@@alias} is a convenient way to define a new name for an existing -command. - -@item -@samp{@@definfoenclose} allows you to define new commands with -customized output in the Info file. - -@end itemize +time you use the macro. (This has nothing to do with the +@code{@@defmac} command, which is for documenting macros in the subject +of the manual; @pxref{Def Cmd Template}.) @menu -* Defining Macros:: Defining and undefining new commands. +* Defining Macros:: Both defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Beyond basic macro usage. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. @end menu -@node Defining Macros +@node Defining Macros, Invoking Macros, Macros, Macros @section Defining Macros @cindex Defining macros @cindex Macro definitions -@cindex Definitions, a.k.a.@: macros @findex macro -You use the Texinfo @code{@@macro} command to define a macro, like this: +You use the Texinfo @code{@@macro} command to define a macro. For example: @example -@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@} +@@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@} @var{text} @dots{} \@var{param1}\ @dots{} @@end macro @end example The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to arguments supplied when the macro is subsequently used in the document -(described in the next section). - -For a macro to work with @TeX{}, @var{macroname} must consist entirely -of letters: no digits, hyphens, underscores, or other special characters. +(see the next section). If a macro needs no parameters, you can define it either with an empty list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro @@ -12324,44 +11822,12 @@ foo}). @cindex Body of a macro @cindex Mutually recursive macros @cindex Recursion, mutual -The definition or @dfn{body} of the macro can contain most Texinfo -commands, including previously-defined macros. Not-yet-defined macro -invocations are not allowed; thus, it is not possible to have mutually -recursive Texinfo macros. Also, a macro definition that defines another -macro does not work in @TeX{} due to limitations in the design of -@code{@@macro}. - -@cindex Parameters to macros -In the macro body, instances of a parameter name surrounded by -backslashes, as in @samp{\@var{param1}\} in the example above, are -replaced by the corresponding argument from the macro invocation. You -can use parameter names any number of times in the body, including zero. - -@cindex Backslash in macros -To get a single @samp{\} in the macro expansion, use @samp{\\}. Any -other use of @samp{\} in the body yields a warning. - -@cindex Spaces in macros -@cindex Whitespace in macros -The newlines after the @code{@@macro} line and before the @code{@@end -macro} line are ignored, that is, not included in the macro body. All -other whitespace is treated according to the usual Texinfo rules. - -@cindex Recursive macro invocations -@findex rmacro -To allow a macro to be used recursively, that is, in an argument to a -call to itself, you must define it with @samp{@@rmacro}, like this: - -@example -@@rmacro rmac -a\arg\b -@@end rmacro -@dots{} -@@rmac@{1@@rmac@{text@}2@} -@end example - -This produces the output `a1atextb2b'. With @samp{@@macro} instead of -@samp{@@rmacro}, an error message is given. +The definition or @dfn{body} of the macro can contain any Texinfo +commands, including previously-defined macros. (It is not possible to +have mutually recursive Texinfo macros.) In the body, instances of a +parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in +the example above, are replaced by the corresponding argument from the +macro invocation. @findex unmacro @cindex Macros, undefining @@ -12375,22 +11841,21 @@ For example: @end example -@node Invoking Macros +@node Invoking Macros, , Defining Macros, Macros @section Invoking Macros @cindex Invoking macros -@cindex Expanding macros -@cindex Running macros @cindex Macro invocation After a macro is defined (see the previous section), you can use (@dfn{invoke}) it in your document like this: @example -@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} +@@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@} @end example -@noindent and the result will be just as if you typed the body of -@var{macroname} at that spot. For example: +@noindent +and the result will be just as if you typed the body of +@var{macro-name} at that spot. For example: @example @@macro foo @{p, q@} @@ -12399,242 +11864,50 @@ Together: \p\ & \q\. @@foo@{a, b@} @end example -@noindent produces: - -@display -Together: a & b. -@end display - -@cindex Backslash, and macros -Thus, the arguments and parameters are separated by commas and delimited -by braces; any whitespace after (but not before) a comma is ignored. -The braces are required in the invocation (but not the definition), even -when the macro takes no arguments, consistent with all other Texinfo -commands. For example: - -@example -@@macro argless @{@} -No arguments here. -@@end macro -@@argless@{@} -@end example - -@noindent produces: - -@display -No arguments here. -@end display - -To insert a comma, brace, or backslash in an argument, prepend a -backslash, as in - -@example -@@@var{macname} @{\\\@{\@}\,@} -@end example - @noindent -which will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macname}. - -If the macro is defined to take a single argument, and is invoked -without any braces, the entire rest of the line after the macro name is -supplied as the argument. For example: - -@example -@@macro bar @{p@} -Twice: \p\ & \p\. -@@end macro -@@bar aah -@end example - -@noindent produces: - -@c Sorry for cheating, but let's not require macros to process the manual. -@display -Twice: aah & aah. -@end display - -If the macro is defined to take a single argument, and is invoked with -braces, the braced text is passed as the argument, regardless of -commas. For example: - -@example -@@macro bar @{p@} -Twice: \p\ & \p\. -@@end macro -@@bar@{a,b@} -@end example - -@noindent produces: +produces: @display -Twice: a,b & a,b. +Together: a & b. @end display - -@node Macro Details -@section Macro Details -@cindex Macro details -@cindex Details of macro usage - -Due to unavoidable disparities in the @TeX{} and @command{makeinfo} -implementations, Texinfo macros have the following limitations. - -@itemize @bullet -@item -All macros are expanded inside at least one @TeX{} group. This means -that @set and other such commands will have no effect inside a macro. - -@item -Macros containing a command which must be on a line by itself, such as a -conditional, cannot be invoked in the middle of a line. - -@item -The @TeX{} implementation cannot construct macros that define macros in -the natural way. To do this, you must use conditionals and raw @TeX{}. -For example: - -@example -@@ifinfo -@@macro ctor @{name, arg@} -@@macro \name\ -something involving \arg\ somehow -@@end macro -@@end macro -@@end ifinfo -@@tex -\gdef\ctor#1@{\ctorx#1,@} -\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} -@@end tex -@end example - -@item -It is best to avoid comments inside macro definitions. - -@end itemize - - -@node alias -@section @samp{@@alias @var{new}=@var{existing}} -@cindex Aliases, command -@cindex Command aliases -@findex alias - -The @samp{@@alias} command defines a new command to be just like an -existing one. This is useful for defining additional markup names, thus -preserving semantic information in the input even though the output -result may be the same. - -Write the @samp{@@alias} command on a line by itself, followed by the -new command name, an equals sign, and the existing command name. -Whitespace around the equals sign is ignored. Thus: -@example -@@alias @var{new} = @var{existing} -@end example - -For example, if your document contains citations for both books and -some other media (movies, for example), you might like to define a -macro @code{@@moviecite@{@}} that does the same thing as an ordinary -@code{@@cite@{@}} but conveys the extra semantic information as well. -You'd do this as follows: - -@example -@@alias moviecite = cite -@end example - -Macros do not always have the same effect due to vagaries of argument -parsing. Also, aliases are much simpler to define than macros. So the -command is not redundant. (It was also heavily used in the Jargon File!) - -Aliases must not be recursive, directly or indirectly. - -@node definfoenclose -@section @samp{definfoenclose}: Customized Highlighting -@cindex Highlighting, customized -@cindex Customized highlighting -@findex definfoenclose - -A @code{@@definfoenclose} command may be used to define a highlighting -command for Info, but not for TeX. A command defined using -@code{@@definfoenclose} marks text by enclosing it in strings that -precede and follow the text. You can use this to get closer control of -your Info output. - -Presumably, if you define a command with @code{@@definfoenclose} for Info, -you will create a corresponding command for @TeX{}, either in -@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in -your document. - -Write a @code{@@definfoenclose} command on a line and follow it with -three arguments separated by commas. The first argument to -@code{@@definfoenclose} is the @@-command name (without the @code{@@}); -the second argument is the Info start delimiter string; and the third -argument is the Info end delimiter string. The latter two arguments -enclose the highlighted text in the Info file. A delimiter string may -contain spaces. Neither the start nor end delimiter is required. If -you do not want a start delimiter but do want an end delimiter, you must -follow the command name with two commas in a row; otherwise, the Info -formatting commands will naturally misinterpret the end delimiter string -you intended as the start delimiter string. - -If you do a @code{@@definfoenclose} on the name of a pre-defined macro -(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the -enclosure definition will override the built-in definition. - -An enclosure command defined this way takes one argument in braces; this -is intended for new markup commands (@pxref{Marking Text}). - -@findex phoo -For example, you can write: - -@example -@@definfoenclose phoo,//,\\ -@end example - -@noindent -near the beginning of a Texinfo file to define @code{@@phoo} as an Info -formatting command that inserts `//' before and `\\' after the argument -to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you -want `//bar\\' highlighted in Info. - -Also, for TeX formatting, you could write +@cindex Backslash, and macros +Thus, the arguments and parameters are separated by commas and delimited +by braces; any whitespace after (but not before) a comma is ignored. To +insert a comma, brace, or backslash in an argument, prepend a backslash, +as in @example -@@iftex -@@global@@let@@phoo=@@i -@@end iftex +@@@var{macro-name} @{\\\@{\@}\,@} @end example @noindent -to define @code{@@phoo} as a command that causes TeX to typeset the -argument to @code{@@phoo} in italics. - -Note that each definition applies to its own formatter: one for TeX, -the other for @code{texinfo-format-buffer} or -@code{texinfo-format-region}. The @code{@@definfoenclose} command need -not be within @samp{@@ifinfo}, but the raw @TeX{} commands do need to be -in @samp{@@iftex}. +which will pass the (almost certainly error-producing) argument +@samp{\@{@},} to @var{macro-name}. -@findex headword -Here is another example: write +If the macro is defined to take a single argument, and is invoked +without any braces, the entire rest of the line after the macro name is +supplied as the argument. For example: @example -@@definfoenclose headword, , : +@@macro bar @{p@} +Twice: \p\, \p\. +@@end macro +@@bar aah @end example @noindent -near the beginning of the file, to define @code{@@headword} as an Info -formatting command that inserts nothing before and a colon after the -argument to @code{@@headword}. +produces: -@samp{@@definfoenclose} definitions must not be recursive, directly or -indirectly. +@display +Twice: aah, aah. +@end display -@node Hardcopy -@chapter Formatting and Printing Hardcopy +@node Format/Print Hardcopy, Create an Info File, Macros, Top +@comment node-name, next, previous, up +@chapter Format and Print Hardcopy @cindex Format and print hardcopy -@cindex Printing hardcopy @cindex Hardcopy, printing it @cindex Making a printed manual @cindex Sorting indices @@ -12647,49 +11920,49 @@ Texinfo file: one for converting the Texinfo file into a file that will be printed, a second for sorting indices, and a third for printing the formatted document. When you use the shell commands, you can either work directly in the operating system shell or work within a shell -inside GNU Emacs. +inside GNU Emacs.@refill If you are using GNU Emacs, you can use commands provided by Texinfo mode instead of shell commands. In addition to the three commands to format a file, sort the indices, and print the result, Texinfo mode offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue. +print queue, and delete a job from the print queue.@refill @menu * Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. +* Format with tex/texindex:: How to format in a shell. +* Format with texi2dvi:: A simpler way to use the shell. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What to do before you use @TeX{}. +* Preparing for TeX:: What you need to do to use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on European A4 paper. -* pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. @end menu -@node Use TeX -@section Use @TeX{} +@node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy +@ifinfo +@heading Use @TeX{} +@end ifinfo The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, if used correctly, +file. @TeX{} is a very powerful typesetting program and, if used right, does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain @TeX{}}, for information on how to obtain @TeX{}.) The @code{makeinfo}, @code{texinfo-format-region}, and @code{texinfo-format-buffer} commands read the very same @@-commands in the Texinfo file as does @TeX{}, but process them differently to -make an Info file (@pxref{Creating an Info File}). +make an Info file; see @ref{Create an Info File}.@refill - -@node Format with tex/texindex -@section Format with @code{tex} and @code{texindex} +@node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Format using @code{tex} and @code{texindex} @cindex Shell formatting with @code{tex} and @code{texindex} @cindex Formatting with @code{tex} and @code{texindex} @cindex DVI file @@ -12701,23 +11974,23 @@ the name of the Texinfo file. For example: tex foo.texi @end example -@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary +@noindent +@TeX{} will produce a @dfn{DVI file} as well as several auxiliary files containing information for indices, cross references, etc. The DVI file (for @dfn{DeVice Independent} file) can be printed on virtually -any device (see the following sections). +any printe (see the following sections). @pindex texindex The @code{tex} formatting command itself does not sort the indices; it writes an output file of unsorted index data. (The @code{texi2dvi} -command automatically generates indices; @pxref{Format with texi2dvi,, -Format with @code{texi2dvi}}.) To generate a printed index after +command automatically generates indices; see @ref{Format with texi2dvi,, +Format using @code{texi2dvi}}.) To generate a printed index after running the @code{tex} command, you first need a sorted index to work from. The @code{texindex} command sorts indices. (The source file @file{texindex.c} comes as part of the standard Texinfo distribution, among other places.)@refill @cindex Names of index files -@cindex Index file names The @code{tex} formatting command outputs unsorted index files under names that obey a standard convention: the name of your main input file with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c, @@ -12725,14 +11998,14 @@ Web2c}) extension removed, followed by the two letter names of indices. For example, the raw index output files for the input file @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the -arguments to give to @code{texindex}. +arguments to give to @code{texindex}.@refill @need 1000 @cindex Wildcards @cindex Globbing Instead of specifying all the unsorted index file names explicitly, you can use @samp{??} as shell wildcards and give the command in this -form: +form:@refill @example texindex foo.?? @@ -12744,13 +12017,13 @@ including any that you have defined yourself using @code{@@defindex} or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} even if there are similarly named files with two letter extensions that are not index files, such as @samp{foo.el}. The @code{texindex} -command reports but otherwise ignores such files.) +command reports but otherwise ignores such files.)@refill For each file specified, @code{texindex} generates a sorted index file whose name is made by appending @samp{s} to the input file name. The -@code{@@printindex} command looks for a file with that name +@code{@@printindex} command knows to look for a file of that name (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the -raw index output file. +raw index output file.@refill After you have sorted the indices, you need to rerun the @code{tex} formatting command on the Texinfo file. This regenerates the DVI file, @@ -12759,7 +12032,7 @@ this time with up-to-date index entries. Finally, you may need to run @code{tex} one more time, to get the page numbers in the cross-references correct. -To summarize, this is a five step process: +To summarize, this is a four step process: @enumerate @item @@ -12777,84 +12050,43 @@ file, this time with indices and defined cross-references, but with page numbers for the cross-references from last time, generally incorrect. @item -Sort the indices again, with @code{texindex}. - -@item Run @code{tex} one last time. This time the correct page numbers are written for the cross-references. @end enumerate @pindex texi2dvi -Alternatively, it's a one-step process: run @code{texi2dvi} -(@pxref{Format with texi2dvi}). +Alternatively, it's a one-step process: run @code{texi2dvi}. You need not run @code{texindex} each time after you run @code{tex}. If you do not, on the next run, the @code{tex} formatting command will use whatever sorted index files happen to exist from the previous use of -@code{texindex}. This is usually ok while you are debugging. - -@cindex Auxiliary files, avoiding -@findex novalidate -@cindex Pointer validation, suppressing -@cindex Chapters, formatting one at a time -Sometimes you may wish to print a document while you know it is -incomplete, or to print just one chapter of a document. In that case, -the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives -when cross-references are not satisfied are just nuisances. You can -avoid them with the @code{@@novalidate} command, which you must give -@emph{before} the @code{@@setfilename} command -(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of -your file would look approximately like this: - -@example -\input texinfo -@@novalidate -@@setfilename myfile.info -@dots{} -@end example +@code{texindex}. This is usually ok while you are +debugging.@refill -@noindent @code{@@novalidate} also turns off validation in -@code{makeinfo}, just like its @code{--no-validate} option -(@pxref{Pointer Validation}). - -@node Format with texi2dvi -@section Format with @code{texi2dvi} +@node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Format using @code{texi2dvi} @pindex texi2dvi @r{(shell script)} The @code{texi2dvi} command automatically runs both @code{tex} and @code{texindex} as many times as necessary to produce a DVI file with -sorted indices and all cross-references resolved. It simplifies the -@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence -described in the previous section. +up-to-date, sorted indices. It simplifies the +@code{tex}---@code{texindex}---@code{tex} sequence described in the +previous section. -To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where -@samp{prompt$ } is your shell prompt): +The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your +shell prompt):@refill @example -prompt$ @kbd{texi2dvi foo.texi} +prompt$ @kbd{texi2dvi @var{filename}@dots{}} @end example -As shown in this example, the input filenames to @code{texi2dvi} must -include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under -MS-DOS and perhaps in other circumstances, you may need to run @samp{sh -texi2dvi foo.texi} instead of relying on the operating system to invoke -the shell on the @samp{texi2dvi} script. +For a list of options, run @samp{texi2dvi --help}. -Perhaps the most useful option to @code{texi2dvi} is -@samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself -after the @code{@@setfilename} in a temporary copy of the input file -before running @TeX{}. With this, you can specify different printing -formats, such as @code{@@smallbook} (@pxref{smallbook}), -@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pageparams} -(@pxref{pagesizes}), without actually changing the document source. -(You can also do this on a site-wide basis with @file{texinfo.cnf}; -@pxref{Preparing for TeX,,Preparing for @TeX{}}). -For a list of other options, run @samp{texi2dvi --help}. - - -@node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy +@node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy +@comment node-name, next, previous, up @section Shell Print Using @code{lpr -d} @pindex lpr @r{(DVI print command)} @@ -12863,7 +12095,7 @@ installation, but @samp{lpr -d} is common. The command may require the DVI file name without any extension or with a @samp{.dvi} extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.) -For example, the following commands, will (perhaps) suffice to sort the +The following commands, for example, will (probably) suffice to sort the indices, format, and print the @cite{Bison Manual}: @example @@ -12889,41 +12121,8 @@ lpr -d bison.dvi @end group @end example -@cindex Shell printing, on MS-DOS/MS-Windows -@cindex Printing DVI files, on MS-DOS/MS-Windows -@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows} -@code{lpr} is a standard program on Unix systems, but it is usually -absent on MS-DOS/MS-Windows. Some network packages come with a -program named @code{lpr}, but these are usually limited to sending files -to a print server over the network, and generally don't support the -@samp{-d} option. If you are unfortunate enough to work on one of these -systems, you have several alternative ways of printing DVI files: - -@itemize @bullet{} -@item Find and install a Unix-like @code{lpr} program, or its clone. -If you can do that, you will be able to print DVI files just like -described above. - -@item Send the DVI files to a network printer queue for DVI files. -Some network printers have special queues for printing DVI files. You -should be able to set up your network software to send files to that -queue. In some cases, the version of @code{lpr} which comes with your -network software will have a special option to send a file to specific -queues, like this: - -@example -lpr -Qdvi -hprint.server.domain bison.dvi -@end example - -@item Convert the DVI file to a Postscript or PCL file and send it to your -local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man -pages for @code{dvilj}, for detailed description of these tools. Once -the DVI file is converted to the format your local printer understands -directly, just send it to the appropriate port, usually @samp{PRN}. -@end itemize - - -@node Within Emacs +@node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy +@comment node-name, next, previous, up @section From an Emacs Shell @cindex Print, format from Emacs shell @cindex Format, print from Emacs shell @@ -12933,8 +12132,8 @@ directly, just send it to the appropriate port, usually @samp{PRN}. You can give formatting and printing commands from a shell within GNU Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Hardcopy, , Format -and Print Hardcopy}, for details. +shell, you can format and print the document. @xref{Format/Print +Hardcopy, , Format and Print Hardcopy}, for details.@refill You can switch to and from the shell buffer while @code{tex} is running and do other editing. If you are formatting a long document @@ -12956,8 +12155,7 @@ lpr -d gcc.dvi and printing in Texinfo mode.@refill @end ifinfo - -@node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy +@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy @section Formatting and Printing in Texinfo Mode @cindex Region printing in Texinfo mode @cindex Format and print in Texinfo mode @@ -13000,7 +12198,7 @@ number shown by a preceding @kbd{C-c C-t C-q} command @item C-c C-t C-k @itemx M-x tex-kill-job -Kill the currently running @TeX{} job started by either +Kill the currently running @TeX{} job started by @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other process running in the Texinfo shell buffer.@refill @@ -13059,22 +12257,13 @@ tex-show-queue-command "lpq" You can change the values of these variables with the @kbd{M-x edit-options} command (@pxref{Edit Options, , Editing Variable Values, -emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command -(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU -Emacs Manual}), or with your @file{.emacs} initialization file -(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill - -@cindex Customize Emacs package -@findex Development/Docs/Texinfo Customize group -Beginning with version 20, GNU Emacs offers a user-friendly interface, -called @dfn{Customize}, for changing values of user-definable variables. -@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU -Emacs Manual}, for more details about this. The Texinfo variables can -be found in the @samp{Development/Docs/Texinfo} group, once you invoke -the @kbd{M-x customize} command. - - -@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy +xemacs, XEmacs User's Manual}), with the @kbd{M-x set-variable} command +(@pxref{Examining, , Examining and Setting Variables, xemacs, XEmacs +User's Manual}), or with your @file{.emacs} initialization file +(@pxref{Init File, , , xemacs, XEmacs User's Manual}).@refill + +@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy +@comment node-name, next, previous, up @section Using the Local Variables List @cindex Local variables @cindex Compile command for formatting @@ -13099,10 +12288,11 @@ End: @noindent This technique is most often used by programmers who also compile programs -this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill +this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill -@node Requirements Summary +@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy +@comment node-name, next, previous, up @section @TeX{} Formatting Requirements Summary @cindex Requirements for formatting @cindex Minimal requirements for formatting @@ -13113,7 +12303,7 @@ Every Texinfo file that is to be input to @TeX{} must begin with a @example \input texinfo -@@setfilename @var{arg-not-used-by-@TeX{}} +@@setfilename @var{arg-not-used-by-@@TeX@{@}} @end example @noindent @@ -13128,7 +12318,7 @@ processing and forces out unfinished pages: @end example Strictly speaking, these lines are all a Texinfo file needs to be -processed successfully by @TeX{}. +processed successfully by @TeX{}. Usually, however, the beginning includes an @code{@@settitle} command to define the title of the printed manual, an @code{@@setchapternewpage} @@ -13136,20 +12326,31 @@ command, a title page, a copyright page, and permissions. Besides an @code{@@bye}, the end of a file usually includes indices and a table of contents. (And of course most manuals contain a body of text as well.) -For more information, see: -@itemize @bullet -@item @ref{settitle, , @code{@@settitle}} -@item @ref{setchapternewpage, , @code{@@setchapternewpage}} -@item @ref{Headings, ,Page Headings} -@item @ref{Titlepage & Copyright Page} -@item @ref{Printing Indices & Menus} -@item @ref{Contents} -@end itemize +@iftex +For more information, see +@ref{settitle, , @code{@@settitle}}, +@ref{setchapternewpage, , @code{@@setchapternewpage}}, +@ref{Headings, ,Page Headings}, +@ref{Titlepage & Copyright Page}, +@ref{Printing Indices & Menus}, and +@ref{Contents}. +@end iftex +@noindent +@ifinfo +For more information, see@* +@ref{settitle, , @code{@@settitle}},@* +@ref{setchapternewpage, , @code{@@setchapternewpage}},@* +@ref{Headings, ,Page Headings},@* +@ref{Titlepage & Copyright Page},@* +@ref{Printing Indices & Menus}, and@* +@ref{Contents}. +@end ifinfo -@node Preparing for TeX -@section Preparing for @TeX{} -@cindex Preparing for @TeX{} +@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Preparing to Use @TeX{} +@cindex Preparing to use @TeX{} @cindex @TeX{} input initialization @cindex @code{TEXINPUTS} environment variable @vindex TEXINPUTS @@ -13182,14 +12383,14 @@ distribution. This file is needed to support the @code{@@image} command @cindex Customizing of @TeX{} for Texinfo @cindex Site-wide Texinfo configuration file Optionally, you may create an additional @file{texinfo.cnf}, and install -it as well. This file is read by @TeX{} when the @code{@@setfilename} -command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any -commands you like there, according to local site-wide conventions. They -will be read by @TeX{} when processing any Texinfo document. For -example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper} -(@pxref{A4 Paper}), then all Texinfo documents will be processed with -that page size in effect. If you have nothing to put in -@file{texinfo.cnf}, you do not need to create it. +it as well. This file is read by @TeX{} at the @code{@@setfilename} +command (@pxref{setfilename,, @code{@@setfilename}}). You can put any +commands you like there according to local site-wide conventions, and +they will be read by @TeX{} when processing any Texinfo document. For +example, if @file{texinfo.cnf} contains the a single line +@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will +be processed with that page size in effect. If you have nothing to put +in @file{texinfo.cnf}, you do not need to create it. @vindex TEXINPUTS If neither of the above locations for these system files suffice for @@ -13224,45 +12425,14 @@ export TEXINPUTS @end group @end example -On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use -of the @samp{;} character, instead of @samp{:}, as directory separator -on these systems.}: - -@example -@group -set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros -@end group -@end example - @noindent -It is customary for DOS/Windows users to put such commands in the -@file{autoexec.bat} file, or in the Windows Registry.@refill +This would cause @TeX{} to look for @file{\input} file first in the current +directory, indicated by the @samp{.}, then in a hypothetical user's +@file{me/mylib} directory, and finally in a system directory. -@noindent -These settings would cause @TeX{} to look for @file{\input} file first -in the current directory, indicated by the @samp{.}, then in a -hypothetical user's @file{me/mylib} directory, and finally in a system -directory @file{/usr/lib/tex/macros}. - -@cindex Dumping a .fmt file -@cindex Format file, dumping -Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, -web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The -disadvantage is that then updating @file{texinfo.tex} requires -redumping.) You can do this by running this command, assuming -@file{epsf.tex} is findable by @TeX{}: - -@example -initex texinfo @@dump -@end example - -(@code{@@dump} is a @TeX{} primitive.) You'll then need to move -@file{texinfo.fmt} to wherever your @code{.fmt} files are found; -typically this will be in the subdirectory @file{web2c} of your @TeX{} -installation, for example, @file{/usr/local/share/tex/web2c}. - -@node Overfull hboxes +@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy +@comment node-name, next, previous, up @section Overfull ``hboxes'' @cindex Overfull @samp{hboxes} @cindex @samp{hboxes}, overfull @@ -13272,67 +12442,46 @@ installation, for example, @file{/usr/local/share/tex/web2c}. the right margin. This can occur when @TeX{} comes upon what it interprets as a long word that it cannot hyphenate, such as an electronic mail network address or a very long title. When this -happens, @TeX{} prints an error message like this: +happens, @TeX{} prints an error message like this:@refill @example -Overfull @@hbox (20.76302pt too wide) +Overfull \hbox (20.76302pt too wide) @end example -@findex hbox @noindent (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. -@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.) +The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill @TeX{} also provides the line number in the Texinfo source file and the text of the offending line, which is marked at all the places that -@TeX{} considered hyphenation. +@TeX{} knows how to hyphenate words. @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -for more information about typesetting errors. +for more information about typesetting errors.@refill If the Texinfo file has an overfull hbox, you can rewrite the sentence so the overfull hbox does not occur, or you can decide to leave it. A small excursion into the right margin often does not matter and may not -even be noticeable. - -If you have many overfull boxes and/or an antipathy to rewriting, you -can coerce @TeX{} into greatly increasing the allowable interword -spacing, thus (if you're lucky) avoiding many of the bad line breaks, -like this: - -@findex \emergencystretch -@example -@@tex -\global\emergencystretch = .9\hsize -@@end tex -@end example - -@noindent -(You can adjust the fraction as needed.) This huge value for -@code{\emergencystretch} cannot be the default, since then the typeset -output would generally be of noticeably lower quality. The default -value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension -containing the current line width. +even be noticeable.@refill @cindex Black rectangle in hardcopy -@cindex Rectangle, black in hardcopy -@cindex Box, ugly black in hardcopy -@cindex Ugly black rectangles in hardcopy -For what overfull boxes you have, however, @TeX{} will print a large, -ugly, black rectangle beside the line that contains the overfull hbox -unless told otherwise. This is so you will notice the location of the -problem if you are correcting a draft. +@cindex Rectangle, ugly, black in hardcopy +However, unless told otherwise, @TeX{} will print a large, ugly, black +rectangle beside the line that contains the overfull hbox. This is so +you will notice the location of the problem if you are correcting a +draft.@refill +@need 1000 @findex finalout To prevent such a monstrosity from marring your final printout, write the following in the beginning of the Texinfo file on a line of its own, -before the @code{@@titlepage} command: +before the @code{@@titlepage} command:@refill @example @@finalout @end example - -@node smallbook +@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy +@comment node-name, next, previous, up @section Printing ``Small'' Books @findex smallbook @cindex Small book size @@ -13351,35 +12500,43 @@ file, before the title page:@refill @end example @noindent -(Since many books are about 7 by 9.25 inches, this command might better -have been called the @code{@@regularbooksize} command, but it came to be -called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.) +(Since regular sized books are often about 7 by 9.25 inches, this +command might better have been called the @code{@@regularbooksize} +command, but it came to be called the @code{@@smallbook} command by +comparison to the 8.5 by 11 inch format.)@refill If you write the @code{@@smallbook} command between the start-of-header and end-of-header lines, the Texinfo mode @TeX{} region formatting command, @code{texinfo-tex-region}, will format the region in ``small'' book size (@pxref{Start of Header}).@refill -@xref{small}, for information about -commands that make it easier to produce examples for a smaller manual. +The Free Software Foundation distributes printed copies of @cite{The GNU +Emacs Manual} and other manuals in the ``small'' book size. +@xref{smallexample & smalllisp, , @code{@@smallexample} and +@code{@@smalllisp}}, for information about commands that make it easier +to produce examples for a smaller manual.@refill -@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to format with @code{@@smallbook} that do not -require changing the source file. +Alternatively, to avoid embedding this physical paper size in your +document, use @code{texi2dvi} to format your document (@pxref{Format +with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then +other people do not have to change the document source file to format it +differently. -@node A4 Paper +@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy +@comment node-name, next, previous, up @section Printing on A4 Paper @cindex A4 paper, printing on @cindex Paper size, European A4 @cindex European A4 paper @findex afourpaper -You can tell @TeX{} to format a document for printing on European size +You can tell @TeX{} to typeset a document for printing on European size A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself near the beginning of the Texinfo file, before the title -page. For example, this is how you would write the header for this -manual: +line by itself between @code{@@iftex} and @code{@@end iftex} lines near +the beginning of the Texinfo file, before the title page:@refill + +For example, this is how you would write the header for this manual:@refill @example @group @@ -13387,70 +12544,35 @@ manual: @@c %**start of header @@setfilename texinfo @@settitle Texinfo +@@syncodeindex vr fn +@@iftex @@afourpaper +@@end iftex @@c %**end of header @end group @end example -@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to format with @code{@@afourpaper} that do not -require changing the source file. - -@findex afourlatex -You may or may not prefer the formatting that results from the command -@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in -wide format. - - -@node pagesizes -@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes -@findex pagesizes -@cindex Custom page sizes -@cindex Page sizes, customized -@cindex Text width and height -@cindex Width of text area -@cindex Height of text area -@cindex Depth of text area - -You can explicitly specify the height and (optionally) width of the main -text area on the page with the @code{@@pagesizes} command. Write this -on a line by itself near the beginning of the Texinfo file, before the -title page. The height comes first, then the width if desired, -separated by a comma. Examples: - -@example -@@pagesizes 200mm,150mm @c for b5 paper -@end example -@noindent and -@example -@@pagesizes 11.5in @c for legal paper -@end example - -@cindex B5 paper, printing on -@cindex Legal paper, printing on -This would be reasonable for printing on B5-size paper. To emphasize, -this command specifies the size of the @emph{text area}, not the size of -the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by -8.5@dmn{in} for legal). - -@cindex Margins on page, not controllable -To make more elaborate changes, such as changing any of the page -margins, you must define a new command in @file{texinfo.tex} (or -@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}). - -@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to specify @code{@@pagesizes} that do not -require changing the source file. +Alternatively, to avoid embedding this physical paper size in your +document, use @code{texi2dvi} to format your document (@pxref{Format +with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then +other people do not have to change the document source file to format it +differently. -@code{@@pagesizes} is ignored by @code{makeinfo}. +@pindex texinfo.cnf +Another alternative: put the @code{@@afourpaper} command in the file +@file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex} +there.) This will automatically typeset all the Texinfo documents at +your site with that paper size in effect. -@node Cropmarks and Magnification +@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy +@comment node-name, next, previous, up @section Cropmarks and Magnification + @findex cropmarks @cindex Cropmarks for printing @cindex Printing cropmarks -You can (attempt to) direct @TeX{} to print cropmarks at the corners of +You can attempt to direct @TeX{} to print cropmarks at the corners of pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} command on a line by itself between @code{@@iftex} and @code{@@end iftex} lines near the beginning of the Texinfo file, before the title @@ -13470,8 +12592,8 @@ book set to 7 by 9.25 inches with the @code{@@smallbook} command. (Printers will not produce cropmarks for regular sized output that is printed on regular sized paper.) Since different printing machines work in different ways, you should explore the use of this command with a -spirit of adventure. You may have to redefine the command in -@file{texinfo.tex}. +spirit of adventure. You may have to redefine the command in the +@file{texinfo.tex} definitions file.@refill @findex mag @r{(@TeX{} command)} @cindex Magnified printing @@ -13487,7 +12609,7 @@ write this command between @code{@@tex} and @code{@@end tex} Follow the @code{\mag} command with an @samp{=} and then a number that is 1000 times the magnification you desire. For example, to print pages at 1.2 normal size, write the following near the beginning of the -Texinfo file, before the title page: +Texinfo file, before the title page:@refill @example @group @@ -13498,69 +12620,27 @@ Texinfo file, before the title page: @end example With some printing technologies, you can print normal-sized copies that -look better than usual by giving a larger-than-normal master to your -print shop. They do the reduction, thus effectively increasing the -resolution. - -Depending on your system, DVI files prepared with a -nonstandard-@code{\mag} may not print or may print only with certain -magnifications. Be prepared to experiment. - - -@node PDF Output -@section PDF Output -@cindex PDF output - -@pindex pdftex -You can generate a PDF output file from Texinfo source by using the -@command{pdftex} program to process your file instead of plain -@command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex -foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}. - -PDF stands for Portable Document Format, and was invented by Adobe -Systems. The -@uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format -definition} is freely available, as is a -@uref{http://www.foolabs.com/xpdf/, free viewer} for the X window -system. Since PDF is a binary format, there is no @samp{@@ifpdf} or -@samp{@@pdf} command by analogy with the other output formats. - -Despite the `portable' in the name, PDF files are nowhere near as -portable in practice as the plain ASCII formats (Info, HTML) Texinfo -also supports (portability relative to DVI is arguable). They also tend -to be much larger and do not support the bitmap fonts used by @TeX{} (by -default) very well. Nevertheless, a PDF file does preserve an actual -printed document on a screen as faithfully as possible, unlike HTML, -say, so have their place. - -PDF support in Texinfo is fairly rudimentary. - - -@node Creating and Installing Info Files -@chapter Creating and Installing Info Files +look better than usual by using a larger-than-normal master.@refill -This chapter describes how to create and install info files. @xref{Info -Files}, for general information about the file format itself. +Depending on your system, @code{\mag} may not work or may work only at +certain magnifications. Be prepared to experiment.@refill - -@menu -* Creating an Info File:: -* Install an Info File:: -@end menu - -@node Creating an Info File -@section Creating an Info File +@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top +@comment node-name, next, previous, up +@chapter Creating an Info File @cindex Creating an Info file -@cindex Info, creating an online file +@cindex Info, creating an on-line file @cindex Formatting a file for Info -@code{makeinfo} is a program that converts a Texinfo file into an Info -file, HTML file, or plain text. @code{texinfo-format-region} and -@code{texinfo-format-buffer} are GNU Emacs functions that convert -Texinfo to Info. +@code{makeinfo} is a utility that converts a Texinfo file into an Info +file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are +GNU Emacs functions that do the same.@refill + +A Texinfo file must contain an @code{@@setfilename} line near its +beginning, otherwise the Info formatting commands will fail. -For information on installing the Info file in the Info system, -@pxref{Install an Info File}. +For information on installing the Info file in the Info system, see +@ref{Install an Info File}.@refill @menu * makeinfo advantages:: @code{makeinfo} provides better error checking. @@ -13574,22 +12654,21 @@ For information on installing the Info file in the Info system, * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. -* makeinfo html:: Generating HTML output. @end menu - -@node makeinfo advantages -@subsection @code{makeinfo} Preferred +@node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File +@ifinfo +@heading @code{makeinfo} Preferred +@end ifinfo The @code{makeinfo} utility creates an Info file from a Texinfo source file more quickly than either of the Emacs formatting commands and provides better error messages. We recommend it. @code{makeinfo} is a C program that is independent of Emacs. You do not need to run Emacs to use @code{makeinfo}, which means you can use @code{makeinfo} on machines -that are too small to run Emacs. You can run @code{makeinfo} in any one -of three ways: from an operating system shell, from a shell inside -Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} -command in Texinfo mode in Emacs. +that are too small to run Emacs. You can run @code{makeinfo} in +any one of three ways: from an operating system shell, from a shell +inside Emacs, or by typing a key command in Texinfo mode in Emacs. @refill The @code{texinfo-format-region} and the @code{texinfo-format-buffer} @@ -13597,12 +12676,13 @@ commands are useful if you cannot run @code{makeinfo}. Also, in some circumstances, they format short regions or buffers more quickly than @code{makeinfo}.@refill -@node Invoking makeinfo -@subsection Running @code{makeinfo} from a Shell +@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File +@section Running @code{makeinfo} from a Shell To create an Info file from a Texinfo file, type @code{makeinfo} followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following to the shell: +is the prompt):@refill @example makeinfo bison.texinfo @@ -13623,9 +12703,9 @@ makeinfo --version @end ifinfo -@node makeinfo options +@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File @comment node-name, next, previous, up -@subsection Options for @code{makeinfo} +@section Options for @code{makeinfo} @cindex @code{makeinfo} options @cindex Options for @code{makeinfo} @@ -13662,37 +12742,24 @@ The options are: Cause the variable @var{var} to be defined. This is equivalent to @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}). -@item --commands-in-node-names -@opindex --commands-in-node-names -Allow @code{@@}-commands in node names. This is not recommended, as it -can probably never be implemented in @TeX{}. It also makes -@code{makeinfo} much slower. Also, this option is ignored when -@samp{--no-validate} is used. @xref{Pointer Validation}, for more -details. - @item --error-limit=@var{limit} -@itemx -e @var{limit} @opindex --error-limit=@var{limit} -@opindex -e @var{limit} Set the maximum number of errors that @code{makeinfo} will report before exiting (on the assumption that continuing would be useless); default 100. +@need 150 @item --fill-column=@var{width} -@itemx -f @var{width} @opindex --fill-column=@var{width} -@opindex -f @var{width} Specify the maximum number of columns in a line; this is the right-hand edge of a line. Paragraphs that are filled will be filled to this width. (Filling is the process of breaking up and connecting lines so that lines are the same length as or shorter than the number specified as the fill column. Lines are broken between words.) The default value -is 72. Ignored with @samp{--html}. +is 72. @item --footnote-style=@var{style} -@itemx -s @var{style} @opindex --footnote-style=@var{style} -@opindex -s @var{style} Set the footnote style to @var{style}, either @samp{end} for the end node style (the default) or @samp{separate} for the separate node style. The value set by this option overrides the value set in a Texinfo file @@ -13700,78 +12767,45 @@ by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the footnote style is @samp{separate}, @code{makeinfo} makes a new node containing the footnotes found in the current node. When the footnote style is @samp{end}, @code{makeinfo} places the footnote references at -the end of the current node. Ignored with @samp{--html}. +the end of the current node. @item --force -@itemx -F @opindex --force -@opindex -F Ordinarily, if the input file has errors, the output files are not created. With this option, they are preserved. @item --help -@itemx -h @opindex --help -@opindex -h Print a usage message listing all available options, then exit successfully. -@item --html -Generate HTML output rather than Info. @xref{makeinfo html}. - @item -I @var{dir} @opindex -I @var{dir} -Append @var{dir} to the directory search list for finding files that -are included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. If @var{dir} is -not given, the current directory @file{.} is appended. Note that -@var{dir} can actually be a list of several directories separated by the -usual path separator character (@samp{:} on Unix, @samp{;} on -MS-DOS/MS-Windows). - -@item --macro-expand=@var{file} -@itemx -E @var{file} -Output the Texinfo source with all the macros expanded to the named -file. Normally, the results of macro expansion are used internally by -@code{makeinfo} and then discarded. This option is used by -@command{texi2dvi} if you are using an old version of @file{texinfo.tex} -that does not support @code{@@macro}. +Add @code{dir} to the directory search list for finding files that are +included using the @code{@@include} command. By default, +@code{makeinfo} searches only the current directory. @item --no-headers @opindex --no-headers -@cindex Plain text output -@cindex ASCII text output -@cindex Generating plain text files -@cindex @file{INSTALL} file, generating -For Info output, do not include menus or node lines in the output and -write to standard output (unless @option{--output} is specified). This -results in an @sc{ascii} file that you cannot read in Info since it does -not contain the requisite nodes or menus. It is primarily useful to -extract certain pieces of a manual into separate files to be included in -a distribution, such as @file{INSTALL} files. - -@cindex Navigation links, omitting -For HTML output, if @samp{--no-split} is also specified, do not include a -navigation links at the top of each node. @xref{makeinfo html}. +Do not include menus or node lines in the output. This results in an +@sc{ascii} file that you cannot read in Info since it does not contain +the requisite nodes or menus. It is primarily useful to extract certain +pieces of a manual into separate files to be included in a distribution, +such as @file{INSTALL} files. @item --no-split @opindex --no-split -@cindex Splitting of output files -@cindex Output file splitting Suppress the splitting stage of @code{makeinfo}. By default, large output files (where the size is greater than 70k bytes) are split into -smaller subfiles. For Info output, each one is approximately 50k bytes. -For HTML output, each file contains one node (@pxref{makeinfo html}). +smaller subfiles, each one approximately 50k bytes. @item --no-pointer-validate @itemx --no-validate @opindex --no-pointer-validate @opindex --no-validate -@cindex Pointer validation, suppressing -Suppress the pointer-validation phase of @code{makeinfo}. This can also -be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use -@TeX{}}). Normally, after a Texinfo file is processed, some consistency -checks are made to ensure that cross references can be resolved, etc. -@xref{Pointer Validation}. +Suppress the pointer-validation phase of @code{makeinfo}. Normally, +after a Texinfo file is processed, some consistency checks are made to +ensure that cross references can be resolved, etc. +@xref{Pointer Validation}.@refill @item --no-warn @opindex --no-warn @@ -13780,10 +12814,6 @@ want this if the file you are creating has examples of Texinfo cross references within it, and the nodes that are referenced do not actually exist. -@item --number-sections -@opindex --number-sections -Output chapter, section, and appendix numbers as in printed manuals. - @item --no-number-footnotes @opindex --no-number-footnotes Suppress automatic footnote numbering. By default, @code{makeinfo} @@ -13797,20 +12827,15 @@ current footnote number to 1 at the start of each node. Specify that the output should be directed to @var{file} and not to the file name specified in the @code{@@setfilename} command found in the Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output -goes to standard output and @samp{--no-split} is implied. For split -HTML output, @var{file} is the name of the output file for the top node -(@pxref{makeinfo html}). +goes to standard output and @samp{--no-split} is implied. @item -P @var{dir} @opindex -P @var{dir} -Prepend @var{dir} to the directory search list for @code{@@include}. -If @var{dir} is not given, the current directory @file{.} is prepended. +Prepend @code{dir} to the directory search list for @code{@@include}. See @samp{-I} for more details. @item --paragraph-indent=@var{indent} -@itemx -p @var{indent} @opindex --paragraph-indent=@var{indent} -@opindex -p @var{indent} Set the paragraph indentation style to @var{indent}. The value set by this option overrides the value set in a Texinfo file by an @code{@@paragraphindent} command (@pxref{paragraphindent}). The value @@ -13824,13 +12849,11 @@ Preserve any existing indentation at the starts of paragraphs. Delete any existing indentation. @item @var{num} -Indent each paragraph by @var{num} spaces. +Indent each paragraph by that number of spaces. @end table @item --reference-limit=@var{limit} -@itemx -r @var{limit} @opindex --reference-limit=@var{limit} -@opindex -r @var{limit} Set the value of the number of references to a node that @code{makeinfo} will make without reporting a warning. If a node has more than this number of references in it, @code{makeinfo} will make the @@ -13847,24 +12870,21 @@ Normally, @code{makeinfo} only outputs messages if there are errors or warnings. @item --version -@itemx -V @opindex --version -@opindex -V Print the version number, then exit successfully. @end table -@node Pointer Validation -@subsection Pointer Validation +@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File +@section Pointer Validation @cindex Pointer validation with @code{makeinfo} @cindex Validation of pointers -If you do not suppress pointer validation with the @samp{--no-validate} -option or the @code{@@novalidate} command in the source file (@pxref{Use -TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final -Info file. Mostly, this means ensuring that nodes you have referenced -really exist. Here is a complete list of what is checked: +If you do not suppress pointer-validation, @code{makeinfo} will check +the validity of the final Info file. Mostly, this means ensuring that +nodes you have referenced really exist. Here is a complete list of what +is checked:@refill @enumerate @item @@ -13874,16 +12894,15 @@ node in the current file and is not an external reference such as to @item In every node, if the `Previous' node is different from the `Up' node, -then the node pointed to by the `Previous' field must have a `Next' -field which points back to this node.@refill +then the `Previous' node must also be pointed to by a `Next' node.@refill @item Every node except the `Top' node must have an `Up' pointer.@refill @item -The node referenced by an `Up' pointer must itself reference the current -node through a menu item, unless the node referenced by `Up' -has the form `(@var{file})'. +The node referenced by an `Up' pointer must contain a reference to the +current node in some manner other than through a `Next' reference. +This includes menu entries and cross references.@refill @item If the `Next' reference of a node is not the same as the `Next' reference @@ -13891,62 +12910,10 @@ of the `Up' reference, then the node referenced by the `Next' pointer must have a `Previous' pointer that points back to the current node. This rule allows the last node in a section to point to the first node of the next chapter.@refill - -@item -Every node except `Top' should be referenced by at least one other node, -either via the `Previous' or `Next' links, or via a menu or a -cross-reference.@refill @end enumerate -@cindex @@-commands in @@node, limited support -Some Texinfo documents might fail during the validation phase because -they use commands like @code{@@value} and @code{@@definfoenclose} in -node definitions and cross-references inconsistently. Consider the -following example: - -@example -@group -@@set nodename Node 1 - -@@node @@value@{nodename@}, Node 2, Top, Top - -This is node 1. - -@@node Node 2, , Node 1, Top - -This is node 2. -@end group -@end example - -@noindent -Here, the node ``Node 1'' was referenced both verbatim and through -@code{@@value}. - -By default, @code{makeinfo} fails such cases, because node names are not -fully expanded until they are written to the output file. You should -always try to reference nodes consistently; e.g., in the above example, -the second @code{@@node} line should have also used @code{@@value}. -However, if, for some reason, you @emph{must} reference node names -inconsistently, and @code{makeinfo} fails to validate the file, you can -use the @samp{--commands-in-node-names} option to force @code{makeinfo} -to perform the expensive expansion of all node names it finds in the -document. This might considerably slow down the program, though; -twofold increase in conversion time was measured for large documents -such as the Jargon file. - -@cindex @@value in @@node lines -The support for @code{@@}-commands in @code{@@node} directives is not -general enough to be freely used. For example, if the example above -redefined @code{nodename} somewhere in the document, @code{makeinfo} -will fail to convert it, even if invoked with the -@samp{--commands-in-node-names} option. - -@samp{--commands-in-node-names} has no effect if the @samp{--no-validate} -option is given. - - -@node makeinfo in Emacs -@subsection Running @code{makeinfo} inside Emacs +@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File +@section Running @code{makeinfo} inside Emacs @cindex Running @code{makeinfo} in Emacs @cindex @code{makeinfo} inside Emacs @cindex Shell, running @code{makeinfo} in @@ -13986,7 +12953,7 @@ You can parse the error messages by typing @kbd{C-x `} (@code{next-error}). This causes Emacs to go to and position the cursor on the line in the Texinfo source that @code{makeinfo} thinks caused the error. @xref{Compilation, , Running @code{make} or -Compilers Generally, emacs, The GNU Emacs Manual}, for more +Compilers Generally, xemacs, XEmacs User's Manual}, for more information about using the @code{next-error} command.@refill In addition, you can kill the shell in which the @code{makeinfo} @@ -13997,8 +12964,8 @@ output.@refill @item C-c C-m C-k @itemx M-x makeinfo-kill-job @findex makeinfo-kill-job -Kill the current running @code{makeinfo} job -(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill +Kill the current running @code{makeinfo} job created by +@code{makeinfo-region} or @code{makeinfo-buffer}.@refill @item C-c C-m C-l @itemx M-x makeinfo-recenter-output-buffer @@ -14031,22 +12998,22 @@ For example, you could write the following in your @file{.emacs} file:@refill @c three references to the same named manual, which looks strange. @iftex For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining -and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs +@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and +Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs Manual}. @end iftex @noindent @ifinfo For more information, see@* -@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* -@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* -@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* +@ref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's Manual},@* +@ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@* +@ref{Init File, , , xemacs, XEmacs User's Manual}, and@* @ref{makeinfo options, , Options for @code{makeinfo}}. @end ifinfo -@node texinfo-format commands +@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File @comment node-name, next, previous, up -@subsection The @code{texinfo-format@dots{}} Commands +@section The @code{texinfo-format@dots{}} Commands @findex texinfo-format-region @findex texinfo-format-buffer @@ -14081,16 +13048,16 @@ procedures are described in an appendix; see @ref{Catching Mistakes}. However, the @code{makeinfo} program is often faster and provides better error checking (@pxref{makeinfo in Emacs}).@refill -@node Batch Formatting +@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File @comment node-name, next, previous, up -@subsection Batch Formatting +@section Batch Formatting @cindex Batch formatting for Info @cindex Info batch formatting You can format Texinfo files for Info using @code{batch-texinfo-format} and Emacs Batch mode. You can run Emacs in Batch mode from any shell, including a shell inside of Emacs. (@xref{Command Switches, , Command -Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill +Line Switches and Arguments, xemacs, XEmacs User's Manual}.)@refill Here is a shell command to format all the files that end in @file{.texinfo} in the current directory: @@ -14113,9 +13080,9 @@ you can continue working in it. (When you run @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot use that Emacs for anything else until the command finishes.)@refill -@node Tag and Split Files +@node Tag and Split Files, , Batch Formatting, Create an Info File @comment node-name, next, previous, up -@subsection Tag Files and Split Files +@section Tag Files and Split Files @cindex Making a tag table automatically @cindex Tag table, making automatically @@ -14131,27 +13098,27 @@ bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the large Info file into shorter @dfn{indirect} subfiles of about 50,000 bytes each. Big files are split into smaller files so that Emacs does not need to make a large buffer to hold the whole of a large Info -file; instead, Emacs allocates just enough memory for the small, split-off -file that is needed at the time. This way, Emacs avoids wasting +file; instead, Emacs allocates just enough memory for the small, split +off file that is needed at the time. This way, Emacs avoids wasting memory when you run Info. (Before splitting was implemented, Info files were always kept short and @dfn{include files} were designed as a way to create a single, large printed manual out of the smaller Info files. @xref{Include Files}, for more information. Include files are -still used for very large documents, such as @cite{The Emacs Lisp +still used for very large documents, such as @cite{The XEmacs Lisp Reference Manual}, in which each chapter is a separate file.)@refill When a file is split, Info itself makes use of a shortened version of the original file that contains just the tag table and references to -the files that were split off. The split-off files are called +the files that were split off. The split off files are called @dfn{indirect} files.@refill -The split-off files have names that are created by appending @w{@samp{-1}}, +The split off files have names that are created by appending @w{@samp{-1}}, @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the @code{@@setfilename} command. The shortened version of the original file continues to have the name specified by @code{@@setfilename}.@refill At one stage in writing this document, for example, the Info file was saved -as the file @file{test-texinfo} and that file looked like this:@refill +as @file{test-texinfo} and that file looked like this:@refill @example @group @@ -14181,7 +13148,7 @@ Node: conventions^?6855 @noindent (But @file{test-texinfo} had far more nodes than are shown here.) Each of -the split-off, indirect files, @file{test-texinfo-1}, +the split off, indirect files, @file{test-texinfo-1}, @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file after the line that says @samp{Indirect:}. The tag table is listed after the line that says @samp{Tag table:}. @refill @@ -14191,7 +13158,7 @@ records the cumulative number of bytes in the preceding indirect files, not counting the file list itself, the tag table, or the permissions text in each file. In the tag table, the number following the node name records the location of the beginning of the node, in bytes from the -beginning of the (unsplit) output. +beginning.@refill If you are using @code{texinfo-format-buffer} to create Info files, you may want to run the @code{Info-validate} command. (The @@ -14203,50 +13170,9 @@ validate the structure of the nodes, see @ref{Using Info-validate}.@refill -@node makeinfo html -@subsection Generating HTML -@cindex HTML - -As an alternative to the normal Info format output you can use the -@samp{--html} option to generate output in HTML format, for installation -on a web site (for example). In this release, HTML output from -@code{makeinfo} is monolithic, splitting the output by chapter or node -is not supported. We hope to implement this feature soon. - -The HTML output file is named according to @code{@@setfilename}, but -with any @samp{.info} extension replaced with @samp{.html}. - -Texinfo input marked up with the @code{@@ifhtml} command will produce -output only with the @samp{--html} option supplied. Input marked up -with the @code{@@html} is passed literally to the output (suppressing -the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters -which have special significance in HTML). - -The @samp{--footnote-style} option is currently ignored for HTML output; -footnotes are hyperlinked at the end of the output file. - -The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The -exception is that HTML 3.2 tables are generated from the -@code{@@multitable} command, but tagged to degrade as well as possible -in browsers without table support. Please report output from an -error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a -bug. - -Navigation bars are inserted at the start of nodes, similarly to Info -output. The @samp{--no-headers} option will suppress this if used with -@samp{--no-split}. Header @code{} elements in split output can -support info-like navigation with browsers like Lynx and @w{Emacs W3} -which implement this @w{HTML 1.0} feature. You still won't normally get -the multi-file regexp and index search facilities provided by Info -readers. Otherwise, hyperlinks are generated from Texinfo commands -where appropriate. @samp{@@xref} commands to other documents are -generated assuming the other document is available in HTML form too, and -@samp{.html} is appended to the @samp{@@xref} Info file name. This -presumably will often not work. - - -@node Install an Info File -@section Installing an Info File +@node Install an Info File, Command List, Create an Info File, Top +@comment node-name, next, previous, up +@chapter Installing an Info File @cindex Installing an Info file @cindex Info file installation @cindex @file{dir} directory for Info installation @@ -14256,7 +13182,7 @@ Info files using the standalone Info program or the Info reader built into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) @menu -* Directory File:: The top level menu for all Info files. +* Directory file:: The top level menu for all Info files. * New Info File:: Listing a new info file. * Other Info Directories:: How to specify Info files that are located in other directories. @@ -14265,9 +13191,10 @@ into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) * Invoking install-info:: @code{install-info} options. @end menu - -@node Directory File -@subsection The Directory File @file{dir} +@node Directory file, New Info File, Install an Info File, Install an Info File +@ifinfo +@heading The @file{dir} File +@end ifinfo For Info to work, the @file{info} directory must contain a file that serves as a top level directory for the Info system. By convention, @@ -14282,6 +13209,7 @@ this:@refill @example @group * Menu: + * Info: (info). Documentation browsing system. * Emacs: (emacs). The extensible, self-documenting text editor. @@ -14311,17 +13239,21 @@ File: emacs Node: Top, Up: (DIR), Next: Distrib @end example @noindent -In this case, the @file{dir} file name is written in upper case -letters---it can be written in either upper or lower case. This is not -true in general, it is a special case for @file{dir}. +(Note that in this case, the @file{dir} file name is written in upper +case letters---it can be written in either upper or lower case. Info +has a feature that it will change the case of the file name to lower +case if it cannot find the name as written.)@refill +@c !!! Can any file name be written in upper or lower case, +@c or is dir a special case? +@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 -@node New Info File -@subsection Listing a New Info File +@node New Info File, Other Info Directories, Directory file, Install an Info File +@section Listing a New Info File @cindex Adding a new info file @cindex Listing a new info file @cindex New info file, listing it in @file{dir} file -@cindex Info file, listing a new +@cindex Info file, listing new one @cindex @file{dir} file listing To add a new Info file to your system, you must write a menu entry to @@ -14341,26 +13273,25 @@ followed by a period. The third part is the description. The name of an Info file often has a @file{.info} extension. Thus, the Info file for GDB might be called either @file{gdb} or @file{gdb.info}. The Info reader programs automatically try the file name both with and -without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will -try the @file{.inf} extension as well.}; so it is better to avoid -clutter and not to write @samp{.info} explicitly in the menu entry. For -example, the GDB menu entry should use just @samp{gdb} for the file -name, not @samp{gdb.info}. +without @file{.info}; so it is better to avoid clutter and not to write +@samp{.info} explicitly in the menu entry. For example, the GDB menu +entry should use just @samp{gdb} for the file name, not @samp{gdb.info}. -@node Other Info Directories -@subsection Info Files in Other Directories +@node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File +@comment node-name, next, previous, up +@section Info Files in Other Directories @cindex Installing Info in another directory @cindex Info installed in another directory @cindex Another Info directory -@cindex @file{dir} files and Info directories If an Info file is not in the @file{info} directory, there are three ways to specify its location:@refill -@enumerate +@itemize @bullet @item -Write the pathname in the @file{dir} file as the second part of the menu. +Write the pathname in the @file{dir} file as the second part of the +menu.@refill @item If you are using Emacs, list the name of the file in a second @file{dir} @@ -14368,63 +13299,58 @@ file, in its directory; and then add the name of that directory to the @code{Info-directory-list} variable in your personal or site initialization file. -This variable tells Emacs where to look for @file{dir} files (the files -must be named @file{dir}). Emacs merges the files named @file{dir} from -each of the listed directories. (In Emacs version 18, you can set the -@code{Info-directory} variable to the name of only one -directory.)@refill +This tells Emacs where to look for @file{dir} files. Emacs merges the +files named @file{dir} from each of the listed directories. (In Emacs +version 18, you can set the @code{Info-directory} variable to the name +of only one directory.)@refill @item Specify the Info directory name in the @code{INFOPATH} environment variable in your @file{.profile} or @file{.cshrc} initialization file. (Only you and others who set this environment variable will be able to -find Info files whose location is specified this way.) -@end enumerate +find Info files whose location is specified this way.)@refill +@end itemize -For example, to reach a test file in the @file{/home/bob/info} +For example, to reach a test file in the @file{/home/bob/manuals} directory, you could add an entry like this to the menu in the -standard @file{dir} file:@refill +@file{dir} file:@refill @example -* Test: (/home/bob/info/info-test). Bob's own test file. +* Test: (/home/bob/manuals/info-test). Bob's own test file. @end example @noindent In this case, the absolute file name of the @file{info-test} file is written as the second part of the menu entry.@refill +@vindex Info-directory-list Alternatively, you could write the following in your @file{.emacs} file:@refill -@vindex Info-directory-list @example @group -(require 'info) (setq Info-directory-list - (cons (expand-file-name "/home/bob/info") Info-directory-list)) + '("/home/bob/manuals" + "/usr/local/info")) @end group @end example +@c reworded to avoid overfill hbox This tells Emacs to merge the @file{dir} file from the -@file{/home/bob/info} directory with the system @file{dir} file. Info -will list the @file{/home/bob/info/info-test} file as a menu entry in -the @file{/home/bob/info/dir} file. Emacs does the merging only -when @kbd{M-x info} is first run, so if you want to set -@code{Info-directory-list} in an Emacs session where you've already run -@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs -to recompose the @file{dir} file. +@file{/home/bob/manuals} directory with the @file{dir} file from the +@file{/usr/local/info} directory. Info will list the +@file{/home/bob/manuals/info-test} file as a menu entry in the +@file{/home/bob/manuals/dir} file.@refill @vindex INFOPATH Finally, you can tell Info where to look by setting the @code{INFOPATH} -environment variable in your shell startup file, such as @file{.cshrc}, -@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible -shell such as @code{sh} or @code{bash} for your shell command -interpreter, you set the @code{INFOPATH} environment variable in the -@file{.profile} initialization file; but if you use @code{csh} or -@code{tcsh}, you set the variable in the @file{.cshrc} initialization -file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in -your @file{autoexec.bat} file or in the Registry. Each type of shell -uses a different syntax. +environment variable in your @file{.cshrc} or @file{.profile} file. If +you use a Bourne-compatible shell such as @code{sh} or @code{bash} for +your shell command interpreter, you set the @code{INFOPATH} environment +variable in the @file{.profile} initialization file; but if you use +@code{csh} or @code{tcsh}, you must set the variable in the +@file{.cshrc} initialization file. The two types of shells use +different syntax. @itemize @bullet @item @@ -14432,7 +13358,7 @@ In a @file{.cshrc} file, you could set the @code{INFOPATH} variable as follows:@refill @smallexample -setenv INFOPATH .:~/info:/usr/local/emacs/info +setenv INFOPATH .:~/manuals:/usr/local/emacs/info @end smallexample @item @@ -14440,35 +13366,21 @@ In a @file{.profile} file, you would achieve the same effect by writing:@refill @smallexample -INFOPATH=.:$HOME/info:/usr/local/emacs/info +INFOPATH=.:$HOME/manuals:/usr/local/emacs/info export INFOPATH @end smallexample - -@item -@pindex autoexec.bat -In a @file{autoexec.bat} file, you write this command@footnote{Note the -use of @samp{;} as the directory separator, and a different syntax for -using values of other environment variables.}: - -@smallexample -set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info -@end smallexample @end itemize @noindent The @samp{.} indicates the current directory as usual. Emacs uses the @code{INFOPATH} environment variable to initialize the value of Emacs's -own @code{Info-directory-list} variable. The stand-alone Info reader -merges any files named @file{dir} in any directory listed in the -@env{INFOPATH} variable into a single menu presented to you in the node -called @samp{(dir)Top}. - -@cindex @samp{:} @r{last in @env{INFOPATH}} -However you set @env{INFOPATH}, if its last character is a -colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this +own @code{Info-directory-list} variable. + +@cindex colon @r{last in @code{INFOPATH}} +However you set @code{INFOPATH}, if its last character is a colon, this is replaced by the default (compiled-in) path. This gives you a way to augment the default path with new directories without having to list all -the standard places. For example (using @code{sh} syntax): +the standard places. For example (using @code{sh} syntax: @example INFOPATH=/local/info: @@ -14479,16 +13391,9 @@ export INFOPATH will search @file{/local/info} first, then the standard directories. Leading or doubled colons are not treated specially. -@cindex @file{dir} file, creating your own -When you create your own @file{dir} file for use with -@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by -copying an existing @file{dir} file and replace all the text after the -@samp{* Menu:} with your desired entries. That way, the punctuation and -special CTRL-_ characters that Info needs will be present. - @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File -@subsection Installing Info Directory Files +@section Installing Info Directory Files When you install an Info file onto your system, you can use the program @code{install-info} to update the Info directory file @file{dir}. @@ -14498,12 +13403,11 @@ after copying the Info file into its proper installed location. @findex dircategory @findex direntry In order for the Info file to work with @code{install-info}, you should -use the commands @code{@@dircategory} and -@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source -file. Use @code{@@direntry} to specify the menu entries to add to the -Info directory file, and use @code{@@dircategory} to specify which part -of the Info directory to put it in. Here is how these commands are used -in this manual: +use the commands @code{@@dircategory} and @code{@@direntry} in the +Texinfo source file. Use @code{@@direntry} to specify the menu entry to +add to the Info directory file, and use @code{@@dircategory} to specify +which part of the Info directory to put it in. Here is how these +commands are used in this manual: @smallexample @@dircategory Texinfo documentation system @@ -14535,50 +13439,38 @@ command. If you use them later on in the input, @code{install-info} will not notice them. If you use @code{@@dircategory} more than once in the Texinfo source, -each usage specifies the `current' category; any subsequent -@code{@@direntry} commands will add to that category. - -Here are some recommended @code{@@dircategory} categories: `GNU -packages', `GNU programming tools', `GNU programming documentation', -`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual -utilities'. The idea is to include the `invoking' node for every -program installed by a package under `Individual utilities', and an -entry for the manual as a whole in the appropriate other category. +each usage specifies one category; the new menu entry is added to the +Info directory file in each of the categories you specify. If you use +@code{@@direntry} more than once, each usage specifies one menu entry; +each of these menu entries is added to the directory in each of the +specified categories. -@node Invoking install-info -@subsection Invoking install-info +@node Invoking install-info, , Installing Dir Entries, Install an Info File +@section Invoking install-info @pindex install-info @code{install-info} inserts menu entries from an Info file into the top-level @file{dir} file in the Info system (see the previous sections for an explanation of how the @file{dir} file works). It's most often -run as part of software installation, or when constructing a @file{dir} file +run as part of software installation, or when constructing a dir file for all manuals on a system. Synopsis: @example install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] @end example -If @var{info-file} or @var{dir-file} are not specified, the options -(described below) that define them must be. There are no compile-time -defaults, and standard input is never used. @code{install-info} can -read only one Info file and write only one @file{dir} file per invocation. +If @var{info-file} or @var{dir-file} are not specified, the various +options (described below) that define them must be. There are no +compile-time defaults, and standard input is never used. +@code{install-info} can read only one info file and write only one dir +file per invocation. @cindex @file{dir}, created by @code{install-info} If @var{dir-file} (however specified) does not exist, @code{install-info} creates it if possible (with no entries). -@cindex Compressed files, reading -@cindex Dir files, compressed -If any input file is compressed with @code{gzip} (@pxref{Invoking -gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it -for reading. And if @var{dir-file} is compressed, @code{install-info} -also automatically leaves it compressed after writing any changes. -If @var{dir-file} itself does not exist, @code{install-info} tries to -open @file{@var{dir-file}.gz}. - Options: @table @code @@ -14589,16 +13481,12 @@ name in the entry in @var{dir-file} must be @var{info-file} (except for an optional @samp{.info} in either one). Don't insert any new entries. @item --dir-file=@var{name} -@itemx -d @var{name} @opindex --dir-file=@var{name} -@opindex -d @var{name} Specify file name of the Info directory file. This is equivalent to using the @var{dir-file} argument. @item --entry=@var{text} -@itemx -e @var{text} @opindex --entry=@var{text} -@opindex -e @var{text} Insert @var{text} as an Info directory entry; @var{text} should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all @@ -14606,24 +13494,17 @@ added. If you don't specify any entries, they are determined from information in the Info file itself. @item --help -@itemx -h @opindex --help -@opindex -h Display a usage message listing basic usage and all available options, then exit successfully. @item --info-file=@var{file} -@itemx -i @var{file} @opindex --info-file=@var{file} -@opindex -i @var{file} Specify Info file to install in the directory. -Equivalent to using the @var{info-file} argument. +This is equivalent to using the @var{info-file} argument. @item --info-dir=@var{dir} -@itemx -D @var{dir} @opindex --info-dir=@var{dir} -@opindex -D @var{dir} -Specify the directory where @file{dir} resides. Equivalent to @samp{--dir-file=@var{dir}/dir}. @item --item=@var{text} @@ -14636,40 +13517,33 @@ a menu item. Suppress warnings. @item --remove -@itemx -r @opindex --remove -@opindex -r Same as @samp{--delete}. @item --section=@var{sec} -@itemx -s @var{sec} @opindex --section=@var{sec} -@opindex -s @var{sec} Put this file's entries in section @var{sec} of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don't specify any sections, they are determined from information in the Info file itself. @item --version -@itemx -V @opindex --version -@opindex -V @cindex version number, finding Display version information and exit successfully. @end table -@node Command List +@node Command List, Tips, Install an Info File, Top @appendix @@-Command List @cindex Alphabetical @@-command list @cindex List of @@-commands @cindex @@-command list -@cindex Reference to @@-commands Here is an alphabetical list of the @@-commands in Texinfo. Square brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, -@samp{@dots{}}, indicates repeated text. +@samp{@dots{}}, indicates repeated text.@refill @sp 1 @table @code @@ -14706,10 +13580,10 @@ Indicate to @TeX{} that an immediately preceding period, question mark, exclamation mark, or colon does not end a sentence. Prevent @TeX{} from inserting extra whitespace as it does at the end of a sentence. The command has no effect on the Info file output. -@xref{Not Ending a Sentence}. +@xref{Not Ending a Sentence}.@refill @item @@= -Generate a macron (bar) accent over the next character, as in @=o. +Generate a macro (bar) accent over the next character, as in @=o. @xref{Inserting Accents}. @item @@? @@ -14734,7 +13608,7 @@ Stands for a left brace, @samp{@{}. Stands for a right-hand brace, @samp{@}}.@* @xref{Braces Atsigns, , Inserting @@ and braces}. -@item @@~ +@item @@= Generate a tilde accent over the next character, as in @~N. @xref{Inserting Accents}. @@ -14743,27 +13617,15 @@ Generate a tilde accent over the next character, as in @~N. Generate the uppercase and lowercase Scandinavian A-ring letters, respectively: @AA{}, @aa{}. @xref{Inserting Accents}. -@item @@acronym@{@var{abbrev}@} -Tag @var{abbrev} as an acronym, that is, an abbreviation written in all -capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}. - @item @@AE@{@} @itemx @@ae@{@} Generate the uppercase and lowercase AE ligatures, respectively: @AE{}, @ae{}. @xref{Inserting Accents}. -@item @@afourlatex -@itemx @@afourpaper -@itemx @@afourwide -Change page dimensions for the A4 paper size. @xref{A4 Paper}. - -@item @@alias @var{new}=@var{existing} -Make the command @samp{@@@var{new}} an alias for the existing command -@samp{@@@var{existing}}. @xref{alias}. - -@item @@anchor@{@var{name}@} -Define @var{name} as the current location for use as a cross-reference -target. @xref{anchor,, @code{@@anchor}}. +@item @@afourpaper +Change page dimensions for the A4 paper size. +Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}. +@xref{A4 Paper}. @item @@appendix @var{title} Begin an appendix. The title appears in the table @@ -14867,14 +13729,10 @@ and @code{@@end ifset} commands, and preventing Highlight text that is an expression, a syntactically complete token of a program, or a program name. @xref{code, , @code{@@code}}.@refill -@item @@command@{@var{command-name}@} -Indicate a command name, such as @command{ls}. -@xref{command,, @code{@@command}}. - @item @@comment @var{comment} Begin a comment in Texinfo. The rest of the line does not appear in either the Info file or the printed manual. A synonym for @code{@@c}. -@xref{Comments}. +@xref{Comments, , Comments}.@refill @item @@contents Print a complete table of contents. Has no effect in Info, which uses @@ -14914,9 +13772,12 @@ entity, and its arguments, if any. @xref{Definition Commands}.@refill Define a new index and its indexing command. Print entries in a roman font. @xref{New Indices, , Defining New Indices}.@refill -@item @@definfoenclose @var{newcmd}, @var{before}, @var{after}, -Create new @@-command @var{newcmd} for Info that marks text by enclosing -it in strings that precede and follow the text. @xref{definfoenclose}. +@c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96. +@item @@definfoenclose @var{new-command}, @var{before}, @var{after}, +Create new @@-command for Info that marks text by enclosing it in +strings that precede and follow the text. Write definition inside of +@code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized +Highlighting}.@refill @item @@defivar @var{class} @var{instance-variable-name} @itemx @@defivarx @var{class} @var{instance-variable-name} @@ -14925,8 +13786,8 @@ object-oriented programming. The command is equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. -@item @@defmac @var{macroname} @var{arguments}@dots{} -@itemx @@defmacx @var{macroname} @var{arguments}@dots{} +@item @@defmac @var{macro-name} @var{arguments}@dots{} +@itemx @@defmacx @var{macro-name} @var{arguments}@dots{} Format a description for a macro. The command is equivalent to @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. @@ -14945,7 +13806,7 @@ Format a description for an operation in object-oriented programming. @code{@@defop} takes as arguments the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any. @xref{Definition -Commands}, and @ref{Abstract Objects}. +Commands}, and @ref{deffnx,, Def Cmds in Detail}. @item @@defopt @var{option-name} @itemx @@defoptx @var{option-name} @@ -14964,7 +13825,7 @@ and @ref{deffnx,, Def Cmds in Detail}. Format a description for a data type. @code{@@deftp} takes as arguments the category, the name of the type (which is a word like @samp{int} or @samp{float}), and then the names of attributes of objects of that type. -@xref{Definition Commands}, and @ref{Data Types}. +@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} @@ -14978,29 +13839,16 @@ entity, and its arguments, if any. @xref{Definition Commands}, and @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} Format a description for a function in a typed language. The command is equivalent to @samp{@@deftypefn Function @dots{}}. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} -@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} -Format a description for a typed instance variable in object-oriented -programming. @xref{Definition Commands}, and @ref{Abstract Objects}. +@xref{Definition Commands}, +and @ref{deffnx,, Def Cmds in Detail}. @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} Format a description for a typed method in object-oriented programming. +Takes as arguments the name of the class of the method, the return type +of the method, the name of the method, and its arguments, if any. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. -@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a typed operation in object-oriented programming. -@xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypevar @var{data-type} @var{variable-name} -@itemx @@deftypevarx @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - @item @@deftypevr @var{classification} @var{data-type} @var{name} @itemx @@deftypevrx @var{classification} @var{data-type} @var{name} Format a description for something like a variable in a typed @@ -15009,6 +13857,12 @@ classification of entity being described, the type, and the name of the entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. +@item @@deftypevar @var{data-type} @var{variable-name} +@itemx @@deftypevarx @var{data-type} @var{variable-name} +Format a description for a variable in a typed language. The command is +equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition +Commands}, and @ref{deffnx,, Def Cmds in Detail}. + @item @@defun @var{function-name} @var{arguments}@dots{} @itemx @@defunx @var{function-name} @var{arguments}@dots{} Format a description for functions. The command is equivalent to @@ -15028,7 +13882,7 @@ as arguments the category of the entity and the name of the entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. -@item @@detailmenu +@item @@detailmenu@{@} Avoid @code{makeinfo} confusion stemming from the detailed node listing in a master menu. @xref{Master Menu Parts}. @@ -15041,39 +13895,33 @@ Specify a part of the Info directory menu where this file's entry should go. @xref{Installing Dir Entries}. @item @@direntry -Begin the Info directory menu entry for this file. Pair with -@code{@@end direntry}. @xref{Installing Dir Entries}. +Begin the Info directory menu entry for this file. +@xref{Installing Dir Entries}. +@need 100 @item @@display -Begin a kind of example. Like @code{@@example} (indent text, do not -fill), but do not select a new font. Pair with @code{@@end display}. -@xref{display, , @code{@@display}}. +Begin a kind of example. Indent text, do not fill, do not select a +new font. Pair with @code{@@end display}. @xref{display, , +@code{@@display}}.@refill @item @@dmn@{@var{dimension}@} Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a thin space before @var{dimension}. No effect in Info. -@xref{dmn, , @code{@@dmn}}. - -@item @@documentencoding @var{enc} -Declare the input encoding as @var{enc}. -@xref{documentencoding,, @code{@@documentencoding}}. - -@item @@documentlanguage @var{CC} -Declare the document language as the two-character ISO-639 abbreviation -@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}. +@xref{dmn, , @code{@@dmn}}.@refill @item @@dotaccent@{@var{c}@} -Generate a dot accent over the character @var{c}, as in @dotaccent{o}. +Generate a dot accent over the character @var{c}, as in @dotaccent{oo}. @xref{Inserting Accents}. @item @@dots@{@} Insert an ellipsis: @samp{@dots{}}. -@xref{dots, , @code{@@dots}}.@refill +@xref{dots, , @code{@@dots@{@}}}.@refill @item @@email@{@var{address}[, @var{displayed-text}]@} Indicate an electronic mail address. -@xref{email, , @code{@@email}}. +@xref{email, , @code{@@email}}.@refill +@need 100 @item @@emph@{@var{text}@} Highlight @var{text}; text is displayed in @emph{italics} in printed output, and surrounded by asterisks in Info. @xref{Emphasis, , @@ -15083,20 +13931,18 @@ Emphasizing Text}. Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting Commands,,@@-commands}. -@item @@env@{@var{environment-variable}@} -Indicate an environment variable name, such as @env{PATH}. -@xref{env,, @code{@@env}}. - @item @@enddots@{@} Generate an end-of-sentence of ellipsis, like this @enddots{} @xref{dots,,@code{@@dots@{@}}}. +@need 100 @item @@enumerate [@var{number-or-letter}] Begin a numbered list, using @code{@@item} for each entry. Optionally, start list with @var{number-or-letter}. Pair with @code{@@end enumerate}. @xref{enumerate, , @code{@@enumerate}}.@refill +@need 100 @item @@equiv@{@} Indicate to the reader the exact equivalence of two forms with a glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill @@ -15121,10 +13967,6 @@ Begin an example. Indent text, do not fill, and select fixed-width font. Pair with @code{@@end example}. @xref{example, , @code{@@example}}.@refill -@item @@exampleindent @var{indent} -Indent example-like environments by @var{indent} number of spaces -(perhaps 0). @xref{exampleindent,, Paragraph Indenting}. - @item @@exclamdown@{@} Produce an upside-down exclamation point. @xref{Inserting Accents}. @@ -15145,10 +13987,12 @@ Highlight the name of a file, buffer, node, or directory. @xref{file, , Prevent @TeX{} from printing large black warning rectangles beside over-wide lines. @xref{Overfull hboxes}.@refill +@need 100 @item @@findex @var{entry} Add @var{entry} to the index of functions. @xref{Index Entries, , Defining the Entries of an Index}.@refill +@need 200 @item @@flushleft @itemx @@flushright Left justify every line but leave the right end ragged. @@ -15157,6 +14001,7 @@ Leave font as is. Pair with @code{@@end flushleft}. @xref{flushleft & flushright, , @code{@@flushleft} and @code{@@flushright}}.@refill +@need 200 @item @@footnote@{@var{text-of-footnote}@} Enter a footnote. Footnote text is printed at the bottom of the page by @TeX{}; Info may format in either `End' node or `Separate' node style. @@ -15168,9 +14013,10 @@ node style or @samp{separate} for the separate node style. @xref{Footnotes}.@refill @item @@format -Begin a kind of example. Like @code{@@display}, but do not narrow the -margins. Pair with @code{@@end format}. @xref{example,, -@code{@@example}}. +Begin a kind of example. Like @code{@@example} or @code{@@display}, +but do not narrow the margins and do not select the fixed-width font. +Pair with @code{@@end format}. @xref{example, , +@code{@@example}}.@refill @item @@ftable @var{formatting-command} Begin a two-column table, using @code{@@item} for each entry. @@ -15313,15 +14159,16 @@ respectively: @L{}, @l{}. @item @@lisp Begin an example of Lisp code. Indent text, do not fill, and select -fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}. +fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, , +@code{@@lisp}}.@refill @item @@lowersections Change subsequent chapters to sections, sections to subsections, and so on. @xref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}}.@refill -@item @@macro @var{macroname} @{@var{params}@} -Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. +@item @@macro @var{macro-name} @{@var{params}@} +Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}. Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining Macros}. @@ -15334,7 +14181,7 @@ chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill @item @@math@{@var{mathematical-expression}@} Format a mathematical expression. -@xref{math, , @code{@@math}: Inserting Mathematical Expressions}. +@xref{math, , @code{@@math} - Inserting Mathematical Expressions}. @item @@menu Mark the beginning of a menu of nodes in Info. No effect in a printed @@ -15360,10 +14207,6 @@ references for @TeX{}. @xref{node, , @code{@@node}}.@refill Prevent text from being indented as if it were a new paragraph. @xref{noindent, , @code{@@noindent}}.@refill -@item @@novalidate -Suppress validation of node references, omit creation of auxiliary files -with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}. - @item @@O@{@} @itemx @@o@{@} Generate the uppercase and lowercase O-with-slash letters, respectively: @@ -15380,21 +14223,15 @@ How to Make Your Own Headings}.@refill Generate the uppercase and lowercase OE ligatures, respectively: @OE{}, @oe{}. @xref{Inserting Accents}. -@item @@option@{@var{option-name}@} -Indicate a command-line option, such as @option{-l} or @option{--help}. -@xref{option,, @code{@@option}}. - @item @@page Start a new page in a printed manual. No effect in Info. @xref{page, , @code{@@page}}.@refill -@item @@pagesizes [@var{width}][, @var{height}] -Change page dimensions. @xref{pagesizes}. - @item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve -source file indentation if @var{indent} is @code{asis}. -@xref{paragraphindent,, Paragraph Indenting}. +Indent paragraphs by @var{indent} number of spaces; delete indentation +if the value of @var{indent} is 0; and do not change indentation if +@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph +Indenting}.@refill @item @@pindex @var{entry} Add @var{entry} to the index of programs. @xref{Index Entries, , Defining @@ -15434,6 +14271,7 @@ or imaginary work. Write command on a line of its own. Pair with @code{@@end quotation}. @xref{quotation, , @code{@@quotation}}.@refill +@need 100 @item @@r@{@var{text}@} Print @var{text} in @r{roman} font. No effect in Info. @xref{Fonts}.@refill @@ -15443,17 +14281,20 @@ Change subsequent sections to chapters, subsections to sections, and so on. @xref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}}.@refill +@need 300 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} Make a reference. In a printed manual, the reference does not start with a `See'. Follow command with a punctuation mark. Only the first argument is mandatory. @xref{ref, , @code{@@ref}}.@refill +@need 300 @item @@refill In Info, refill and indent the paragraph after all the other processing has been done. No effect on @TeX{}, which always refills. This command is no longer needed, since all formatters now automatically refill. @xref{Refilling Paragraphs}.@refill +@need 300 @item @@result@{@} Indicate the result of an expression to the reader with a special glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill @@ -15483,26 +14324,17 @@ Make @var{flag} active, causing the Texinfo formatting commands to format text between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end ifset} commands. Optionally, set value of @var{flag} to @var{string}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. +@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill @item @@setchapternewpage @var{on-off-odd} Specify whether chapters start on new pages, and if so, whether on odd-numbered (right-hand) new pages. @xref{setchapternewpage, , -@code{@@setchapternewpage}}. - -@item @@setcontentsaftertitlepage -Put the table of contents after the @samp{@@end titlepage} even if the -@code{@@contents} command is not there. @xref{Contents}. +@code{@@setchapternewpage}}.@refill @item @@setfilename @var{info-file-name} Provide a name to be used by the Info file. This command is essential for @TeX{} formatting as well, even though it produces no output. -@xref{setfilename, , @code{@@setfilename}}. - -@item @@setshortcontentsaftertitlepage -Place the short table of contents after the @samp{@@end titlepage} -command even if the @code{@@shortcontents} command is not there. -@xref{Contents}. +@xref{setfilename, , @code{@@setfilename}}.@refill @item @@settitle @var{title} Provide a title for page headers in a printed manual. @@ -15514,45 +14346,40 @@ menus rather than tables of contents. A synonym for @code{@@summarycontents}. @xref{Contents, , Generating a Table of Contents}.@refill -@item @@shorttitlepage @var{title} +@item @@shorttitlepage@{@var{title}@} Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. +@need 400 @item @@smallbook Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format. @xref{smallbook, , -Printing Small Books}. Also, see @ref{small}. - -@item @@smalldisplay -Begin a kind of example. Like @code{@@smallexample} (indent text, no -filling), but do not select the fixed-width font. In @code{@@smallbook} -format, print text in a smaller font than with @code{@@display}. Pair -with @code{@@end smalldisplay}. @xref{small}. +Printing Small Books}. Also, see @ref{smallexample & smalllisp, , +@code{@@smallexample} and @code{@@smalllisp}}.@refill +@need 400 @item @@smallexample Indent text to indicate an example. Do not fill, select fixed-width font. In @code{@@smallbook} format, print text in a smaller font than with @code{@@example}. Pair with @code{@@end smallexample}. -@xref{small}. - -@item @@smallformat -Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow -the margins and do not select the fixed-width font. -In @code{@@smallbook} format, print text in a smaller font than -with @code{@@format}. Pair with @code{@@end smallformat}. -@xref{small}. +@xref{smallexample & smalllisp, , @code{@@smallexample} and +@code{@@smalllisp}}.@refill +@need 400 @item @@smalllisp Begin an example of Lisp code. Indent text, do not fill, select fixed-width font. In @code{@@smallbook} format, print text in a -smaller font. Pair with @code{@@end smalllisp}. @xref{small}. +smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & +smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill +@need 700 @item @@sp @var{n} Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill @item @@ss@{@} Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. -@item @@strong @{@var{text}@} +@need 700 +@item @@strong @var{text} Emphasize @var{text} by typesetting it in a @strong{bold} font for the printed manual and by surrounding it with asterisks for Info. @xref{emph & strong, , Emphasizing Text}.@refill @@ -15594,16 +14421,19 @@ menus rather than tables of contents. A synonym for @code{@@shortcontents}. @xref{Contents, , Generating a Table of Contents}.@refill +@need 300 @item @@syncodeindex @var{from-index} @var{into-index} Merge the index named in the first argument into the index named in the second argument, printing the entries from the first index in @code{@@code} font. @xref{Combining Indices}.@refill +@need 300 @item @@synindex @var{from-index} @var{into-index} Merge the index named in the first argument into the index named in the second argument. Do not change the font of @var{from-index} entries. @xref{Combining Indices}.@refill +@need 100 @item @@t@{@var{text}@} Print @var{text} in a @t{fixed-width}, typewriter-like font. No effect in Info. @xref{Fonts}.@refill @@ -15611,6 +14441,7 @@ No effect in Info. @xref{Fonts}.@refill @item @@tab Separate columns in a multitable. @xref{Multitable Rows}. +@need 400 @item @@table @var{formatting-command} Begin a two-column table, using @code{@@item} for each entry. Write each first column entry on the same line as @code{@@item}. First @@ -15654,18 +14485,21 @@ Not relevant to Info, which does not have title pages. @xref{title subtitle author, , The @code{@@title} @code{@@subtitle} and @code{@@author} Commands}.@refill +@need 400 @item @@titlefont@{@var{text}@} In a printed manual, print @var{text} in a larger than normal font. Not relevant to Info, which does not have title pages. @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} and @code{@@sp} Commands}.@refill +@need 300 @item @@titlepage Indicate to Texinfo the beginning of the title page. Write command on a line of its own. Pair with @code{@@end titlepage}. Nothing between @code{@@titlepage} and @code{@@end titlepage} appears in Info. @xref{titlepage, , @code{@@titlepage}}.@refill +@need 150 @item @@today@{@} Insert the current date, in `1 Jan 1900' style. @xref{Custom Headings, , How to Make Your Own Headings}.@refill @@ -15715,9 +14549,9 @@ chapter. The title appears in the table of contents of a printed manual. In Info, the title is underlined with periods. @xref{subsubsection, , The `subsub' Commands}.@refill -@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} +@item @@uref@{@var{url}[, @var{displayed-text}@} Define a cross reference to an external uniform resource locator for the -World Wide Web. @xref{uref, , @code{@@uref}}.@refill +World Wide Web. @xref{url, , @code{@@url}}.@refill @item @@url@{@var{url}@} Indicate text that is a uniform resource locator for the World Wide @@ -15737,10 +14571,12 @@ Highlight a metasyntactic variable, which is something that stands for another piece of text. @xref{var, , Indicating Metasyntactic Variables}.@refill +@need 400 @item @@vindex @var{entry} Add @var{entry} to the index of variables. @xref{Index Entries, , Defining the Entries of an Index}.@refill +@need 400 @item @@vskip @var{amount} In a printed manual, insert whitespace so as to push text on the remainder of the page towards the bottom of the page. Used in @@ -15749,6 +14585,7 @@ formatting the copyright page with the argument @samp{0pt plus only in contexts ignored for Info. @xref{Copyright & Permissions, , The Copyright Page and Printed Permissions}.@refill +@need 400 @item @@vtable @var{formatting-command} Begin a two-column table, using @code{@@item} for each entry. Automatically enter each of the items in the first column into the @@ -15756,11 +14593,13 @@ index of variables. Pair with @code{@@end vtable}. The same as @code{@@table}, except for indexing. @xref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}.@refill +@need 400 @item @@w@{@var{text}@} Prevent @var{text} from being split across two lines. Do not end a paragraph that uses @code{@@w} with an @code{@@refill} command. @xref{w, , @code{@@w}}.@refill +@need 400 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} Make a reference that starts with `See' in a printed manual. Follow command with a punctuation mark. Only the first argument is @@ -15768,7 +14607,7 @@ mandatory. @xref{xref, , @code{@@xref}}.@refill @end table -@node Tips +@node Tips, Sample Texinfo File, Command List, Top @appendix Tips and Hints Here are some tips for writing Texinfo documentation:@refill @@ -15831,8 +14670,9 @@ Lisp. @item Write the indexing commands that refer to a whole section immediately after the section command, and write the indexing commands that refer to -a paragraph before that paragraph. +the paragraph before the paragraph. +@need 1000 In the example that follows, a blank line comes after the index entry for ``Leaping'': @@ -16210,7 +15050,7 @@ Write notes for yourself at the very end of a Texinfo file after the @end itemize -@node Sample Texinfo File +@node Sample Texinfo File, Sample Permissions, Tips, Top @appendix A Sample Texinfo File @cindex Sample Texinfo file, no comments @@ -16288,10 +15128,9 @@ manual. @end example -@node Sample Permissions +@node Sample Permissions, Include Files, Sample Texinfo File, Top @appendix Sample Permissions @cindex Permissions -@cindex Sample permissions @cindex Copying permissions Texinfo files should contain sections that tell the readers that they @@ -16301,7 +15140,7 @@ and the printed manual.@refill Also, if you are writing a manual about software, you should explain that the software is free and either include the GNU General Public License (GPL) or provide a reference to it. @xref{Distrib, , -Distribution, emacs, The GNU Emacs Manual}, for an example of the text +Distribution, xemacs, XEmacs User's Manual}, for an example of the text that could be used in the software ``Distribution'', ``General Public License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, , Texinfo Copying Conditions}, for an example of a brief explanation @@ -16315,7 +15154,7 @@ of how the copying conditions provide you with rights. @refill @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions @ifinfo -@section Inserting Permissions +@appendixsec Inserting Permissions @end ifinfo In a Texinfo file, the first @code{@@ifinfo} section usually begins @@ -16349,18 +15188,18 @@ To make it simple to insert a permission notice into each section of the Texinfo file, sample permission notices for each section are reproduced in full below.@refill -You may need to specify the correct name of a section mentioned in the -permission notice. For example, in @cite{The GDB Manual}, the name of -the section referring to the General Public License is called the ``GDB -General Public License'', but in the sample shown below, that section is -referred to generically as the ``GNU General Public License''. If the -Texinfo file does not carry a copy of the General Public License, leave -out the reference to it, but be sure to include the rest of the -sentence. +Note that you may need to specify the correct name of a section +mentioned in the permission notice. For example, in @cite{The GDB +Manual}, the name of the section referring to the General Public +License is called the ``GDB General Public License'', but in the +sample shown below, that section is referred to generically as the +``GNU General Public License''. If the Texinfo file does not carry a +copy of the General Public License, leave out the reference to it, but +be sure to include the rest of the sentence.@refill @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions @comment node-name, next, previous, up -@section @samp{ifinfo} Copying Permissions +@appendixsec @samp{ifinfo} Copying Permissions @cindex @samp{ifinfo} permissions In the @code{@@ifinfo} section of a Texinfo file, the standard Free @@ -16369,7 +15208,7 @@ Software Foundation permission notice reads as follows:@refill @example This file documents @dots{} -Copyright 1999 Free Software Foundation, Inc. +Copyright 1998 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and @@ -16401,7 +15240,7 @@ translation approved by the Free Software Foundation. @node Titlepage Permissions, , ifinfo Permissions, Sample Permissions @comment node-name, next, previous, up -@section Titlepage Copying Permissions +@appendixsec Titlepage Copying Permissions @cindex Titlepage permissions In the @code{@@titlepage} section of a Texinfo file, the standard Free @@ -16431,7 +15270,7 @@ translation approved by the Free Software Foundation. @end example -@node Include Files +@node Include Files, Headings, Sample Permissions, Top @appendix Include Files @cindex Include files @@ -16456,7 +15295,7 @@ conveniently small parts.@refill @end menu @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files -@section How to Use Include Files +@appendixsec How to Use Include Files @findex include To include another file within a Texinfo file, write the @@ -16497,7 +15336,7 @@ Texinfo mode command, @code{texinfo-multiple-files-update}, that is designed for @code{@@include} files.@refill @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files -@section @code{texinfo-multiple-files-update} +@appendixsec @code{texinfo-multiple-files-update} @findex texinfo-multiple-files-update GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} @@ -16573,7 +15412,7 @@ updates @strong{every} pointer and menu in @strong{all} the files and then inser master menu.@refill @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files -@section Include File Requirements +@appendixsec Include File Requirements @cindex Include file requirements @cindex Requirements for include files @@ -16599,7 +15438,7 @@ should @emph{not} contain any nodes besides the single `Top' node. The them.@refill @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files -@section Sample File with @code{@@include} +@appendixsec Sample File with @code{@@include} @cindex Sample @code{@@include} file @cindex Include file sample @cindex @code{@@include} file sample @@ -16629,7 +15468,7 @@ would insert a main or master menu:@refill @group @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1999 Free Software Foundation, Inc. +Copyright @@copyright@{@} 1998 Free Software Foundation, Inc. @@end titlepage @end group @@ -16670,21 +15509,21 @@ The full contents of @file{concept-index.texinfo} might be as simple as this: @example @group -@@node Concept Index +@@node Concept Index, , Second, Top @@unnumbered Concept Index @@printindex cp @end group @end example -The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference +The outer Texinfo source file for @cite{The XEmacs Lisp Reference Manual} is named @file{elisp.texi}. This outer file contains a master menu with 417 entries and a list of 41 @code{@@include} files.@refill @node Include Files Evolution, , Sample Include File, Include Files @comment node-name, next, previous, up -@section Evolution of Include Files +@appendixsec Evolution of Include Files When Info was first created, it was customary to create many small Info files on one subject. Each Info file was formatted from its own @@ -16712,7 +15551,7 @@ However, because large Info files are now split automatically, it is no longer necessary to keep them small.@refill Nowadays, multiple Texinfo files are used mostly for large documents, -such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects +such as @cite{The XEmacs Lisp Reference Manual}, and for projects in which several different people write different sections of a document simultaneously.@refill @@ -16723,7 +15562,7 @@ you can write menus and cross references without naming the different Texinfo files.@refill -@node Headings +@node Headings, Catching Mistakes, Include Files, Top @appendix Page Headings @cindex Headings @cindex Footings @@ -16782,7 +15621,7 @@ right part is set flushright.@refill @node Heading Format, Heading Choice, Headings Introduced, Headings @comment node-name, next, previous, up -@section Standard Heading Formats +@appendixsec Standard Heading Formats Texinfo provides two standard heading formats, one for manuals printed on one side of each sheet of paper, and the other for manuals printed @@ -16851,7 +15690,7 @@ manual.@refill @node Heading Choice, Custom Headings, Heading Format, Headings @comment node-name, next, previous, up -@section Specifying the Type of Heading +@appendixsec Specifying the Type of Heading @TeX{} does not begin to generate page headings for a standard Texinfo file until it reaches the @code{@@end titlepage} command. Thus, the @@ -16888,25 +15727,22 @@ Texinfo lacks an @code{@@setchapternewpage even} command.@refill @node Custom Headings, , Heading Choice, Headings @comment node-name, next, previous, up -@section How to Make Your Own Headings +@appendixsec How to Make Your Own Headings You can use the standard headings provided with Texinfo or specify your own. By default, Texinfo has no footers, so if you specify them, the available page size for the main text will be slightly reduced. +@c Following paragraph is verbose to prevent overfull hboxes. Texinfo provides six commands for specifying headings and -footings: -@itemize @bullet -@item -@code{@@everyheading} @code{@@everyfooting} generate page headers and -footers that are the same for both even- and odd-numbered pages. -@item -@code{@@evenheading} and @code{@@evenfooting} command generate headers -and footers for even-numbered (left-hand) pages. -@item -@code{@@oddheading} and @code{@@oddfooting} generate headers and footers -for odd-numbered (right-hand) pages. -@end itemize +footings. The @code{@@everyheading} command and +@code{@@everyfooting} command generate page headers and footers +that are the same for both even- and odd-numbered pages. +The @code{@@evenheading} command and @code{@@evenfooting} +command generate headers and footers for even-numbered +(left-hand) pages; and the @code{@@oddheading} command and +@code{@@oddfooting} command generate headers and footers for +odd-numbered (right-hand) pages.@refill Write custom heading specifications in the Texinfo file immediately after the @code{@@end titlepage} command. Enclose your specifications @@ -17038,7 +15874,7 @@ Beware of overlong titles: they may overlap another part of the header or footer and blot it out.@refill -@node Catching Mistakes +@node Catching Mistakes, Refilling Paragraphs, Headings, Top @appendix Formatting Mistakes @cindex Structure, catching mistakes in @cindex Nodes, catching mistakes @@ -17094,7 +15930,7 @@ may want to use the tools described in this appendix.@refill @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes @comment node-name, next, previous, up -@section Catching Errors with Info Formatting +@appendixsec Catching Errors with Info Formatting @cindex Catching errors with Info formatting @cindex Debugging with Info formatting @@ -17275,13 +16111,13 @@ Inside the function @code{texinfo-format-parse-args}, the function @code{re-search-forward} was called; it was this function that could not find the missing right-hand brace.@refill -@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs -Manual}, for more information.@refill +@xref{Lisp Debug, , Debugging Emacs Lisp, xemacs, XEmacs User's Manual}, +for more information.@refill @end ignore @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes @comment node-name, next, previous, up -@section Catching Errors with @TeX{} Formatting +@appendixsec Catching Errors with @TeX{} Formatting @cindex Catching errors with @TeX{} formatting @cindex Debugging with @TeX{} formatting @@ -17363,8 +16199,9 @@ You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} at the @samp{?} prompt.@refill @end enumerate -If you are running @TeX{} inside Emacs, you need to switch to the shell -buffer and line at which @TeX{} offers the @samp{?} prompt. +Please note that if you are running @TeX{} inside Emacs, you need to +switch to the shell buffer and line at which @TeX{} offers the @samp{?} +prompt.@refill Sometimes @TeX{} will format a file without producing error messages even though there is a problem. This usually occurs if a command is not ended @@ -17410,7 +16247,7 @@ directly with @TeX{}, not with Texinfo.)@refill @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes @comment node-name, next, previous, up -@section Using @code{texinfo-show-structure} +@appendixsec Using @code{texinfo-show-structure} @cindex Showing the structure of a file @findex texinfo-show-structure @@ -17454,20 +16291,20 @@ commands respectively. If you move your cursor into the @samp{*Occur*} window, you can position the cursor over one of the lines and use the @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot in the Texinfo file. @xref{Other Repeating -Search, , Using Occur, emacs, The GNU Emacs Manual}, for more +Search, , Using Occur, xemacs, XEmacs User's Manual}, for more information about @code{occur-mode-goto-occurrence}.@refill The first line in the @samp{*Occur*} window describes the @dfn{regular expression} specified by @var{texinfo-heading-pattern}. This regular expression is the pattern that @code{texinfo-show-structure} looks for. -@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, +@xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual}, for more information.@refill When you invoke the @code{texinfo-show-structure} command, Emacs will display the structure of the whole buffer. If you want to see the structure of just a part of the buffer, of one chapter, for example, use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the -region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is +region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is how the example used above was generated. (To see the whole buffer again, use @kbd{C-x n w} (@code{widen}).)@refill @@ -17482,7 +16319,7 @@ or left out a section, you can correct the mistake.@refill @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes @comment node-name, next, previous, up -@section Using @code{occur} +@appendixsec Using @code{occur} @cindex Occurrences, listing with @code{@@occur} @findex occur @@ -17499,10 +16336,10 @@ command directly. To do this, type@refill @noindent and then, when prompted, type a @dfn{regexp}, a regular expression for the pattern you want to match. (@xref{Regexps, , Regular Expressions, -emacs, The GNU Emacs Manual}.) The @code{occur} command works from -the current location of the cursor in the buffer to the end of the -buffer. If you want to run @code{occur} on the whole buffer, place -the cursor at the beginning of the buffer.@refill +xemacs, XEmacs User's Manual}.) The @code{occur} command works from the +current location of the cursor in the buffer to the end of the buffer. +If you want to run @code{occur} on the whole buffer, place the cursor at +the beginning of the buffer.@refill For example, to see all the lines that contain the word @samp{@@chapter} in them, just type @samp{@@chapter}. This will @@ -17517,12 +16354,12 @@ or phrase, end the last word with a @samp{$}; for example, all the nodes that are part of the same chapter or section and therefore have the same `Up' pointer.@refill -@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, +@xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual}, for more information.@refill @node Running Info-Validate, , Using occur, Catching Mistakes @comment node-name, next, previous, up -@section Finding Badly Referenced Nodes +@appendixsec Finding Badly Referenced Nodes @findex Info-validate @cindex Nodes, checking for badly referenced @cindex Checking for badly referenced nodes @@ -17551,7 +16388,7 @@ if you write an Info file from scratch.@refill @end menu @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate -@subsection Running @code{Info-validate} +@appendixsubsec Running @code{Info-validate} @cindex Running @code{Info-validate} @cindex Info validating a large file @cindex Validating a large file @@ -17564,9 +16401,9 @@ M-x Info-validate @end example @noindent -Note that the @code{Info-validate} command requires an upper case +(Note that the @code{Info-validate} command requires an upper case `I'. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}. +@code{Info-validate}. @xref{Tagifying}.)@refill If your file is valid, you will receive a message that says ``File appears valid''. However, if you have a pointer that does not point to a node, @@ -17600,16 +16437,17 @@ This is because every `Next' pointer should be matched by a @code{Info-validate} also checks that all menu entries and cross references point to actual nodes.@refill -@code{Info-validate} requires a tag table and does not work with files -that have been split. (The @code{texinfo-format-buffer} command -automatically splits large files.) In order to use @code{Info-validate} -on a large file, you must run @code{texinfo-format-buffer} with an -argument so that it does not split the Info file; and you must create a -tag table for the unsplit file. +Note that @code{Info-validate} requires a tag table and does not work +with files that have been split. (The @code{texinfo-format-buffer} +command automatically splits large files.) In order to use +@code{Info-validate} on a large file, you must run +@code{texinfo-format-buffer} with an argument so that it does not split +the Info file; and you must create a tag table for the unsplit +file.@refill @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate @comment node-name, next, previous, up -@subsection Creating an Unsplit File +@appendixsubsec Creating an Unsplit File @cindex Creating an unsplit file @cindex Unsplit file creation @@ -17646,7 +16484,7 @@ a tag table for it. @refill @cindex Tag table, making manually @node Tagifying, Splitting, Unsplit, Running Info-Validate -@subsection Tagifying a File +@appendixsubsec Tagifying a File After creating an unsplit Info file, you must create a tag table for it. Visit the Info file you wish to tagify and type:@refill @@ -17684,14 +16522,14 @@ table and split the file manually.@refill @node Splitting, , Tagifying, Running Info-Validate @comment node-name, next, previous, up -@subsection Splitting a File Manually +@appendixsubsec Splitting a File Manually @cindex Splitting an Info file manually @cindex Info file, splitting manually You should split a large file or else let the @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it for you automatically. (Generally you will let one of the formatting -commands do this job for you. @xref{Creating an Info File}.)@refill +commands do this job for you. @xref{Create an Info File}.)@refill The split-off files are called the indirect subfiles.@refill @@ -17734,11 +16572,10 @@ The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.@refill -@node Refilling Paragraphs +@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top @appendix Refilling Paragraphs @cindex Refilling paragraphs @cindex Filling paragraphs -@cindex Paragraphs, filling @findex refill The @code{@@refill} command refills and, optionally, indents the first @@ -17774,11 +16611,10 @@ the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} and therefore do not refill or indent them.@refill -@node Command Syntax +@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top +@comment node-name, next, previous, up @appendix @@-Command Syntax @cindex @@-command syntax -@cindex Syntax, of @@-commands -@cindex Command syntax The character @samp{@@} is used to start special Texinfo commands. (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo @@ -17839,7 +16675,7 @@ Emacs paragraph commands because it cannot appear at the beginning of a line.@refill -@node Obtaining TeX +@node Obtaining TeX, Command and Variable Index, Command Syntax, Top @appendix How to Obtain @TeX{} @cindex Obtaining @TeX{} @cindex @TeX{}, how to obtain @@ -17862,8 +16698,16 @@ available distributions: @end example The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: +Code CD-ROM suitable for printing Texinfo manuals; the University of +Washington maintains and supports a tape distribution; the @TeX{} Users +Group co-sponsors a complete CD-ROM @TeX{} distribution. + +@itemize @bullet + +@item +For the FSF Source Code CD-ROM, please contact: +@iftex @display @group Free Software Foundation, Inc. @@ -17878,6 +16722,54 @@ Free Dial Fax (in Japan): Electronic mail: @code{gnu@@gnu.org} @end group @end display +@end iftex +@ifinfo +@display +@group +Free Software Foundation, Inc. +59 Temple Place Suite 330 +Boston, MA @w{ } 02111-1307 +USA + +Telephone: @w{+1-617-542-5942} +Fax: (including Japan) @w{+1-617-542-2652} +Free Dial Fax (in Japan): +@w{ } @w{ } @w{ } 0031-13-2473 (KDD) +@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) +Electronic mail: @code{gnu@@gnu.org} +@end group +@end display +@end ifinfo + +@item +To order a complete distribution on CD-ROM, please see +@uref{http://tug.org/tex-live.html}. (This distribution is also +available by FTP; see the URL's above.) + +@item +To order a full distribution from the University of Washington on either +a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge, +send $210 to: + +@display +@group +Pierre A. MacKay +Denny Hall, Mail Stop DH-10 +University of Washington +Seattle, WA @w{ } 98195 +USA +Telephone: +1-206-543-2268 +Electronic mail: @code{mackay@@cs.washington.edu} +@end group +@end display + +@noindent +Please make checks payable to the University of Washington. +Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas +sites: please add to the base cost, if desired, $20.00 for shipment via +air parcel post, or $30.00 for shipment via courier. + +@end itemize Many other @TeX{} distributions are available; see @uref{http://tug.org/}. @@ -17885,8 +16777,7 @@ Many other @TeX{} distributions are available; see @c These are no longer ``new'', and the explanations @c are all given elsewhere anyway, I think. --karl, 25apr97. -@c So ignore the entire appendix. -@ignore +@ignore (the entire appendix) @c node New Features, Command and Variable Index, Obtaining TeX, Top @c appendix Second Edition Features @@ -17904,10 +16795,10 @@ edition.@refill Here is a brief description of the new commands.@refill -@c menu +@menu * New Texinfo Mode Commands:: The updating commands are especially useful. * New Commands:: Many newly described @@-commands. -@c end menu +@end menu @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX @c appendixsec New Texinfo Mode Commands @@ -18095,8 +16986,8 @@ Indent descriptions in menus. Insert node pointers in strict sequence. @end table -@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX -@c appendix.sec New Texinfo @@-Commands +@c node New Commands, , New Texinfo Mode Commands, Obtaining TeX +@c appendixsec New Texinfo @@-Commands The second edition of the Texinfo manual describes more than 50 commands that were not described in the first edition. A third or so @@ -18311,7 +17202,7 @@ see @ref{Overfull hboxes},@* see @ref{Footnotes},@* see @ref{dmn, , Format a Dimension},@* see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* -see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* +see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@* see @ref{minus, , Inserting a Minus Sign},@* see @ref{paragraphindent, , Paragraph Indenting},@* see @ref{Cross Reference Commands},@* @@ -18373,8 +17264,8 @@ Insert the current date. @end tex @end ignore - -@node Command and Variable Index +@node Command and Variable Index, Concept Index, Obtaining TeX, Top +@comment node-name, next, previous, up @unnumbered Command and Variable Index This is an alphabetical list of all the @@-commands, assorted Emacs Lisp @@ -18384,10 +17275,12 @@ commands are listed without their preceding @samp{@@}.@refill @printindex fn -@node Concept Index +@node Concept Index, , Command and Variable Index, Top @unnumbered Concept Index @printindex cp +@summarycontents +@contents @bye diff --git a/man/xemacs-faq.texi b/man/xemacs-faq.texi index be50d8a..ef0b785 100644 --- a/man/xemacs-faq.texi +++ b/man/xemacs-faq.texi @@ -7,7 +7,7 @@ @finalout @titlepage @title XEmacs FAQ -@subtitle Frequently asked questions about XEmacs @* Last Modified: $Date: 1999/11/20 20:16:50 $ +@subtitle Frequently asked questions about XEmacs @* Last Modified: $Date: 1999/12/07 03:11:46 $ @sp 1 @author Tony Rossini @author Ben Wing @@ -15,6 +15,7 @@ @author Steve Baur @author Andreas Kaempf @author Christian Nyb@o{} +@author Sandra Wambold @page @end titlepage @@ -88,6 +89,7 @@ library directory>/info/}. For example in * Customization:: Customization and Options. * Subsystems:: Major Subsystems. * Miscellaneous:: The Miscellaneous Stuff. +* MS Windows:: XEmacs on Microsoft Windows. * Current Events:: What the Future Holds. @detailmenu @@ -377,12 +379,38 @@ Miscellaneous: * Q5.3.11:: How do I add new Info directories? * Q5.3.12:: What do I need to change to make printing work? -What the Future Holds +XEmacs on MS Windows -* Q6.0.1:: What is new in 20.2? -* Q6.0.2:: What is new in 20.3? -* Q6.0.3:: What is new in 20.4? -* Q6.0.4:: Procedural changes in XEmacs development. +General Info: +* Q6.0.1:: What is the status of the XEmacs port to Windows? +* Q6.0.2:: What flavors of MS Windows are supported? +* Q6.0.3:: Are binary kits available? +* Q6.0.4:: Does XEmacs on MS Windows require an X server to run? + +Building XEmacs on MS Windows: +* Q6.1.1:: I decided to run with X. Where do I get an X server? +* Q6.1.2:: What compiler do I need to compile XEmacs? +* Q6.1.3:: How do I compile for the native port? +* Q6.1.4:: How do I compile for the X port? +* Q6.1.5:: How do I compile for Cygnus' Cygwin? +* Q6.1.6:: What do I need for Cygwin? + +Customization and User Interface: +* Q6.2.1:: How will the port cope with differences in the Windows user interface? +* Q6.2.2:: How do I change fonts in XEmacs on MS Windows? +* Q6.2.3:: Where do I put my @file{.emacs} file? + +Miscellaneous: +* Q6.3.1:: Will XEmacs rename all the win32-* symbols to w32-*? +* Q6.3.2:: What are the differences between the various MS Windows emacsen? +* Q6.3.3:: What is the porting team doing at the moment? + +Current Events: + +* Q7.0.1:: What is new in 20.2? +* Q7.0.2:: What is new in 20.3? +* Q7.0.3:: What is new in 20.4? +* Q7.0.4:: Procedural changes in XEmacs development. @end detailmenu @end menu @@ -477,6 +505,8 @@ track changes to GNU Emacs while also working to add new features. @node Q1.0.2, Q1.0.3, Q1.0.1, Introduction @unnumberedsubsec Q1.0.2: What is the current version of XEmacs? +XEmacs 21.1.8 is the current stable version of XEmacs. + XEmacs 20.4 is a minor upgrade from 20.3, containing many bugfixes. It was released in February 1998. @@ -486,7 +516,7 @@ which was also the last version without international language support. @node Q1.0.3, Q1.0.4, Q1.0.2, Introduction @unnumberedsubsec Q1.0.3: Where can I find it? -The canonical source and binaries is found via anonymous FTP at: +The canonical source and binaries can be found via anonymous FTP at: @example @uref{ftp://ftp.xemacs.org/pub/xemacs/} @@ -498,7 +528,7 @@ The canonical source and binaries is found via anonymous FTP at: For a detailed description of the differences between GNU Emacs and XEmacs and a detailed history of XEmacs, check out the @example -@uref{http://www.xemacs.org/NEWS.html, NEWS file} +@uref{http://www.xemacs.org/About/XEmacsVsGNUemacs.html, NEWS file} @end example However, here is a list of some of the reasons why we think you might @@ -580,44 +610,37 @@ that often result. Mail your questions to @email{xemacs-beta@@xemacs.org} and @node Q1.0.6, Q1.0.7, Q1.0.5, Introduction @unnumberedsubsec Q1.0.6: Where can I get help? -Probably the easiest way, if everything is installed, is to use info, by -pressing @kbd{C-h i}, or selecting @code{Manuals->Info} from the Help Menu. - -Also, @kbd{M-x apropos} will look for commands for you. +Probably the easiest way, if everything is installed, is to use Info, by +pressing @kbd{C-h i}, or selecting @code{Manuals->Info} from the +Help Menu. @kbd{M-x apropos} can be used to look for particular commands. -Try reading this FAQ, examining the regular GNU Emacs FAQ (which can be -found with the Emacs 19 distribution) as well as at -@uref{http://www.eecs.nwu.edu/emacs/faq/} and reading the Usenet group -comp.emacs.xemacs. +For items not found in the manual, try reading this FAQ +@comment , examining the regular GNU Emacs FAQ (which can be +@comment found with the Emacs 19 distribution) as well as at +@comment @uref{http://www.eecs.nwu.edu/emacs/faq/} +and reading the Usenet group comp.emacs.xemacs. -If that does not help, try posting your question to comp.emacs.xemacs. -Please @strong{do not} post XEmacs related questions to gnu.emacs.help. +If you choose to post to a newsgroup, @strong{please use +comp.emacs.xemacs}. Please do not post XEmacs related questions to +gnu.emacs.help. If you cannot post or read Usenet news, there is a corresponding mailing list which is available. It can be subscribed to by sending a message -with a subject of @samp{subscribe} to @email{xemacs-request@@xemacs.org} -for subscription information and @email{xemacs@@xemacs.org} to send messages -to the list. - -To cancel a subscription, you @strong{must} use the xemacs-request -address. Send a message with a subject of @samp{unsubscribe} to be -removed. +to @email{xemacs-request@@xemacs.org} with @samp{subscribe} in the +body of the message. Send to the list at @email{xemacs@@xemacs.org}. +list. To cancel a subscription, you @strong{must} use the +xemacs-request address. Send a message with a subject of +@samp{unsubscribe} to be removed. @node Q1.0.7, Q1.0.8, Q1.0.6, Introduction @unnumberedsubsec Q1.0.7: Where is the mailing list archived? -The mailing list was archived in the directory -@example -@uref{ftp://ftp.xemacs.org/pub/mlists/}. -@end example - -However, this archive is out of date. The current mailing list server -supports an @code{archive} feature, which may be utilized. +The archives can be found at @uref{http://www.xemacs.org/Lists/Archive} @node Q1.0.8, Q1.0.9, Q1.0.7, Introduction @unnumberedsubsec Q1.0.8: How do you pronounce XEmacs? -I pronounce it @samp{Eks eemax}. +The most common pronounciation is @samp{Eks eemax}. @node Q1.0.9, Q1.0.10, Q1.0.8, Introduction @unnumberedsubsec Q1.0.9: What does XEmacs look like? @@ -630,40 +653,42 @@ Screen snapshots are available in the WWW version of the FAQ. @node Q1.0.10, Q1.0.11, Q1.0.9, Introduction @unnumberedsubsec Q1.0.10: Is there a port of XEmacs to Microsoft ('95 or NT)? -Thanks to efforts of many people, coordinated by -@email{davidh@@wr.com.au, David Hobley} and @email{marcpa@@cam.org, Marc -Paquette}, beta versions of XEmacs now run on 32-bit Windows platforms -(NT and 95). The current betas require having an X server to run -XEmacs; however, a native NT/95 port is in alpha, thanks to -@email{jhar@@tardis.ed.ac.uk, Jonathan Harris}. - -Although some features are still unimplemented, XEmacs 21.0 will support -MS-Windows. - -The NT development is now coordinated by a mailing list at -@email{xemacs-nt@@xemacs.org}. - -If you are willing to contribute or want to follow the progress, mail to -@iftex -@* -@end iftex -@email{xemacs-nt-request@@xemacs.org} to subscribe. - -Furthermore, Altrasoft is seeking corporate and government sponsors to -help fund a fully native port of XEmacs to Windows 95 and NT using -full-time, senior-level staff working under a professionally managed -project structure. See @uref{http://www.altrasoft.com/, the Altrasoft -web site} for more details -or contact Altrasoft directly at 1-888-ALTSOFT. - - -The closest existing port is @dfn{Win-Emacs}, which is based on Lucid -Emacs 19.6. Available from @uref{http://www.pearlsoft.com/}. - -There's a port of GNU Emacs (not XEmacs) at -@example -@uref{http://www.cs.washington.edu/homes/voelker/ntemacs.html}. -@end example +Yes, @xref{MS Windows}. + +@comment Thanks to efforts of many people, coordinated by +@comment @email{davidh@@wr.com.au, David Hobley} and @email{marcpa@@cam.org, Marc +@comment Paquette}, beta versions of XEmacs now run on 32-bit Windows platforms +@comment (NT and 95). The current betas require having an X server to run +@comment XEmacs; however, a native NT/95 port is in alpha, thanks to +@comment @email{jhar@@tardis.ed.ac.uk, Jonathan Harris}. +@comment +@comment Although some features are still unimplemented, XEmacs 21.0 will support +@comment MS-Windows. +@comment +@comment The NT development is now coordinated by a mailing list at +@comment @email{xemacs-nt@@xemacs.org}. +@comment +@comment If you are willing to contribute or want to follow the progress, mail to +@comment @iftex +@comment @* +@comment @end iftex +@comment @email{xemacs-nt-request@@xemacs.org} to subscribe. +@comment +@comment Furthermore, Altrasoft is seeking corporate and government sponsors to +@comment help fund a fully native port of XEmacs to Windows 95 and NT using +@comment full-time, senior-level staff working under a professionally managed +@comment project structure. See @uref{http://www.altrasoft.com/, the Altrasoft +@comment web site} for more details +@comment or contact Altrasoft directly at 1-888-ALTSOFT. +@comment +@comment +@comment The closest existing port is @dfn{Win-Emacs}, which is based on Lucid +@comment Emacs 19.6. Available from @uref{http://www.pearlsoft.com/}. +@comment +@comment There's a port of GNU Emacs (not XEmacs) at +@comment @example +@comment @uref{http://www.cs.washington.edu/homes/voelker/ntemacs.html}. +@comment @end example @node Q1.0.11, Q1.0.12, Q1.0.10, Introduction @unnumberedsubsec Q1.0.11: Is there a port of XEmacs to the Macintosh? @@ -691,39 +716,24 @@ No, and there is no news of anyone working on it. @node Q1.0.14, Q1.1.1, Q1.0.13, Introduction @unnumberedsubsec Q1.0.14: Where can I obtain a printed copy of the XEmacs users manual? -Altrasoft Associates, a firm specializing in Emacs-related support and -development, will be maintaining the XEmacs user manual. The firm plans -to begin publishing printed copies of the manual soon. -@c This used to say `March 1997'! +Pre-printed manuals are not available. If you are familiar with +TeX, you can generate your own manual from the XEmacs sources. + +HTML and Postscript versions of XEmacs manuals may be available from the +XEmacs web site in the future. -@example - Web: @uref{http://www.xemacs.com} - E-mail: @email{info@@xemacs.com} - Tel: +1 408 243 3300 -@end example @node Q1.1.1, Q1.1.2, Q1.0.14, Introduction @unnumberedsec 1.1: Policies @unnumberedsubsec Q1.1.1: What is the FAQ editorial policy? The FAQ is actively maintained and modified regularly. All links should -be up to date. - -Changes are displayed on a monthly basis. @dfn{Months}, for this -purpose are defined as the 5th of the month through the 5th of the -month. Preexisting questions that have been changed are marked as such. -Brand new questions are tagged. - -All submissions are welcome. E-mail submissions -to -@iftex -@* -@end iftex -@email{faq@@xemacs.org, Christian Nyb@o{}}. +be up to date. All submissions are welcome. E-mail submissions to +@email{faq@@xemacs.org, XEmacs FAQ maintainers}. Please make sure that @samp{XEmacs FAQ} appears on the Subject: line. If you think you have a better way of answering a question, or think a -question should be included, I'd like to hear about it. Questions and +question should be included, we'd like to hear about it. Questions and answers included into the FAQ will be edited for spelling and grammar, and will be attributed. Answers appearing without attribution are either from versions of the FAQ dated before May 1996, or are from one @@ -734,8 +744,8 @@ author. @node Q1.1.2, Q1.1.3, Q1.1.1, Introduction @unnumberedsubsec Q1.1.2: How do I become a Beta Tester? -Send an email message to @email{xemacs-beta-request@@xemacs.org} with a -subject line of @samp{subscribe}. +Send an email message to @email{xemacs-beta-request@@xemacs.org} with +the line @samp{subscribe} in the body of the message. Be prepared to get your hands dirty, as beta testers are expected to identify problems as best they can. @@ -966,14 +976,12 @@ characters. @node Q1.3.2, Q1.3.3, Q1.3.1, Introduction @unnumberedsubsec Q1.3.2: What is the status of Asian-language support, aka MULE? -The MULE support works OK but still needs a fair amount of work before -it's really solid. We could definitely use some help here, esp. people -who speak Japanese and will use XEmacs/MULE to work with Japanese and -have some experience with E-Lisp. +MULE support is now available for UNIX versions of XEmacs. -As the fundings on Mule have stopped, the Mule part of XEmacs is currently -looking for a full-time maintainer. If you can provide help here, or -are willing to fund the work, please mail to @email{xemacs-beta@@xemacs.org}. +If you would like to help, you may want to join the +@email{xemacs-mule@@xemacs.org} mailing list. Especially needed are +people who speak/write languages other than English, who are willing to +use XEmacs/MULE regularly, and have some experience with Elisp. @xref{Q1.1.2}. @@ -1167,18 +1175,18 @@ There's the XEmacs tutorial available from the Help Menu under it's available in a non-english language, type @kbd{C-u C-h t TAB}, type the first letters of your preferred language, then type @key{RET}. -There's an Emacs Lisp tutorial at - -@example -@uref{ftp://prep.ai.mit.edu/pub/gnu/emacs-lisp-intro-1.04.tar.gz}. -@end example - -@email{erik@@petaxp.rug.ac.be, Erik Sundermann} has made a tutorial web -page at -@iftex -@* -@end iftex -@uref{http://petaxp.rug.ac.be/~erik/xemacs/}. +@comment There's an Emacs Lisp tutorial at +@comment +@comment @example +@comment @uref{ftp://prep.ai.mit.edu/pub/gnu/emacs-lisp-intro-1.04.tar.gz}. +@comment @end example +@comment +@comment @email{erik@@petaxp.rug.ac.be, Erik Sundermann} has made a tutorial web +@comment page at +@comment @iftex +@comment @* +@comment @end iftex +@comment @uref{http://petaxp.rug.ac.be/~erik/xemacs/}. @node Q1.4.4, Q1.4.5, Q1.4.3, Introduction @unnumberedsubsec Q1.4.4: May I see an example of a useful XEmacs Lisp function? @@ -2381,8 +2389,8 @@ corresponding to the configure options used when building XEmacs. @node Q2.1.16, Q2.1.17, Q2.1.15, Installation @unnumberedsubsec Q2.1.16: XEmacs crashes in @code{strcat} on HP/UX 10 ->From the problems database (through -@uref{http://support.mayfield.hp.com/}): +From the problems database (through +the former address http://support.mayfield.hp.com/): @example Problem Report: 5003302299 @@ -2735,7 +2743,7 @@ It's almost always a mistake to test @code{emacs-version} or any similar variables. Instead, use feature-tests, such as @code{featurep}, @code{boundp}, -@code{fboundp}, or even simple behaviroal tests, eg.: +@code{fboundp}, or even simple behavioral tests, eg.: @lisp (defvar foo-old-losing-code-p @@ -4471,12 +4479,11 @@ tm has following functions: tm is available from following anonymous ftp sites: @itemize @bullet -@item @uref{ftp://ftp.jaist.ac.jp/pub/GNU/elisp/mime/} (Japan). -@item @uref{ftp://ftp.nis.co.jp/pub/gnu/emacs-lisp/tm/} (Japan). -@c The host above is unknown. - -@item @uref{ftp://ftp.nisiq.net/pub/gnu/emacs-lisp/tm/} (US). -@item @uref{ftp://ftp.miranova.com/pub/gnus/jaist.ac.jp/} (US). +@comment @item @uref{ftp://ftp.jaist.ac.jp/pub/GNU/elisp/mime/} (Japan). +@comment @item @uref{ftp://ftp.nis.co.jp/pub/gnu/emacs-lisp/tm/} (Japan). +@comment @c The host above is unknown. +@comment @item @uref{ftp://ftp.nisiq.net/pub/gnu/emacs-lisp/tm/} (US). +@comment @item @uref{ftp://ftp.miranova.com/pub/gnus/jaist.ac.jp/} (US). @item @uref{ftp://ftp.unicamp.br/pub/mail/mime/tm/} (Brasil). @item @uref{ftp://ftp.th-darmstadt.de/pub/editors/GNU-Emacs/lisp/mime/} (Germany). @item @uref{ftp://ftp.tnt.uni-hannover.de/pub/editors/xemacs/contrib/} (Germany). @@ -4582,7 +4589,7 @@ details, check out @iftex @* @end iftex -@uref{http://www.sun.com/software/Products/Developer-products/programs.html}. +@uref{http://www.sun.com/software/Products/Developer-products}. @end quotation @node Q4.4.2, Q4.5.1, Q4.4.1, Subsystems @@ -4928,13 +4935,15 @@ One way to do this (and much more) is by using the @iftex @* @end iftex -@uref{ftp://ftp.mathworks.com/pub/contrib/v5/tools/matlab.el, matlab mode}. +@comment @uref{ftp://ftp.mathworks.com/pub/contrib/v5/tools/matlab.el, matlab mode}. +matlab mode. (If someone knows where this can be found, please contact +the @email{faq@@xemacs.org,XEmacs FAQ maintainer}. Instructions on how to install this mode are included in this file. @end quotation -@node Miscellaneous, Current Events, Subsystems, Top +@node Miscellaneous, MS Windows, Subsystems, Top @unnumbered 5 The Miscellaneous Stuff This is part 5 of the XEmacs Frequently Asked Questions list. This @@ -5299,7 +5308,7 @@ if ( "$TERM" == emacs || "$TERM" == unknown ) unset filec @email{bwarsaw@@cnri.reston.va.us, Barry A. Warsaw} writes: @quotation -This can be had from @uref{http://www.python.org/ftp/emacs/}. +This can be had from @uref{http://www.python.org/emacs/}. @end quotation @node Q5.0.16, Q5.0.17, Q5.0.15, Miscellaneous @@ -6080,8 +6089,9 @@ method, one should NOT quote the face string using the sed script . It might also be helpful to use @email{stig@@hackvan.com, Stig's} script (included in the compface distribution at XEmacs.org) to do the -conversion. For convenience xbm2xface is available for anonymous FTP at -@uref{ftp://ftp.miranova.com/pub/xemacs/xbm2xface.pl}. +conversion. +@comment For convenience xbm2xface is available for anonymous FTP at +@comment @uref{ftp://ftp.miranova.com/pub/xemacs/xbm2xface.pl}. Contributors for this item: @@ -6182,25 +6192,394 @@ NOTE: It is an undocumented limitation in XEmacs that postscript printing (the @code{Pretty Print Buffer} menu item) @strong{requires} a window system environment. It cannot be used outside of X11. -@node Current Events, , Miscellaneous, Top -@unnumbered 6 What the Future Holds +@node MS Windows, Current Events, Miscellaneous, Top +@unnumbered 6 XEmacs on MS Windows + +This is part 6 of the XEmacs Frequently Asked Questions list, written by +Hrvoje Niksic and others. This section is devoted to the MS Windows +port of XEmacs. + +@menu + +General Info +* Q6.0.1:: What is the status of the XEmacs port to Windows? +* Q6.0.2:: What flavors of MS Windows are supported? +* Q6.0.3:: Where are the XEmacs on MS Windows binaries? +* Q6.0.4:: Does XEmacs on MS Windows require an X server to run? + +Building XEmacs on MS Windows +* Q6.1.1:: I decided to run with X. Where do I get an X server? +* Q6.1.2:: What compiler do I need to compile XEmacs? +* Q6.1.3:: How do I compile for the native port? +* Q6.1.4:: How do I compile for the X port? +* Q6.1.5:: How do I compile for Cygnus' Cygwin? +* Q6.1.6:: What do I need for Cygwin? + +Customization and User Interface +* Q6.2.1:: How will the port cope with differences in the Windows user interface? +* Q6.2.2:: How do I change fonts in XEmacs on MS Windows? +* Q6.2.3:: Where do I put my @file{.emacs} file? + +Miscellaneous +* Q6.3.1:: Will XEmacs rename all the win32-* symbols to w32-*? +* Q6.3.2:: What are the differences between the various MS Windows emacsen? +* Q6.3.3:: What is the porting team doing at the moment? + +@end menu + +@node Q6.0.1, Q6.0.2, MS Windows, MS Windows +@unnumberedsec 6.0: General Info +@unnumberedsubsec Q6.0.1: What is the status of the XEmacs port to Windows? + +Is XEmacs really getting ported to MS Windows? What is the status of the port? + +Yes, a group of volunteers actively works on making XEmacs code base +cleanly compile and run on MS Windows operating systems. The mailing +list at @email{xemacs-nt@@xemacs.org} is dedicated to that effort (please use +the -request address to subscribe). + +At this time, XEmacs on MS Windows is usable, but lacks some of the +features of XEmacs on UNIX and UNIX-like systems. Notably, +internationalization does not work. + +@node Q6.0.2, Q6.0.3, Q6.0.1, MS Windows +@unnumberedsubsec Q6.0.2: What flavors of MS Windows are supported? The list name implies NT only. + +The list name is misleading, as XEmacs will support both Windows 95, +Windows 98 and Windows NT. The MS Windows-specific code is based on +Microsoft Win32 API, and will not work on MS Windows 3.x or on MS-DOS. + + +@node Q6.0.3, Q6.0.4, Q6.0.2, MS Windows +@unnumberedsubsec Q6.0.3: Are binary kits available? + +Binary kits are available at +@uref{ftp://ftp.xemacs.org/pub/xemacs/binary-kits/win32/} for the +"plain" MS Windows version. + +@node Q6.0.4, Q6.1.1, Q6.0.3, MS Windows +@unnumberedsubsec Q6.0.4: Does XEmacs on MS Windows require an X server to run? + +Short answer: No. + +Long answer: XEmacs can be built in several ways in the MS Windows +environment, some of them requiring an X server and some not. + +One is what we call the "X" port -- it requires X libraries to build +and an X server to run. Internally it uses the Xt event loop and +makes use of X toolkits. Its look is quite un-Windowsy, but it works +reliably and supports all of the graphical features of Unix XEmacs. + +The other is what we call the "native" port. It uses the Win32 API +and does not require X libraries to build, nor does it require an X to +run. In fact, it has no connection with X whatsoever. At this time, +the native port obsoletes the X port, providing almost all of its +features, including support for menus, scrollbars, toolbars, embedded +images and background pixmaps, frame pointers, etc. Most of the +future work will be based on the native port. + +There is also a third special case, the Cygwin port. It takes +advantage of Cygnus emulation library under Win32, which enables it to +reuse much of the Unix XEmacs code base, such as processes and network +support, or internal select() mechanisms. + +Cygwin port supports all display types -- TTY, X & MS gui, and can be +built with support for all three. If you build with ms gui support +then the Cygwin version uses the majority of the msw code, which is +mostly related to display. If you want to build with X support you +need X libraries. If you want to build with tty support you need +ncurses. MS gui requires no additional libraries. + +Some of the advantages of the Cygwin version are that it: + +@itemize @bullet + +@item integrates well with Cygwin environment for existing Cygwin users; +@item uses configure so building with different features is very easy; +@item has process support in X & tty. + +@end itemize + +The disadvantage is that it requires several Unix utilities and the +whole Cygwin environment, whereas the native port requires only a +suitable MS Windows compiler. Also, it follows the Unix filesystem and +process model very closely (some will undoubtedly view this as an +advantage). + +@node Q6.1.1, Q6.1.2, Q6.0.4, MS Windows +@unnumberedsec 6.1: Building XEmacs on MS Windows +@unnumberedsubsec Q6.1.1: I decided to run with X. Where do I get an X server? + +Pointers to X servers can be found at +@iftex +@* +@end iftex +@uref{http://dao.gsfc.nasa.gov/software/grads/win32/X11R6.3/}; + +look for "Where to get an X server". Also note that, although the above +page talks about Cygnus gnu-win32 (Cygwin), the information on X servers +is Cygwin-independent. You don't have to be running/using Cygwin to use +these X servers, and you don't have to compile XEmacs under Cygwin to +use XEmacs with these X servers. An "X port" XEmacs compiled under +Visual C++ will work with these X servers (as will XEmacs running on a +Unix box, redirected to the server running on your PC). + + +@node Q6.1.2, Q6.1.3, Q6.1.1, MS Windows +@unnumberedsubsec Q6.1.2: What compiler do I need to compile XEmacs? + +You need Visual C++ 4.2 or 5.0, with the exception of the Cygwin port, +which uses Gcc. + + +@node Q6.1.3, Q6.1.4, Q6.1.2, MS Windows +@unnumberedsubsec Q6.1.3: How do I compile for the native port? + +Please read the file @file{nt/README} in the XEmacs distribution, which +contains the full description. + + +@node Q6.1.4, Q6.1.5, Q6.1.3, MS Windows +@unnumberedsubsec Q6.1.4: How do I compile for the X port? + +Again, it is described in @file{nt/README} in some detail. Basically, you +need to get X11 libraries from ftp.x.org, and compile them. If the +precompiled versions are available somewhere, I don't know of it. + + +@node Q6.1.5, Q6.1.6, Q6.1.4, MS Windows +@unnumberedsubsec Q6.1.5: How do I compile for Cygnus' Cygwin? + +Similar as on Unix; use the usual `configure' and `make' process. +Some problems to watch out for: + +@itemize @bullet +@item +make sure HOME is set. This controls where you @file{.emacs} file comes +from; + +@item +CYGWIN32 needs to be set to tty for process support +work. e.g. CYGWIN32=tty; + +@item +picking up some other grep or other unix like tools can kill configure; + +@item +static heap too small, adjust src/sheap-adjust.h to a more positive +number; + +@item +The Cygwin version doesn't understand @file{//machine/path} type paths so you +will need to manually mount a directory of this form under a unix style +directory for a build to work on the directory. + +@end itemize + +@node Q6.1.6, Q6.2.1, Q6.1.5, MS Windows +@unnumberedsubsec Q6.1.6: What do I need for Cygwin? + +You can find the Cygwin tools and compiler at: + +@uref{http://sourceware.cygnus.com/cygwin/} + +You will need version b19 or later. + +You will also need the X libraries. There are libraries at +@iftex +@* +@end iftex +@uref{http://dao.gsfc.nasa.gov/software/grads/win32/X11R6.3/}, but +these are not b19 compatible. You can get b19 X11R6.3 binaries, as +well as pre-built ncurses and graphic libraries, from: + +@uref{ftp://ftp.parallax.co.uk/pub/andyp/}. + + +@node Q6.2.1, Q6.2.2, Q6.1.6, MS Windows +@unnumberedsec 6.2: Customization and User Interface +@unnumberedsubsec Q6.2.1: How will the port cope with differences in the Windows user interface? + +XEmacs (and Emacs in general) UI is pretty +different from what is expected of a typical MS Windows program. How will +the MS Windows port cope with it? + +Fortunately, Emacs is also one of the most configurable editor beasts +in the world. The MS Windows "look and feel" (mark via shift-arrow, +self-inserting deletes region, etc.) can be easily configured via +various packages distributed with XEmacs. The `pending-delete' +package is an example of such a utility. + +In future versions, some of these packages might be turned on by +default in the MS Windows environment. + + +@node Q6.2.2, Q6.2.3, Q6.2.1, MS Windows +@unnumberedsubsec Q6.2.2: How do I change fonts in XEmacs on MS Windows? + +You can change font manually, but not from the menubar, yet. For +example: + +@display + (set-face-font 'default "Lucida Console:Regular:10") + (set-face-font 'modeline "MS Sans Serif:Regular:10") +@end display + + +@node Q6.2.3, Q6.3.1, Q6.2.2, MS Windows +@unnumberedsubsec Q6.2.3: Where do I put my @file{.emacs} file? + +If the HOME environment variable is set, @file{.emacs} will be looked for +there. Else the directory defaults to `c:\'. + +@node Q6.3.1, Q6.3.2, Q6.2.3, MS Windows +@unnumberedsec 6.3: Miscellaneous +@unnumberedsubsec Q6.3.1: Will XEmacs rename all the win32-* symbols to w32-*? + +In his flavor of Emacs 20, Richard Stallman has renamed all the win32-* +symbols to w32-*. Will XEmacs do the same? + +We consider such a move counter-productive, thus we will not use the +`w32' prefix. However, we do recognize that Win32 name is little more +than a marketing buzzword (will it be Win64 in the next release?), so +we decided not to use it. Using `windows-' would be wrong because the +term is too generic, which is why we settled on a compromise +`mswindows' term. + +Thus all the XEmacs variables and functions directly related to Win32 +are prefixed `mswindows-'. The user-variables shared with NT Emacs +will be provided as compatibility aliases. + +Architectural note: We believe that there should be a very small +number of window-systems-specific variables, and will try to provide +generic interfaces whenever possible. + + +@node Q6.3.2, Q6.3.3, Q6.3.1, MS Windows +@unnumberedsubsec Q6.3.2: What are the differences between the various MS Windows emacsen? + +XEmacs, Win-Emacs, DOS Emacs, NT Emacs, this is all very confusing. +Could you briefly explain the differences between them? + +Here is a recount of various Emacs versions running on MS Windows: + +@itemize @bullet + +@item +Win-Emacs + +@itemize @minus + +@item +Win-Emacs is a port of Lucid Emacs 19.6 to MS Windows using X +compatibility libraries. Win-Emacs has been written by Ben Wing. The +MS Windows code has not made it back to Lucid Emacs, which left Win-Emacs +pretty much dead for our purposes. Win-Emacs used to be available at +Pearlsoft, but not anymore, since Pearlsoft went out of business. +@end itemize + +@item +GNU Emacs for DOS + +@itemize @minus + +@item +GNU Emacs features support for MS-DOS and DJGPP (D.J. Delorie's DOS +port of Gcc). Such an Emacs is heavily underfeatured, because it does +not supports long file names, lacks proper subprocesses support, and +is far too big compared to typical DOS editors. +@end itemize + +@item +GNU Emacs compiled with Win32 + +@itemize @minus + +@item +Starting with version 19.30, it has been possible to compile GNU Emacs +under MS Windows using the DJGPP compiler and X libraries. The result +is is very similar to GNU Emacs compiled under MS DOS, only it +supports longer file names, etc. This "port" is similar to the "X" +flavor of XEmacs on MS Windows. +@end itemize + +@item +NT Emacs + +@itemize @minus + +@item +NT Emacs is a version of GNU Emacs modified to compile and run under +MS MS Windows 95 and NT using the native Win32 API. As such, it is close +in spirit to the XEmacs "native" port. + +@item +NT Emacs has been written by Geoff Voelker, and more information can be +found at +@iftex +@* +@end iftex +@uref{http://www.cs.washington.edu/homes/voelker/ntemacs.html}. + +@end itemize + +@item +XEmacs + +@itemize @minus + +@item +Beginning with XEmacs 19.12, XEmacs' architecture has been redesigned +in such a way to allow clean support of multiple window systems. At +this time the TTY support was added, making X and TTY the first two +"window systems" XEmacs supported. The 19.12 design is the basis for +the current native MS Windows code. + +@item +Some time during 1997, David Hobley (soon joined by Marc Paquette) +imported some of the NT-specific portions of GNU Emacs, making XEmacs +with X support compile under Windows NT, and creating the "X" port. + +@item +Several months later, Jonathan Harris sent out initial patches to use +the Win32 API, thus creating the native port. Since then, various +people have contributed, including Kirill M. Katsnelson (contributed +support for menubars, subprocesses and network, as well as loads of +other code), Andy Piper (ported XEmacs to Cygwin environment, +contributed Windows unexec, Windows-specific glyphs and toolbars code, +and more), Jeff Sparkes (contributed scrollbars support) and many +others. + +@end itemize + +@end itemize + + +@node Q6.3.3, , Q6.3.2, MS Windows +@unnumberedsubsec Q6.3.3: What is the porting team doing at the moment? + +The porting team is continuing work on the MS Windows-specific code. + + +@node Current Events, , MS Windows, Top +@unnumbered 7 What the Future Holds -This is part 6 of the XEmacs Frequently Asked Questions list. This +This is part 7 of the XEmacs Frequently Asked Questions list. This section will change monthly, and contains any interesting items that have transpired over the previous month. If you are reading this from the XEmacs distribution, please see the version on the Web or archived at the various FAQ FTP sites, as this file is surely out of date. @menu -* Q6.0.1:: What is new in 20.2? -* Q6.0.2:: What is new in 20.3? -* Q6.0.3:: What is new in 20.4? -* Q6.0.4:: Procedural changes in XEmacs development. +* Q7.0.1:: What is new in 20.2? +* Q7.0.2:: What is new in 20.3? +* Q7.0.3:: What is new in 20.4? +* Q7.0.4:: Procedural changes in XEmacs development. @end menu -@node Q6.0.1, Q6.0.2, Current Events, Current Events -@unnumberedsec 6.0: Changes -@unnumberedsubsec Q6.0.1: What is new in 20.2? +@node Q7.0.1, Q7.0.2, Current Events, Current Events +@unnumberedsec 7.0: Changes +@unnumberedsubsec Q7.0.1: What is new in 20.2? The biggest changes in 20.2 include integration of EFS (the next generation of ange-ftp) and AUC Tex (the Emacs subsystem that includes a @@ -6212,8 +6591,8 @@ customize}. XEmacs 20.2 is the development release (20.0 was beta), and is no longer considered unstable. -@node Q6.0.2, Q6.0.3, Q6.0.1, Current Events -@unnumberedsubsec Q6.0.2: What is new in 20.3? +@node Q7.0.2, Q7.0.3, Q7.0.1, Current Events +@unnumberedsubsec Q7.0.2: What is new in 20.3? XEmacs 20.3 was released in November 1997. It contains many bugfixes, and a number of new features, including Autoconf 2 based configuration, @@ -6232,15 +6611,15 @@ the default) is definitely faster than XEmacs 19.16. XEmacs 20.3 is the first non-beta v20 release, and will be the basis for all further development. -@node Q6.0.3, Q6.0.4, Q6.0.2, Current Events -@unnumberedsubsec Q6.0.3: What's new in XEmacs 20.4? +@node Q7.0.3, Q7.0.4, Q7.0.2, Current Events +@unnumberedsubsec Q7.0.3: What's new in XEmacs 20.4? XEmacs 20.4 is a bugfix release with no user-visible changes. @c Filled in from NEWS file of 20.5-b33 -@node Q6.0.4, , Q6.0.3, Current Events -@unnumberedsubsec Q6.0.4: Procedural changes in XEmacs development. +@node Q7.0.4, , Q7.0.3, Current Events +@unnumberedsubsec Q7.0.4: Procedural changes in XEmacs development. @enumerate @item diff --git a/nt/ChangeLog b/nt/ChangeLog index cd415f7..5053ad5 100644 --- a/nt/ChangeLog +++ b/nt/ChangeLog @@ -1,3 +1,27 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-11-27 Adrian Aichner + + * xemacs.mak (SRCDIR): Make path to xemacs absolute to + facilitate building info in man subdirs. Echo all cd commands, + not just some of them. + + (makeinfo-test): Test for availability of `texinfo' package to + build info. Recommend use of external `makeinfo' program for + building info docs faster. + + (info): cd into man subdirs to support use of external `makeinfo' + program. + +1999-11-17 Martin Buchholz + + * xemacs.mak: Remove references to index.unperm, index.perm. + Fix dependencies. + Shouldn't .obj and .info be in SUFFIXES? + Remove extra `\'. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/nt/xemacs.mak b/nt/xemacs.mak index 7331255..8a8254b 100644 --- a/nt/xemacs.mak +++ b/nt/xemacs.mak @@ -417,17 +417,17 @@ CONFIG_VALUES = $(LIB_SRC)\config.values # Inferred rule {$(LIB_SRC)}.c{$(LIB_SRC)}.exe : - @cd $(LIB_SRC) + cd $(LIB_SRC) $(CCV) -I. -I$(XEMACS)/src -I$(XEMACS)/nt/inc $(LIB_SRC_DEFINES) $(CFLAGS) -Fe$@ $** -link -incremental:no - @cd $(NT) + cd $(NT) # Individual dependencies ETAGS_DEPS = $(LIB_SRC)/getopt.c $(LIB_SRC)/getopt1.c $(LIB_SRC)/../src/regex.c $(LIB_SRC)/etags.exe : $(LIB_SRC)/etags.c $(ETAGS_DEPS) $(LIB_SRC)/movemail.exe: $(LIB_SRC)/movemail.c $(LIB_SRC)/pop.c $(ETAGS_DEPS) - @cd $(LIB_SRC) + cd $(LIB_SRC) $(CCV) -I. -I$(XEMACS)/src -I$(XEMACS)/nt/inc $(LIB_SRC_DEFINES) $(CFLAGS) -Fe$@ $** wsock32.lib -link -incremental:no - @cd $(NT) + cd $(NT) LIB_SRC_TOOLS = \ $(LIB_SRC)/make-docfile.exe \ @@ -861,7 +861,7 @@ TEMACS_OBJS= \ # Rules .SUFFIXES: -.SUFFIXES: .c .texi +.SUFFIXES: .c .obj .texi .info # nmake rule !if $(DEBUG_XEMACS) @@ -901,7 +901,7 @@ $(OUTDIR)\xemacs.res: xemacs.rc # Section handling automated tests starts here -SRCDIR=..\src +SRCDIR=$(MAKEDIR)\..\src PROGNAME=$(SRCDIR)\xemacs.exe blddir=$(MAKEDIR:\=\\)\\.. temacs_loadup=$(TEMACS) -batch -l $(SRCDIR)/../lisp/loadup.el @@ -926,7 +926,10 @@ check-temacs: # Section handling automated tests ends here # Section handling info starts here -MAKEINFO=$(PROGNAME) -no-site-file -no-init-file -batch -l texinfmt -f batch-texinfo-format + +!if !defined(MAKEINFO) +MAKEINFO=$(PROGNAME) -vanilla -batch -l texinfmt -f batch-texinfo-format +!endif MANDIR = $(XEMACS)\man INFODIR = $(XEMACS)\info @@ -948,12 +951,10 @@ INFO_FILES= \ $(INFODIR)\internals.info {$(MANDIR)}.texi{$(INFODIR)}.info: + cd $(MANDIR) $(MAKEINFO) $** -$(INFODIR)\xemacs.info: $(MANDIR)\xemacs\xemacs.texi - $(MAKEINFO) $** - -$(MANDIR)\xemacs\xemacs.texi: \ +XEMACS_SRCS = \ $(MANDIR)\xemacs\abbrevs.texi \ $(MANDIR)\xemacs\basic.texi \ $(MANDIR)\xemacs\buffers.texi \ @@ -965,13 +966,13 @@ $(MANDIR)\xemacs\xemacs.texi: \ $(MANDIR)\xemacs\entering.texi \ $(MANDIR)\xemacs\files.texi \ $(MANDIR)\xemacs\fixit.texi \ + $(MANDIR)\xemacs\frame.texi \ $(MANDIR)\xemacs\glossary.texi \ $(MANDIR)\xemacs\gnu.texi \ $(MANDIR)\xemacs\help.texi \ $(MANDIR)\xemacs\indent.texi \ $(MANDIR)\xemacs\keystrokes.texi \ $(MANDIR)\xemacs\killing.texi \ - $(MANDIR)\xemacs\\xemacs.texi \ $(MANDIR)\xemacs\m-x.texi \ $(MANDIR)\xemacs\major.texi \ $(MANDIR)\xemacs\mark.texi \ @@ -979,25 +980,23 @@ $(MANDIR)\xemacs\xemacs.texi: \ $(MANDIR)\xemacs\mini.texi \ $(MANDIR)\xemacs\misc.texi \ $(MANDIR)\xemacs\mouse.texi \ + $(MANDIR)\xemacs\mule.texi \ $(MANDIR)\xemacs\new.texi \ + $(MANDIR)\xemacs\packages.texi \ $(MANDIR)\xemacs\picture.texi \ $(MANDIR)\xemacs\programs.texi \ $(MANDIR)\xemacs\reading.texi \ $(MANDIR)\xemacs\regs.texi \ - $(MANDIR)\xemacs\frame.texi \ $(MANDIR)\xemacs\search.texi \ $(MANDIR)\xemacs\sending.texi \ + $(MANDIR)\xemacs\startup.texi \ $(MANDIR)\xemacs\text.texi \ $(MANDIR)\xemacs\trouble.texi \ $(MANDIR)\xemacs\undo.texi \ - $(MANDIR)\xemacs\windows.texi - - -$(INFODIR)\lispref.info: $(MANDIR)\lispref\lispref.texi - copy $(MANDIR)\lispref\index.perm $(MANDIR)\lispref\index.texi - $(MAKEINFO) $** + $(MANDIR)\xemacs\windows.texi \ + $(MANDIR)\xemacs\xemacs.texi -$(MANDIR)\lispref\lispref.texi: \ +LISPREF_SRCS = \ $(MANDIR)\lispref\abbrevs.texi \ $(MANDIR)\lispref\annotations.texi \ $(MANDIR)\lispref\back.texi \ @@ -1008,10 +1007,12 @@ $(MANDIR)\lispref\lispref.texi: \ $(MANDIR)\lispref\compile.texi \ $(MANDIR)\lispref\consoles-devices.texi \ $(MANDIR)\lispref\control.texi \ + $(MANDIR)\lispref\customize.texi \ $(MANDIR)\lispref\databases.texi \ $(MANDIR)\lispref\debugging.texi \ $(MANDIR)\lispref\dialog.texi \ $(MANDIR)\lispref\display.texi \ + $(MANDIR)\lispref\dragndrop.texi \ $(MANDIR)\lispref\edebug-inc.texi \ $(MANDIR)\lispref\edebug.texi \ $(MANDIR)\lispref\errors.texi \ @@ -1025,12 +1026,12 @@ $(MANDIR)\lispref\lispref.texi: \ $(MANDIR)\lispref\hash-tables.texi \ $(MANDIR)\lispref\help.texi \ $(MANDIR)\lispref\hooks.texi \ - $(MANDIR)\lispref\index.perm \ - $(MANDIR)\lispref\index.unperm \ + $(MANDIR)\lispref\index.texi \ $(MANDIR)\lispref\internationalization.texi \ $(MANDIR)\lispref\intro.texi \ $(MANDIR)\lispref\keymaps.texi \ $(MANDIR)\lispref\ldap.texi \ + $(MANDIR)\lispref\lispref.texi \ $(MANDIR)\lispref\lists.texi \ $(MANDIR)\lispref\loading.texi \ $(MANDIR)\lispref\locals.texi \ @@ -1062,37 +1063,62 @@ $(MANDIR)\lispref\lispref.texi: \ $(MANDIR)\lispref\tooltalk.texi \ $(MANDIR)\lispref\variables.texi \ $(MANDIR)\lispref\windows.texi \ - $(MANDIR)\lispref\x-windows.texi \ - $(MANDIR)\lispref\index.unperm \ - $(MANDIR)\lispref\index.perm + $(MANDIR)\lispref\x-windows.texi +INTERNALS_SRCS = \ + $(MANDIR)\internals\internals.texi \ + $(MANDIR)\internals\index.texi -$(INFODIR)\new-users-guide.info: $(MANDIR)\new-users-guide\new-users-guide.texi - $(MAKEINFO) $** - -$(MANDIR)\new-users-guide\new-users-guide.texi: \ +NEW_USERS_GUIDE_SRCS = \ $(MANDIR)\new-users-guide\custom1.texi \ - $(MANDIR)\new-users-guide\files.texi \ - $(MANDIR)\new-users-guide\region.texi \ $(MANDIR)\new-users-guide\custom2.texi \ - $(MANDIR)\new-users-guide\help.texi \ - $(MANDIR)\new-users-guide\search.texi \ $(MANDIR)\new-users-guide\edit.texi \ + $(MANDIR)\new-users-guide\enter.texi \ + $(MANDIR)\new-users-guide\files.texi \ + $(MANDIR)\new-users-guide\help.texi \ $(MANDIR)\new-users-guide\modes.texi \ - $(MANDIR)\new-users-guide\xmenu.texi \ - $(MANDIR)\new-users-guide\enter.texi - - -$(INFODIR)\internals.info: $(MANDIR)\internals\internals.texi - copy $(MANDIR)\internals\index.perm $(MANDIR)\internals\index.texi - $(MAKEINFO) $** - -$(MANDIR)\internals\internals.texi: \ - $(MANDIR)\internals\index.unperm \ - $(MANDIR)\internals\index.perm - - -info: $(INFO_FILES) + $(MANDIR)\new-users-guide\new-users-guide.texi \ + $(MANDIR)\new-users-guide\region.texi \ + $(MANDIR)\new-users-guide\search.texi \ + $(MANDIR)\new-users-guide\xmenu.texi + +$(INFODIR)\xemacs.info: $(XEMACS_SRCS) + cd $(MANDIR)\xemacs + $(MAKEINFO) xemacs.texi + cd .. + + +$(INFODIR)\lispref.info: $(LISPREF_SRCS) + cd $(MANDIR)\lispref + $(MAKEINFO) lispref.texi + cd .. + +$(INFODIR)\internals.info: $(INTERNALS_SRCS) + cd $(MANDIR)\internals + $(MAKEINFO) internals.texi + cd .. + +$(INFODIR)\new-users-guide.info: $(NEW_USERS_GUIDE_SRCS) + cd $(MANDIR)\new-users-guide + $(MAKEINFO) new-users-guide.texi + cd .. + +info: makeinfo-test $(INFO_FILES) + +makeinfo-test: + @< PlaceHolder @xcopy /q PROBLEMS "$(INSTALL_DIR)\" @@ -1199,7 +1226,7 @@ distclean: cd $(LISP) $(DEL) /s /q *.bak *.elc *.orig *.rej cd $(INFODIR) - $(DEL) *.info* $(MANDIR)\internals\index.texi $(MANDIR)\lispref\index.texi + $(DEL) *.info* depend: mkdepend -f xemacs.mak -p$(OUTDIR)\ -o.obj -w9999 -- $(TEMACS_CPP_FLAGS) -- $(DOC_SRC1) $(DOC_SRC2) $(DOC_SRC3) $(DOC_SRC4) $(DOC_SRC5) $(DOC_SRC6) $(DOC_SRC7) $(DOC_SRC8) $(DOC_SRC9) $(LASTFILE_SRC)\lastfile.c $(LIB_SRC)\make-docfile.c $(LIB_SRC)\run.c @@ -1305,6 +1332,7 @@ XEmacs $(XEMACS_VERSION_STRING) $(xemacs_codename:"=\") configured for `$(EMACS_ VANILLA=-vanilla FORCE: $(LISP)\auto-autoloads.el: FORCE + @$(DEL) $(LISP)\auto-autoloads.el $(PROGNAME) $(VANILLA) -batch \ -l autoload -f batch-update-directory $(LISP) $(PROGNAME) $(VANILLA) -batch \ diff --git a/src/ChangeLog b/src/ChangeLog index 9478322..c5a0fe9 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,142 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + +1999-12-06 Martin Buchholz + + * events.c (Fcopy_event): Don't copy the lrecord_header. + + * lisp.h (DO_REALLOC): + Optimize. + Remove redundant parens. + Remove generic hygienic macro comment. + + * lrecord.h (set_lheader_implementation): Remove redundant parens. + +1999-12-05 Martin Buchholz + + * lstream.c (Lstream_adding): + - Never compare a size_t and a possibly negative number. + - Optimize. + +1999-12-05 Kyle Jones + + * lisp/itimer.el: (require 'lisp-float-type). Use + floats directly in itimer-time-difference. + +1999-12-05 Andy Piper + + * redisplay-output.c (redisplay_output_layout): avoid name hiding. + + * gui.h: declare gui_add_item_keywords_to_plist. + + * window.c (Fdelete_window): mark subwindows as changed so that + they can be GC'd if necessary. + +1999-12-02 Jan Vroonhof + + * src/callproc.c (Fcall_process_internal): Be careful in writing + terminating null when copying args. nargs can be < 4. + Idea from Klaus Frank + +1999-11-29 Kyle Jones + + * src/sound.c (Fding): Remove zero initialization of + static variables to avoid crashes on systems that dump + the initialized data segment read-only. + +1999-12-05 Jan Vroonhof + + * glyphs-x.c (convert_EImage_to_XImage): Guard against other + visual classes. From Rasmus Borup Hansen + +1999-12-04 Martin Buchholz + + * lstream.c: (filedesc_reader): + (filedesc_writer): Try number 2: Support broken systems where + return type of read() and write() is different from ssize_t. + + * systty.h: + * sysdep.h: + * sysdep.c: + - Replace macro calls to EMACS_GET_TTY and EMACS_SET_TTY with + function equivalents emacs_get_tty() and emacs_set_tty(). + - Moved prototypes to systty.h, where struct event_tty is defined. + - Renamed bogus `waitp' parameter to `flushp'. + + * lstream.c (filedesc_reader): Support broken systems where return + type of read() is different from ssize_t. + + * events.c (Fcopy_event): Avoid redundant EQ test if event2 is nil. + + * event-stream.c (menu_move_up): Remove redundant if block. + (menu_move_down): Gratuitous rewriting. + (menu_move_left): Work around Cygnus codefusion-990706 compiler bug. + (menu_move_right): Ditto. + + * lrecord.h (copy_lcrecord): + (zero_lcrecord): + Always add parentheses around uses of macro arguments. + + * sysdll.c: #include for exit(). + * unexhp9k800.x: #include for malloc(). + Use proper prototype for Save_Shared_Data(void). + +1999-12-04 Jan Vroonhof + + * src/redisplay.c (point_would_be_visible): Correct for topclip. + +1999-12-02 Hrvoje Niksic + + * lisp.h: Declare Qself_insert_defer_undo. + + * event-stream.c (Fdispatch_event): Get the magic undo thing from + a symbol property, so commands other than self-insert-command can + install it. + (syms_of_event_stream): Define Qself_insert_defer_undo. + +1999-11-30 Martin Buchholz + + * floatfns.c (emacs_rint): Rename rint to emacs_rint, so that + `#undef HAVE_RINT' works. + + * sysdep.h: Fix up prototypes for sys_read_1(), sys_write_1() + +1999-11-25 Andy Piper + + * select-msw.c (Fmswindows_set_clipboard): selection fixes from + Mike Alexander. + (Fmswindows_delete_selection): ditto. + + * redisplay.h (CLASS_REDISPLAY_FLAGS_CHANGEDP): add size_changed. + (GLOBAL_REDISPLAY_FLAGS_CHANGEDP): ditto. + + * redisplay.c (redisplay_device): move size changed to macros in + redisplay.h + (redisplay_without_hooks): ditto. + + * redisplay-output.c (redisplay_output_layout): rename to avoid + name hiding. + + * process-nt.c (struct nt_process_data): mks toolkit fixes from + Mike Alexander. + (nt_create_process): ditto. + (nt_send_process): ditto. + + * nt.c (init_environment): make sure mingw32 gets the cached + system info. + + * gui.h: declare gui_add_item_keywords_to_plist. + + * event-msw.c (mswindows_wnd_proc): Clipboard fixes from Mike + Alexander. + + * console-msw.h: fix cygwin define/header 1.0 problems. + * glyphs-msw.c: ditto. + * ntplay.c: ditto. + * unexcw.c: ditto. + * s/cygwin32/h: ditto. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/src/callproc.c b/src/callproc.c index 080a1d7..2b45793 100644 --- a/src/callproc.c +++ b/src/callproc.c @@ -287,8 +287,8 @@ If you quit, the process is killed with SIGINT, or SIGKILL if you CHECK_STRING (args[i]); new_argv[i - 3] = (char *) XSTRING_DATA (args[i]); } - new_argv[nargs - 3] = 0; } + new_argv[max(nargs - 3,1)] = 0; if (NILP (path)) report_file_error ("Searching for program", Fcons (args[0], Qnil)); diff --git a/src/console-msw.h b/src/console-msw.h index 19d01d0..f3a6c3b 100644 --- a/src/console-msw.h +++ b/src/console-msw.h @@ -38,7 +38,8 @@ Boston, MA 02111-1307, USA. */ #endif #include #include /* DDE management library */ -#if !defined(__CYGWIN32__) && !defined(__MINGW32__) +#if !defined(__CYGWIN32__) && !defined(__MINGW32__) \ + || CYGWIN_VERSION_DLL_MAJOR > 20 #include /* FileManager/Explorer drag and drop */ #include #endif diff --git a/src/device-x.c b/src/device-x.c index 0c1a3e5..a1a8196 100644 --- a/src/device-x.c +++ b/src/device-x.c @@ -1337,7 +1337,7 @@ The returned value of this function is nil if the queried resource is not found. If the third arg is `string', a string is returned, and if it is `integer', an integer is returned. If the third arg is `boolean', then the returned value is the list (t) for true, (nil) for false, and is nil to -mean ``unspecified.'' +mean ``unspecified''. */ (name, class, type, locale, device, no_error)) { diff --git a/src/elhash.c b/src/elhash.c index f3b79f5..e44ca97 100644 --- a/src/elhash.c +++ b/src/elhash.c @@ -270,8 +270,7 @@ hash_table_equal (Lisp_Object hash_table1, Lisp_Object hash_table2, int depth) `weakness' (nil, t, key or value) `data' (a list) - If `print-readably' is non-nil, then a simpler syntax is used; for - instance: + If `print-readably' is nil, then a simpler syntax is used, for example # diff --git a/src/event-msw.c b/src/event-msw.c index f3e7727..6a0c91c 100644 --- a/src/event-msw.c +++ b/src/event-msw.c @@ -56,6 +56,7 @@ Boston, MA 02111-1307, USA. */ #include "lstream.h" #include "process.h" #include "redisplay.h" +#include "select.h" #include "sysproc.h" #include "syswait.h" #include "systime.h" @@ -1614,6 +1615,13 @@ mswindows_wnd_proc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam) switch (message) { + case WM_DESTROYCLIPBOARD: + /* We own the clipboard and someone else wants it. Delete our + cached copy of the clipboard contents so we'll ask for it from + Windows again when someone does a paste. */ + handle_selection_clear(QCLIPBOARD); + break; + case WM_ERASEBKGND: /* Erase background only during non-dynamic sizing */ msframe = FRAME_MSWINDOWS_DATA (XFRAME (mswindows_find_frame (hwnd))); diff --git a/src/event-stream.c b/src/event-stream.c index 81f5f02..48bd9fc 100644 --- a/src/event-stream.c +++ b/src/event-stream.c @@ -259,6 +259,8 @@ Lisp_Object Qmenu_right; Lisp_Object Qmenu_select; Lisp_Object Qmenu_escape; +Lisp_Object Qself_insert_defer_undo; + /* this is in keymap.c */ extern Lisp_Object Fmake_keymap (Lisp_Object name); @@ -3098,20 +3100,15 @@ command_builder_find_leaf_1 (struct command_builder *builder) static void menu_move_up (void) { - widget_value *current, *prev; - widget_value *entries; + widget_value *current = lw_get_entries (False); + widget_value *entries = lw_get_entries (True); + widget_value *prev = NULL; - current = lw_get_entries (False); - entries = lw_get_entries (True); - prev = NULL; - if (current != entries) + while (entries != current) { - while (entries != current) - { - if (entries->name /*&& entries->enabled*/) prev = entries; - entries = entries->next; - assert (entries); - } + if (entries->name /*&& entries->enabled*/) prev = entries; + entries = entries->next; + assert (entries); } if (!prev) @@ -3140,11 +3137,8 @@ menu_move_up (void) static void menu_move_down (void) { - widget_value *current; - widget_value *new; - - current = lw_get_entries (False); - new = current; + widget_value *current = lw_get_entries (False); + widget_value *new = current; while (new->next) { @@ -3177,11 +3171,9 @@ menu_move_left (void) int l = level; widget_value *current; - while (level >= 3) - { - --level; - lw_pop_menu (); - } + while (level-- >= 3) + lw_pop_menu (); + menu_move_up (); current = lw_get_entries (False); if (l > 2 && current->contents) @@ -3195,11 +3187,9 @@ menu_move_right (void) int l = level; widget_value *current; - while (level >= 3) - { - --level; - lw_pop_menu (); - } + while (level-- >= 3) + lw_pop_menu (); + menu_move_down (); current = lw_get_entries (False); if (l > 2 && current->contents) @@ -4604,15 +4594,35 @@ Magic events are handled as necessary. } else /* key sequence is bound to a command */ { + int magic_undo = 0; + int magic_undo_count = 20; + Vthis_command = leaf; + /* Don't push an undo boundary if the command set the prefix arg, or if we are executing a keyboard macro, or if in the minibuffer. If the command we are about to execute is self-insert, it's tricky: up to 20 consecutive self-inserts may be done without an undo boundary. This counter is reset as soon as a command other than self-insert-command is executed. - */ - if (! EQ (leaf, Qself_insert_command)) + + Programmers can also use the `self-insert-undo-magic' + property to install that behaviour on functions other + than `self-insert-command', or to change the magic + number 20 to something else. */ + + if (SYMBOLP (leaf)) + { + Lisp_Object prop = Fget (leaf, Qself_insert_defer_undo, Qnil); + if (NATNUMP (prop)) + magic_undo = 1, magic_undo_count = XINT (prop); + else if (!NILP (prop)) + magic_undo = 1; + else if (EQ (leaf, Qself_insert_command)) + magic_undo = 1; + } + + if (!magic_undo) command_builder->self_insert_countdown = 0; if (NILP (XCONSOLE (console)->prefix_arg) && NILP (Vexecuting_macro) @@ -4626,10 +4636,10 @@ Magic events are handled as necessary. && command_builder->self_insert_countdown == 0) Fundo_boundary (); - if (EQ (leaf, Qself_insert_command)) + if (magic_undo) { if (--command_builder->self_insert_countdown < 0) - command_builder->self_insert_countdown = 20; + command_builder->self_insert_countdown = magic_undo_count; } execute_command_event (command_builder, @@ -4815,7 +4825,7 @@ That is not right. Calling this function directs the translated event to replace the original event, so that only one version of the event actually -appears in the echo area and in the value of `this-command-keys.'. +appears in the echo area and in the value of `this-command-keys'. */ ()) { @@ -4957,6 +4967,7 @@ syms_of_event_stream (void) defsymbol (&Qmenu_select, "menu-select"); defsymbol (&Qmenu_escape, "menu-escape"); + defsymbol (&Qself_insert_defer_undo, "self-insert-defer-undo"); defsymbol (&Qcancel_mode_internal, "cancel-mode-internal"); } diff --git a/src/events.c b/src/events.c index 8f465d3..7bb19c4 100644 --- a/src/events.c +++ b/src/events.c @@ -763,7 +763,7 @@ DEFUN ("copy-event", Fcopy_event, 1, 2, 0, /* Make a copy of the given event object. If a second argument is given, the first event is copied into the second and the second is returned. If the second argument is not supplied (or -is nil) then a new event will be made as with `allocate-event.' See also +is nil) then a new event will be made as with `make-event'. See also the function `deallocate-event'. */ (event1, event2)) @@ -771,19 +771,26 @@ the function `deallocate-event'. CHECK_LIVE_EVENT (event1); if (NILP (event2)) event2 = Fmake_event (Qnil, Qnil); - else CHECK_LIVE_EVENT (event2); - if (EQ (event1, event2)) - return signal_simple_continuable_error_2 - ("copy-event called with `eq' events", event1, event2); + else + { + CHECK_LIVE_EVENT (event2); + if (EQ (event1, event2)) + return signal_simple_continuable_error_2 + ("copy-event called with `eq' events", event1, event2); + } assert (XEVENT_TYPE (event1) <= last_event_type); assert (XEVENT_TYPE (event2) <= last_event_type); { - Lisp_Object save_next = XEVENT_NEXT (event2); + Lisp_Event *ev2 = XEVENT (event2); + Lisp_Event *ev1 = XEVENT (event1); + + ev2->event_type = ev1->event_type; + ev2->channel = ev1->channel; + ev2->timestamp = ev1->timestamp; + ev2->event = ev1->event; - *XEVENT (event2) = *XEVENT (event1); - XSET_EVENT_NEXT (event2, save_next); return event2; } } diff --git a/src/floatfns.c b/src/floatfns.c index 5e86a98..5dd8496 100644 --- a/src/floatfns.c +++ b/src/floatfns.c @@ -55,9 +55,13 @@ Boston, MA 02111-1307, USA. */ #define THIS_FILENAME floatfns #include "sysfloat.h" -#ifndef HAVE_RINT +/* The code uses emacs_rint, so that it works to undefine HAVE_RINT + if `rint' exists but does not work right. */ +#ifdef HAVE_RINT +#define emacs_rint rint +#else static double -rint (double x) +emacs_rint (double x) { double r = floor (x + 0.5); double diff = fabs (r - x); @@ -831,7 +835,7 @@ Return the nearest integer to ARG. { double d; /* Screw the prevailing rounding mode. */ - IN_FLOAT ((d = rint (XFLOAT_DATA (arg))), "round", arg); + IN_FLOAT ((d = emacs_rint (XFLOAT_DATA (arg))), "round", arg); return (float_to_int (d, "round", arg, Qunbound)); } #endif /* LISP_FLOAT_TYPE */ @@ -891,7 +895,7 @@ Return the nearest integer to ARG, as a float. (arg)) { double d = extract_float (arg); - IN_FLOAT (d = rint (d), "fround", arg); + IN_FLOAT (d = emacs_rint (d), "fround", arg); return make_float (d); } diff --git a/src/glyphs-msw.c b/src/glyphs-msw.c index d3c11b6..fd318b3 100644 --- a/src/glyphs-msw.c +++ b/src/glyphs-msw.c @@ -1100,8 +1100,10 @@ typedef struct #define OIC_BANG 32515 #define OIC_NOTE 32516 #define OIC_WINLOGO 32517 +#if defined (__CYGWIN32__) && CYGWIN_VERSION_DLL_MAJOR < 21 #define LR_SHARED 0x8000 #endif +#endif static CONST resource_t bitmap_table[] = { diff --git a/src/glyphs-x.c b/src/glyphs-x.c index 301da9b..d229d67 100644 --- a/src/glyphs-x.c +++ b/src/glyphs-x.c @@ -44,6 +44,7 @@ Boston, MA 02111-1307, USA. */ Subwindow and Widget support by Andy Piper for 21.2 TODO: + Support the GrayScale, StaticColor and StaticGray visual classes. Convert images.el to C and stick it in here? */ @@ -184,6 +185,13 @@ convert_EImage_to_XImage (Lisp_Object device, int width, int height, vis = DEVICE_X_VISUAL (XDEVICE(device)); depth = DEVICE_X_DEPTH(XDEVICE(device)); + if (vis->class == GrayScale || vis->class == StaticColor || + vis->class == StaticGray) + { + /* #### Implement me!!! */ + return NULL; + } + if (vis->class == PseudoColor) { /* Quantize the image and get a histogram while we're at it. diff --git a/src/glyphs.c b/src/glyphs.c index 7deab6c..0e327f4 100644 --- a/src/glyphs.c +++ b/src/glyphs.c @@ -1609,6 +1609,8 @@ instance is a mono pixmap; otherwise, the same image instance is returned. if (!HAS_DEVMETH_P (XDEVICE (device), colorize_image_instance)) return image_instance; + /* #### There should be a copy_image_instance(), which calls a + device-specific method to copy the window-system subobject. */ new = allocate_image_instance (device); copy_lcrecord (XIMAGE_INSTANCE (new), XIMAGE_INSTANCE (image_instance)); /* note that if this method returns non-zero, this method MUST diff --git a/src/gui.h b/src/gui.h index 169abd5..4723252 100644 --- a/src/gui.h +++ b/src/gui.h @@ -71,6 +71,7 @@ void gui_item_add_keyval_pair (Lisp_Object, Error_behavior errb); Lisp_Object gui_parse_item_keywords (Lisp_Object item); Lisp_Object gui_parse_item_keywords_no_errors (Lisp_Object item); +void gui_add_item_keywords_to_plist (Lisp_Object plist, Lisp_Object gui_item); int gui_item_active_p (Lisp_Object); int gui_item_selected_p (Lisp_Object); int gui_item_included_p (Lisp_Object, Lisp_Object into); diff --git a/src/lisp.h b/src/lisp.h index c827371..883070a 100644 --- a/src/lisp.h +++ b/src/lisp.h @@ -134,21 +134,16 @@ char *xstrdup (CONST char *); macro will realloc BASEVAR as necessary so that it can hold at least NEEDED_SIZE objects. The reallocing is done by doubling, which ensures constant amortized time per element. */ -#define DO_REALLOC(basevar, sizevar, needed_size, type) do \ -{ \ - /* Avoid side-effectualness. */ \ - /* Dammit! Macros suffer from dynamic scope! */ \ - /* We demand inline functions! */ \ +#define DO_REALLOC(basevar, sizevar, needed_size, type) do { \ size_t do_realloc_needed_size = (needed_size); \ - size_t do_realloc_newsize = 0; \ - while ((sizevar) < (do_realloc_needed_size)) { \ - do_realloc_newsize = 2*(sizevar); \ - if (do_realloc_newsize < 32) \ - do_realloc_newsize = 32; \ - (sizevar) = do_realloc_newsize; \ - } \ - if (do_realloc_newsize) \ - XREALLOC_ARRAY (basevar, type, do_realloc_newsize); \ + if ((sizevar) < do_realloc_needed_size) \ + { \ + if ((sizevar) < 32) \ + (sizevar) = 32; \ + while ((sizevar) < do_realloc_needed_size) \ + (sizevar) *= 2; \ + XREALLOC_ARRAY (basevar, type, (sizevar)); \ + } \ } while (0) #ifdef ERROR_CHECK_MALLOC @@ -2864,7 +2859,8 @@ extern Lisp_Object Qquote, Qrange_error, Qrassoc, Qrassq, Qread_char; extern Lisp_Object Qread_from_minibuffer, Qreally_early_error_handler; extern Lisp_Object Qregion_beginning, Qregion_end, Qrequire, Qresource; extern Lisp_Object Qreturn, Qreverse, Qright, Qrun_hooks, Qsans_modifiers; -extern Lisp_Object Qsave_buffers_kill_emacs, Qsearch, Qselected, Qself_insert_command; +extern Lisp_Object Qsave_buffers_kill_emacs, Qsearch, Qselected; +extern Lisp_Object Qself_insert_command, Qself_insert_defer_undo; extern Lisp_Object Qsequencep, Qsetting_constant, Qseven, Qshift_jis, Qshort; extern Lisp_Object Qsignal, Qsimple, Qsingularity_error, Qsize, Qspace; extern Lisp_Object Qspecifier, Qstandard_input, Qstandard_output, Qstart_open; diff --git a/src/lrecord.h b/src/lrecord.h index 968ccc4..35a4b89 100644 --- a/src/lrecord.h +++ b/src/lrecord.h @@ -72,12 +72,12 @@ struct lrecord_header struct lrecord_implementation; int lrecord_type_index (CONST struct lrecord_implementation *implementation); -# define set_lheader_implementation(header,imp) do { \ +#define set_lheader_implementation(header,imp) do { \ struct lrecord_header* SLI_header = (header); \ - (SLI_header)->type = lrecord_type_index (imp); \ - (SLI_header)->mark = 0; \ - (SLI_header)->c_readonly = 0; \ - (SLI_header)->lisp_readonly = 0; \ + SLI_header->type = lrecord_type_index (imp); \ + SLI_header->mark = 0; \ + SLI_header->c_readonly = 0; \ + SLI_header->lisp_readonly = 0; \ } while (0) struct lcrecord_header @@ -489,12 +489,12 @@ void *alloc_lcrecord (size_t size, CONST struct lrecord_implementation *); overwrite the header information. */ #define copy_lcrecord(dst, src) \ - memcpy ((char *) dst + sizeof (struct lcrecord_header), \ - (char *) src + sizeof (struct lcrecord_header), \ - sizeof (*dst) - sizeof (struct lcrecord_header)) + memcpy ((char *) (dst) + sizeof (struct lcrecord_header), \ + (char *) (src) + sizeof (struct lcrecord_header), \ + sizeof (*(dst)) - sizeof (struct lcrecord_header)) #define zero_lcrecord(lcr) \ - memset ((char *) lcr + sizeof (struct lcrecord_header), 0, \ - sizeof (*lcr) - sizeof (struct lcrecord_header)) + memset ((char *) (lcr) + sizeof (struct lcrecord_header), 0, \ + sizeof (*(lcr)) - sizeof (struct lcrecord_header)) #endif /* _XEMACS_LRECORD_H_ */ diff --git a/src/lstream.c b/src/lstream.c index 9ecce37..3e6d1ac 100644 --- a/src/lstream.c +++ b/src/lstream.c @@ -392,19 +392,24 @@ Lstream_flush (Lstream *lstr) static size_t Lstream_adding (Lstream *lstr, size_t num, int force) { - /* Compute the size that the outbuffer needs to be after the - chars are added. */ - size_t size_needed = max (lstr->out_buffer_size, - num + lstr->out_buffer_ind); + size_t size = num + lstr->out_buffer_ind; + + if (size <= lstr->out_buffer_size) + return num; + /* Maybe chop it down so that we don't buffer more characters than our advertised buffering size. */ - if (!force) - size_needed = min (lstr->buffering_size, size_needed); - DO_REALLOC (lstr->out_buffer, lstr->out_buffer_size, - size_needed, unsigned char); - /* There might be more data buffered than the buffering size, - so make sure we don't return a negative number here. */ - return max (0, min (num, size_needed - lstr->out_buffer_ind)); + if ((size > lstr->buffering_size) && !force) + { + size = lstr->buffering_size; + /* There might be more data buffered than the buffering size. */ + if (size <= lstr->out_buffer_ind) + return 0; + } + + DO_REALLOC (lstr->out_buffer, lstr->out_buffer_size, size, unsigned char); + + return size - lstr->out_buffer_ind; } /* Like Lstream_write(), but does not handle line-buffering correctly. */ @@ -934,7 +939,9 @@ filedesc_reader (Lstream *stream, unsigned char *data, size_t size) struct filedesc_stream *str = FILEDESC_STREAM_DATA (stream); if (str->end_pos >= 0) size = min (size, (size_t) (str->end_pos - str->current_pos)); - nread = (str->allow_quit ? read_allowing_quit : read) (str->fd, data, size); + nread = str->allow_quit ? + read_allowing_quit (str->fd, data, size) : + read (str->fd, data, size); if (nread > 0) str->current_pos += nread; return nread; @@ -987,8 +994,9 @@ filedesc_writer (Lstream *stream, CONST unsigned char *data, size_t size) /**** start of non-PTY-crap ****/ if (size > 0) - retval = ((str->allow_quit ? write_allowing_quit : write) - (str->fd, data, size)); + retval = str->allow_quit ? + write_allowing_quit (str->fd, data, size) : + write (str->fd, data, size); else retval = 0; if (retval < 0 && errno_would_block_p (errno) && str->blocked_ok) @@ -1011,8 +1019,10 @@ filedesc_writer (Lstream *stream, CONST unsigned char *data, size_t size) out for EWOULDBLOCK. */ if (str->chars_sans_newline >= str->pty_max_bytes) { - ssize_t retval2 = ((str->allow_quit ? write_allowing_quit : write) - (str->fd, &str->eof_char, 1)); + ssize_t retval2 = str->allow_quit ? + write_allowing_quit (str->fd, &str->eof_char, 1) : + write (str->fd, &str->eof_char, 1); + if (retval2 > 0) str->chars_sans_newline = 0; else if (retval2 < 0) @@ -1042,8 +1052,10 @@ filedesc_writer (Lstream *stream, CONST unsigned char *data, size_t size) if (need_newline) { Bufbyte nl = '\n'; - ssize_t retval2 = ((str->allow_quit ? write_allowing_quit : write) - (str->fd, &nl, 1)); + ssize_t retval2 = str->allow_quit ? + write_allowing_quit (str->fd, &nl, 1) : + write (str->fd, &nl, 1); + if (retval2 > 0) { str->chars_sans_newline = 0; diff --git a/src/miscplay.c b/src/miscplay.c index 37eeb17..3acfca5 100644 --- a/src/miscplay.c +++ b/src/miscplay.c @@ -562,7 +562,6 @@ size_t sndcnvULaw_2mono(void **data,size_t *sz,void **outbuf) size_t sndcnv16swap(void **data,size_t *sz,void **outbuf) { - /* #### Not aliasing-safe!! Must convert to use unions instead! */ size_t cnt = *sz / 2; unsigned short *p; diff --git a/src/nt.c b/src/nt.c index ce16938..2fa0319 100644 --- a/src/nt.c +++ b/src/nt.c @@ -608,7 +608,9 @@ init_environment () "EMACSLOCKDIR", "INFOPATH" }; - +#ifdef HEAP_IN_DATA + cache_system_info (); +#endif for (i = 0; i < countof (env_vars); i++) { if (!getenv (env_vars[i]) && diff --git a/src/ntplay.c b/src/ntplay.c index 2b85ab8..398e27a 100644 --- a/src/ntplay.c +++ b/src/ntplay.c @@ -25,7 +25,8 @@ Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA #include "sysfile.h" #include "lisp.h" -#if defined (__CYGWIN32__) || defined(__MINGW32__) +#if (defined (__CYGWIN32__) || defined(__MINGW32__)) && \ + CYGWIN_VERSION_DLL_MAJOR < 21 extern BOOL WINAPI PlaySound(LPCSTR,HMODULE,DWORD); #else #include diff --git a/src/objects-msw.c b/src/objects-msw.c index 1b90aca..9190490 100644 --- a/src/objects-msw.c +++ b/src/objects-msw.c @@ -49,7 +49,8 @@ Boston, MA 02111-1307, USA. */ #include "device.h" #include "insdel.h" -#if defined(__CYGWIN32__) || defined(__MINGW32__) +#if (defined(__CYGWIN32__) || defined(__MINGW32__)) && \ + CYGWIN_VERSION_DLL_MAJOR < 21 #define stricmp strcasecmp #define FONTENUMPROC FONTENUMEXPROC #define ntmTm ntmentm diff --git a/src/process-nt.c b/src/process-nt.c index 2a61346..0e3eb7d 100644 --- a/src/process-nt.c +++ b/src/process-nt.c @@ -53,6 +53,7 @@ Lisp_Object Qnt_quote_process_args; struct nt_process_data { HANDLE h_process; + int need_enable_child_signals; }; #define NT_DATA(p) ((struct nt_process_data*)((p)->process_data)) @@ -421,7 +422,7 @@ nt_create_process (struct Lisp_Process *p, Lisp_Object *argv, int nargv, Lisp_Object program, Lisp_Object cur_dir) { - HANDLE hmyshove, hmyslurp, hprocin, hprocout; + HANDLE hmyshove, hmyslurp, hprocin, hprocout, hprocerr; LPTSTR command_line; BOOL do_io, windowed; char *proc_env; @@ -472,6 +473,10 @@ nt_create_process (struct Lisp_Process *p, CreatePipe (&hprocin, &hmyshove, &sa, 0); CreatePipe (&hmyslurp, &hprocout, &sa, 0); + /* Duplicate the stdout handle for use as stderr */ + DuplicateHandle(GetCurrentProcess(), hprocout, GetCurrentProcess(), &hprocerr, + 0, TRUE, DUPLICATE_SAME_ACCESS); + /* Stupid Win32 allows to create a pipe with *both* ends either inheritable or not. We need process ends inheritable, and local ends not inheritable. */ @@ -599,7 +604,7 @@ nt_create_process (struct Lisp_Process *p, { si.hStdInput = hprocin; si.hStdOutput = hprocout; - si.hStdError = hprocout; + si.hStdError = hprocerr; si.dwFlags |= STARTF_USESTDHANDLES; } @@ -614,6 +619,7 @@ nt_create_process (struct Lisp_Process *p, /* These just have been inherited; we do not need a copy */ CloseHandle (hprocin); CloseHandle (hprocout); + CloseHandle (hprocerr); } /* Handle process creation failure */ @@ -640,12 +646,18 @@ nt_create_process (struct Lisp_Process *p, CloseHandle (pi.hProcess); } - if (!windowed) - enable_child_signals (pi.hProcess); - ResumeThread (pi.hThread); CloseHandle (pi.hThread); + /* Remember to enable child signals later if this is not a windowed + app. Can't do it right now because that screws up the MKS Toolkit + shell. */ + if (!windowed) + { + NT_DATA(p)->need_enable_child_signals = 10; + kick_status_notify (); + } + /* Hack to support Windows 95 negative pids */ return ((int)pi.dwProcessId < 0 ? -(int)pi.dwProcessId : (int)pi.dwProcessId); @@ -664,6 +676,18 @@ static void nt_update_status_if_terminated (struct Lisp_Process* p) { DWORD exit_code; + + if (NT_DATA(p)->need_enable_child_signals > 1) + { + NT_DATA(p)->need_enable_child_signals -= 1; + kick_status_notify (); + } + else if (NT_DATA(p)->need_enable_child_signals == 1) + { + enable_child_signals(NT_DATA(p)->h_process); + NT_DATA(p)->need_enable_child_signals = 0; + } + if (GetExitCodeProcess (NT_DATA(p)->h_process, &exit_code) && exit_code != STILL_ACTIVE) { @@ -765,6 +789,14 @@ nt_kill_child_process (Lisp_Object proc, int signo, { struct Lisp_Process *p = XPROCESS (proc); + /* Enable child signals if necessary. This may lose the first + but it's better than nothing. */ + if (NT_DATA(p)->need_enable_child_signals > 0) + { + enable_child_signals(NT_DATA(p)->h_process); + NT_DATA(p)->need_enable_child_signals = 0; + } + /* Signal error if SIGNO cannot be sent */ validate_signal_number (signo); diff --git a/src/redisplay-output.c b/src/redisplay-output.c index 5b8228c..f767790 100644 --- a/src/redisplay-output.c +++ b/src/redisplay-output.c @@ -1223,14 +1223,14 @@ redisplay_output_layout (struct window *w, /* We bogusly don't take f->extents_changed and f->glyphs_changed into account. This is because if we do we always redisplay the entire layout. So far I have seen no ill effects to we'll see. */ - int frame_changed = (f->buffers_changed || - f->clip_changed || - f->faces_changed || - f->frame_changed || - f->modeline_changed || - f->subwindows_changed || - f->windows_changed || - f->windows_structure_changed); + int frame_really_changed = (f->buffers_changed || + f->clip_changed || + f->faces_changed || + f->frame_changed || + f->modeline_changed || + f->subwindows_changed || + f->windows_changed || + f->windows_structure_changed); XSETWINDOW (window, w); @@ -1246,7 +1246,7 @@ redisplay_output_layout (struct window *w, /* Highly dodgy optimization. We want to only output the whole layout if we really have to. */ - if (frame_changed || IMAGE_INSTANCE_DIRTYP (p)) + if (frame_really_changed || IMAGE_INSTANCE_DIRTYP (p)) { /* First clear the area we are drawing into. This is the easiest thing to do since we have many gaps that we have to make sure are @@ -1348,7 +1348,7 @@ redisplay_output_layout (struct window *w, generalisation.*/ if (redisplay_normalize_glyph_area (&cdb, &cdga) && - (frame_changed || IMAGE_INSTANCE_DIRTYP (childii))) + (frame_really_changed || IMAGE_INSTANCE_DIRTYP (childii))) { struct display_line dl; /* this is fake */ Lisp_Object string = @@ -1382,14 +1382,14 @@ redisplay_output_layout (struct window *w, case IMAGE_MONO_PIXMAP: case IMAGE_COLOR_PIXMAP: - if (frame_changed || IMAGE_INSTANCE_DIRTYP (childii)) + if (frame_really_changed || IMAGE_INSTANCE_DIRTYP (childii)) redisplay_output_pixmap (w, child, &cdb, &cdga, findex, 0, 0, 0, 0); break; case IMAGE_WIDGET: case IMAGE_SUBWINDOW: - if (frame_changed || IMAGE_INSTANCE_DIRTYP (childii)) + if (frame_really_changed || IMAGE_INSTANCE_DIRTYP (childii)) redisplay_output_subwindow (w, child, &cdb, &cdga, findex, 0, 0, 0); break; diff --git a/src/redisplay.c b/src/redisplay.c index d9c9855..fa3e3b3 100644 --- a/src/redisplay.c +++ b/src/redisplay.c @@ -6451,8 +6451,7 @@ redisplay_device (struct device *d) if (FRAME_REPAINT_P (f)) { - if (CLASS_REDISPLAY_FLAGS_CHANGEDP(f) - || f->size_changed) + if (CLASS_REDISPLAY_FLAGS_CHANGEDP (f)) { preempted = redisplay_frame (f, 0); } @@ -6503,7 +6502,7 @@ redisplay_without_hooks (void) handle_asynch_device_change (); if (!GLOBAL_REDISPLAY_FLAGS_CHANGEDP && - !size_changed && !disable_preemption && preemption_count < max_preempts) + !disable_preemption && preemption_count < max_preempts) goto done; DEVICE_LOOP_NO_BREAK (devcons, concons) @@ -6511,8 +6510,7 @@ redisplay_without_hooks (void) struct device *d = XDEVICE (XCAR (devcons)); int preempted; - if (CLASS_REDISPLAY_FLAGS_CHANGEDP (d) - || d->size_changed) + if (CLASS_REDISPLAY_FLAGS_CHANGEDP (d)) { preempted = redisplay_device (d); @@ -7411,7 +7409,7 @@ int point_would_be_visible (struct window *w, Bufpos startp, Bufpos point) { struct buffer *b = XBUFFER (w->buffer); - int pixpos = 0; + int pixpos = -WINDOW_TEXT_TOP_CLIP(w); int bottom = WINDOW_TEXT_HEIGHT (w); int start_elt; diff --git a/src/redisplay.h b/src/redisplay.h index f79847c..37d88ea 100644 --- a/src/redisplay.h +++ b/src/redisplay.h @@ -560,7 +560,7 @@ extern int windows_structure_changed; gutter_changed = 0; \ glyphs_changed = 0; \ subwindows_changed = 0; \ - subwindows_state_changed = 0; \ + subwindows_state_changed = 0; \ windows_changed = 0; \ windows_structure_changed = 0; \ } while (0) @@ -578,6 +578,7 @@ extern int windows_structure_changed; (p)->toolbar_changed || \ (p)->gutter_changed || \ (p)->glyphs_changed || \ + (p)->size_changed || \ (p)->subwindows_changed || \ (p)->subwindows_state_changed || \ (p)->windows_changed || \ @@ -596,6 +597,7 @@ extern int windows_structure_changed; toolbar_changed || \ gutter_changed || \ glyphs_changed || \ + size_changed || \ subwindows_changed || \ subwindows_state_changed || \ windows_changed || \ diff --git a/src/s/cygwin32.h b/src/s/cygwin32.h index 19d7c55..def1faa 100644 --- a/src/s/cygwin32.h +++ b/src/s/cygwin32.h @@ -47,8 +47,12 @@ Boston, MA 02111-1307, USA. */ #include #else #ifdef SIGIO +#define CYGWIN_VERSION_DLL_MAJOR 19 +#define CYGWIN_VERSION_DLL_MINOR 0 #define CYGWIN_B19 #else +#define CYGWIN_VERSION_DLL_MAJOR 18 +#define CYGWIN_VERSION_DLL_MINOR 0 #define BROKEN_CYGWIN #endif #endif @@ -57,7 +61,7 @@ extern void cygwin32_win32_to_posix_path_list(const char*, char*); extern int cygwin32_win32_to_posix_path_list_buf_size(const char*); extern void cygwin32_posix_to_win32_path_list(const char*, char*); extern int cygwin32_posix_to_win32_path_list_buf_size(const char*); -#ifndef CYGWIN_VERSION_DLL_MAJOR +#if CYGWIN_VERSION_DLL_MAJOR < 20 struct timeval; struct timezone; struct itimerval; diff --git a/src/select-msw.c b/src/select-msw.c index 616f0d6..a760eb0 100644 --- a/src/select-msw.c +++ b/src/select-msw.c @@ -29,6 +29,7 @@ Boston, MA 02111-1307, USA. */ #include #include "lisp.h" +#include "frame.h" #include "select.h" #include "console-msw.h" @@ -41,6 +42,7 @@ Copy STRING to the mswindows clipboard. int rawsize, size, i; unsigned char *src, *dst, *next; HGLOBAL h = NULL; + struct frame *f = NULL; CHECK_STRING (string); @@ -52,7 +54,8 @@ Copy STRING to the mswindows clipboard. if (src[i] == '\n') size++; - if (!OpenClipboard (NULL)) + f = selected_frame (); + if (!OpenClipboard (FRAME_MSWINDOWS_HANDLE (f))) return Qnil; if (!EmptyClipboard () || @@ -88,7 +91,6 @@ Copy STRING to the mswindows clipboard. i = (SetClipboardData (CF_TEXT, h) != NULL); CloseClipboard (); - GlobalFree (h); return i ? Qt : Qnil; } @@ -184,7 +186,16 @@ Remove the current MS-Windows selection from the clipboard. */ ()) { - return EmptyClipboard () ? Qt : Qnil; + BOOL success = OpenClipboard (NULL); + if (success) + { + success = EmptyClipboard (); + /* Close it regardless of whether empty worked. */ + if (!CloseClipboard ()) + success = FALSE; + } + + return success ? Qt : Qnil; } static void diff --git a/src/sound.c b/src/sound.c index 4a8786f..c9fe1b0 100644 --- a/src/sound.c +++ b/src/sound.c @@ -379,8 +379,8 @@ device). */ (arg, sound, device)) { - static time_t last_bell_time = (time_t) 0; - static struct device *last_bell_device = (struct device*) 0; + static time_t last_bell_time; + static struct device *last_bell_device; time_t now; struct device *d = decode_device (device); diff --git a/src/sysdep.c b/src/sysdep.c index ea912f0..607d2e3 100644 --- a/src/sysdep.c +++ b/src/sysdep.c @@ -424,7 +424,7 @@ void child_setup_tty (int out) { struct emacs_tty s; - EMACS_GET_TTY (out, &s); + emacs_get_tty (out, &s); #if defined (HAVE_TERMIO) || defined (HAVE_TERMIOS) assert (isatty(out)); @@ -516,7 +516,7 @@ child_setup_tty (int out) s.lmode = LLITOUT | s.lmode; /* Don't strip 8th bit */ #endif /* not HAVE_TERMIO */ - EMACS_SET_TTY (out, &s, 0); + emacs_set_tty (out, &s, 0); #ifdef RTU { @@ -1372,7 +1372,8 @@ emacs_get_tty (int fd, struct emacs_tty *settings) /* Set the parameters of the tty on FD according to the contents of *SETTINGS. If FLUSHP is non-zero, we discard input. - Return 0 if all went well, and -1 if anything failed. */ + Return 0 if all went well, and -1 if anything failed. + #### All current callers use FLUSHP == 0. */ int emacs_set_tty (int fd, struct emacs_tty *settings, int flushp) @@ -1482,7 +1483,7 @@ tty_init_sys_modes_on_device (struct device *d) input_fd = CONSOLE_TTY_DATA (con)->infd; output_fd = CONSOLE_TTY_DATA (con)->outfd; - EMACS_GET_TTY (input_fd, &CONSOLE_TTY_DATA (con)->old_tty); + emacs_get_tty (input_fd, &CONSOLE_TTY_DATA (con)->old_tty); tty = CONSOLE_TTY_DATA (con)->old_tty; con->tty_erase_char = Qnil; @@ -1649,7 +1650,7 @@ tty_init_sys_modes_on_device (struct device *d) tty.ltchars = new_ltchars; #endif /* HAVE_LTCHARS */ - EMACS_SET_TTY (input_fd, &tty, 0); + emacs_set_tty (input_fd, &tty, 0); /* This code added to insure that, if flow-control is not to be used, we have an unlocked terminal at the start. */ @@ -1756,7 +1757,7 @@ tabs_safe_p (struct device *d) { struct emacs_tty tty; - EMACS_GET_TTY (DEVICE_INFD (d), &tty); + emacs_get_tty (DEVICE_INFD (d), &tty); return EMACS_TTY_TABS_OK (&tty); } #endif @@ -1829,7 +1830,7 @@ eight_bit_tty (struct device *d) assert (DEVICE_TTY_P (d)); input_fd = DEVICE_INFD (d); - EMACS_GET_TTY (input_fd, &s); + emacs_get_tty (input_fd, &s); #if defined (HAVE_TERMIO) || defined (HAVE_TERMIOS) eight_bit = (s.main.c_cflag & CSIZE) == CS8; @@ -1879,7 +1880,7 @@ tty_reset_sys_modes_on_device (struct device *d) fsync (output_fd); #endif - while (EMACS_SET_TTY (input_fd, &CONSOLE_TTY_DATA (con)->old_tty, 0) + while (emacs_set_tty (input_fd, &CONSOLE_TTY_DATA (con)->old_tty, 0) < 0 && errno == EINTR) ; diff --git a/src/sysdep.h b/src/sysdep.h index 79e6a76..04432e9 100644 --- a/src/sysdep.h +++ b/src/sysdep.h @@ -27,10 +27,6 @@ Boston, MA 02111-1307, USA. */ extern char **environ; -struct emacs_tty; -int emacs_get_tty (int fd, struct emacs_tty *settings); -int emacs_set_tty (int fd, struct emacs_tty *settings, int waitp); - int eight_bit_tty (struct device *d); void stuff_char (struct console *con, int c); @@ -78,10 +74,10 @@ void reset_poll_for_quit (void); extern JMP_BUF break_system_call_jump; extern volatile int can_break_system_calls; -int sys_write_1 (int fildes, CONST void *buf, size_t nbyte, - int allow_quit); -int sys_read_1 (int fildes, void *buf, size_t nbyte, - int allow_quit); +ssize_t sys_write_1 (int fildes, CONST void *buf, size_t nbyte, + int allow_quit); +ssize_t sys_read_1 (int fildes, void *buf, size_t nbyte, + int allow_quit); /* Call these functions if you want to change some terminal parameter -- reset the console, change the parameter, and init it again. */ diff --git a/src/sysdll.c b/src/sysdll.c index d6e7df9..abc70b8 100644 --- a/src/sysdll.c +++ b/src/sysdll.c @@ -23,6 +23,7 @@ Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA #include #endif +#include #include "sysdll.h" /* This whole file is conditional upon HAVE_SHLIB */ diff --git a/src/systty.h b/src/systty.h index 3f9efdb..a2c5b36 100644 --- a/src/systty.h +++ b/src/systty.h @@ -358,11 +358,11 @@ Boston, MA 02111-1307, USA. */ emacs_tty should contain an element for each parameter struct that Emacs may change. - EMACS_GET_TTY (int FD, struct emacs_tty *P) stores the parameters + emacs_get_tty (int FD, struct emacs_tty *P) stores the parameters of the tty on FD in *P. Return zero if all's well, or -1 if we ran into an error we couldn't deal with. - EMACS_SET_TTY (int FD, struct emacs_tty *P, int flushp) + emacs_set_tty (int FD, struct emacs_tty *P, int flushp) sets the parameters of the tty on FD according to the contents of *P. If flushp is non-zero, we discard queued input to be written before making the change. @@ -409,15 +409,9 @@ struct emacs_tty { #endif /* HAVE_TCHARS */ #endif /* HAVE_TERMIOS */ }; - -/* Define EMACS_GET_TTY and EMACS_SET_TTY, - the macros for reading and setting parts of `struct emacs_tty'. - - These got pretty unmanageable (huge macros are hard to debug), and - finally needed some code which couldn't be done as part of an - expression, so we moved them out to their own functions in sysdep.c. */ -#define EMACS_GET_TTY(fd, p) emacs_get_tty (fd, p) -#define EMACS_SET_TTY(fd, p, waitp) emacs_set_tty (fd, p, waitp) + +int emacs_get_tty (int fd, struct emacs_tty *settings); +int emacs_set_tty (int fd, struct emacs_tty *settings, int flushp); /* --------------------------------------------------------- */ diff --git a/src/unexcw.c b/src/unexcw.c index 276f5ff..74f131e 100644 --- a/src/unexcw.c +++ b/src/unexcw.c @@ -40,7 +40,9 @@ unexec (char *, char *, void *, void *, void *) #else #undef CONST -#include +#ifndef MAX_PATH +#define MAX_PATH 260 +#endif #include #define ALLOC_UNIT 0xFFFF diff --git a/src/unexhp9k800.c b/src/unexhp9k800.c index c89fb01..9c2bad9 100644 --- a/src/unexhp9k800.c +++ b/src/unexhp9k800.c @@ -52,6 +52,7 @@ Boston, MA 02111-1307, USA. */ #include +#include #include #include #include @@ -80,7 +81,7 @@ Boston, MA 02111-1307, USA. */ #ifdef HPUX_USE_SHLIBS #include /* User-space dynamic loader entry points */ -void Save_Shared_Data(); +void Save_Shared_Data(void); int run_time_remap(); #endif diff --git a/src/unexsol2.c b/src/unexsol2.c index d9de182..06e71e7 100644 --- a/src/unexsol2.c +++ b/src/unexsol2.c @@ -20,7 +20,7 @@ Boston, MA 02111-1307, USA. */ /* Synched up with: Not in FSF. */ -/* #pragma ident "@(#) $Id: unexsol2.c,v 1.2 1995/01/25 20:39:16 georgn Exp $" */ +/* #pragma ident "@(#) $Id: unexsol2.c,v 1.3 1997/10/13 03:35:33 steve Exp $" */ #include #include diff --git a/src/window.c b/src/window.c index a63fe35..cdf35a0 100644 --- a/src/window.c +++ b/src/window.c @@ -1865,6 +1865,12 @@ will automatically call `save-buffers-kill-emacs'.) par = XWINDOW (parent); MARK_FRAME_WINDOWS_STRUCTURE_CHANGED (f); + /* It's quite likely that deleting a window will result in + subwindows needing to be deleted also (since they are cached + per-window). So we mark them as changed, so that the cachels will + get reset by redisplay and thus deleted subwindows can get + GC'd. */ + MARK_FRAME_SUBWINDOWS_CHANGED (f); /* Are we trying to delete any frame's selected window? Note that we could be dealing with a non-leaf window diff --git a/tests/ChangeLog b/tests/ChangeLog index 0829572..5265be8 100644 --- a/tests/ChangeLog +++ b/tests/ChangeLog @@ -1,3 +1,7 @@ +1999-12-07 Martin Buchholz + + * XEmacs 21.2.23 is released. + 1999-11-29 XEmacs Build Bot * XEmacs 21.2.22 is released diff --git a/version.sh b/version.sh index b501d5e..53a3857 100644 --- a/version.sh +++ b/version.sh @@ -2,8 +2,8 @@ emacs_is_beta=t emacs_major_version=21 emacs_minor_version=2 -emacs_beta_version=22 -xemacs_codename="Mercedes" +emacs_beta_version=23 +xemacs_codename="Hebe" infodock_major_version=4 infodock_minor_version=0 infodock_build_version=8