diff options
author | Karl Berry <karl@freefriends.org> | 2009-01-25 01:57:18 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-01-25 01:57:18 +0000 |
commit | af944c3e4ba74f59f21178c8477fdea4b682ef2b (patch) | |
tree | afa6af46a5179bdbd38a05fa7d63b2ff8ae32516 /Build/source/utils/texinfo/doc | |
parent | 0cea5be7570fb0ddc3d28e6bb8371809e04ca2ae (diff) |
remove texinfo
git-svn-id: svn://tug.org/texlive/trunk@11963 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/utils/texinfo/doc')
41 files changed, 0 insertions, 39513 deletions
diff --git a/Build/source/utils/texinfo/doc/Makefile.am b/Build/source/utils/texinfo/doc/Makefile.am deleted file mode 100644 index e4182c4b358..00000000000 --- a/Build/source/utils/texinfo/doc/Makefile.am +++ /dev/null @@ -1,124 +0,0 @@ -# $Id: Makefile.am,v 1.37 2008/03/25 10:51:19 akim Exp $ -# Makefile.am for texinfo/doc. -# Run automake in .. to produce Makefile.in from this. -# -# This file is free software; as a special exception the author gives -# unlimited permission to copy and/or distribute it, with or without -# modifications, as long as this notice is preserved. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the -# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - -# Put texinfo.txi first because that's the most important. -info_TEXINFOS = texinfo.txi info-stnd.texi info.texi -DISTCLEANFILES = texinfo texinfo-* info*.info* - -man_MANS = info.1 infokey.1 install-info.1 makeinfo.1 texindex.1 \ - info.5 texinfo.5 - -# Use the programs built in our distribution, taking account of possible -# cross-compiling. -MAKEINFO = $(top_builddir)/$(native_tools)/makeinfo/makeinfo - -# We'd also like to use something like this, but Automake calls -# "install-info" directly. -# INSTALL_INFO = $(top_builddir)/$(native_tools)/util/ginstall-info - -TXI_XLATE = txi-cs.tex txi-de.tex txi-en.tex txi-es.tex txi-fr.tex \ - txi-it.tex txi-nl.tex txi-nb.tex txi-pl.tex txi-pt.tex \ - txi-ru.tex txi-sr.tex txi-tr.tex txi-uk.tex - -# Include our texinfo.tex, not Automake's. -EXTRA_DIST = epsf.tex texinfo.tex \ - fdl.texi \ - $(man_MANS) $(TXI_XLATE) - -if INSTALL_WARNINGS -install-data-local: - @echo - @echo "WARNING: If your texmf tree does not already contain" - @echo " up-to-date versions, you must install" - @echo " texinfo.tex and txi-??.tex manually," - @echo " perhaps in TEXMF/tex/texinfo/," - @echo " where TEXMF is a root of your TeX tree." - @echo " See doc/README for some considerations." - @echo " You can run make TEXMF=/your/texmf install-tex to do this." - @echo - @echo " You may also need to install epsf.tex in" - @echo " TEXMF/tex/generic/dvips, if your TeX" - @echo " installation did not include it." -endif - -texmf_texinfo = $(TEXMF)/tex/texinfo -texmf_dvips = $(TEXMF)/tex/generic/epsf -install-tex: - test -n "$(TEXMF)" || (echo "TEXMF must be set." >&2; exit 1) - $(mkinstalldirs) $(DESTDIR)$(texmf_texinfo) $(DESTDIR)$(texmf_dvips) - $(INSTALL_DATA) $(srcdir)/texinfo.tex $(DESTDIR)$(texmf_texinfo)/texinfo.tex - $(INSTALL_DATA) $(srcdir)/epsf.tex $(DESTDIR)$(texmf_dvips)/epsf.tex - for f in $(TXI_XLATE); do \ - $(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(texmf_texinfo)/$$f; done - -# The man pages depend on the --help strings and the version number. -common_mandeps = $(top_srcdir)/configure.ac - -# Set up the variables: -man_rule_0 = \ - program=`expr '/$@' : '.*/\(.*\)\.1'` && \ - case $$program in makeinfo) dir=makeinfo;; info*) dir=info;; \ - *install-info) dir=install-info;; *) dir=util;; esac && \ - dir="$(top_builddir)/$(native_tools)/$$dir" && \ - case $$program in info|install-info) program=g$$program;; \ - esac - -# Update the manpage for a binary program; set up the variables, -# make sure the binary is up-to-date and then generate the man page. -man_rule_bin = echo "Updating man page $@" && \ - $(man_rule_0) && \ - echo cd "$$dir" '&&' $(MAKE) $(AM_MAKEFLAGS) $$program$(EXEEXT) && \ - (cd "$$dir" && $(MAKE) $(AM_MAKEFLAGS) $$program$(EXEEXT)) && \ - echo $(HELP2MAN) --name=\""$$name"\" "$$dir/$$program" -o '$@' && \ - $(HELP2MAN) --name="$$name" "$$dir/$$program" -o '$@' - -$(srcdir)/info.1: $(top_srcdir)/info/info.c $(common_mandeps) - @name="read Info documents" && $(man_rule_bin) -$(srcdir)/infokey.1: $(top_srcdir)/info/infokey.c $(common_mandeps) - @name="compile customizations for Info" && $(man_rule_bin) -$(srcdir)/install-info.1: $(top_srcdir)/install-info/install-info.c $(common_mandeps) - @name="update info/dir entries" && $(man_rule_bin) - -# Here we need some postprocessing: -$(srcdir)/makeinfo.1: $(top_srcdir)/makeinfo/makeinfo.c $(common_mandeps) - @name="translate Texinfo documents" && $(man_rule_bin) - mv $@ $@.tmp - sed '/^\.IP$$/N;/\nAlso/s/I//;/\nThe/s/I//' $@.tmp >$@ - rm $@.tmp - -$(srcdir)/texindex.1: $(util_srcdir)/texindex.c $(common_mandeps) - @name="sort Texinfo index files" && $(man_rule_bin) - - -## ---------- ## -## texi2dvi. ## -## ---------- ## - -man_MANS += texi2dvi.1 texi2pdf.1 pdftexi2dvi.1 -util_srcdir = $(top_srcdir)/util -# Do not depend on the current user's settings. -unset_envvars = unset TEXI2DVI_BUILD_MODE; unset TEXI2DVI_BUILD_DIRECTORY - -common_texi2dvi_deps = $(common_mandeps) \ - $(util_srcdir)/texi2dvi $(util_srcdir)/texi2pdf - -$(srcdir)/texi2dvi.1: $(common_texi2dvi_deps) - $(unset_envvars); $(HELP2MAN) --name="convert Texinfo documents to DVI" $(util_srcdir)/texi2dvi >$@ - -$(srcdir)/texi2pdf.1: $(common_texi2dvi_deps) - $(unset_envvars); $(HELP2MAN) --name="convert Texinfo documents to PDF" $(util_srcdir)/texi2pdf >$@ - -$(srcdir)/pdftexi2dvi.1: $(common_texi2dvi_deps) - $(unset_envvars); $(HELP2MAN) --name="convert Texinfo documents to PDF" $(util_srcdir)/pdftexi2dvi >$@ - -# Do not create info files for distribution. -dist-info: diff --git a/Build/source/utils/texinfo/doc/Makefile.in b/Build/source/utils/texinfo/doc/Makefile.in deleted file mode 100644 index f43ae4c68cf..00000000000 --- a/Build/source/utils/texinfo/doc/Makefile.in +++ /dev/null @@ -1,1113 +0,0 @@ -# Makefile.in generated by automake 1.10.1 from Makefile.am. -# @configure_input@ - -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. -# This Makefile.in is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY, to the extent permitted by law; without -# even the implied warranty of MERCHANTABILITY or FITNESS FOR A -# PARTICULAR PURPOSE. - -@SET_MAKE@ - -# $Id: Makefile.am,v 1.37 2008/03/25 10:51:19 akim Exp $ -# Makefile.am for texinfo/doc. -# Run automake in .. to produce Makefile.in from this. -# -# This file is free software; as a special exception the author gives -# unlimited permission to copy and/or distribute it, with or without -# modifications, as long as this notice is preserved. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the -# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -VPATH = @srcdir@ -pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ -pkgincludedir = $(includedir)/@PACKAGE@ -am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -install_sh_DATA = $(install_sh) -c -m 644 -install_sh_PROGRAM = $(install_sh) -c -install_sh_SCRIPT = $(install_sh) -c -INSTALL_HEADER = $(INSTALL_DATA) -transform = $(program_transform_name) -NORMAL_INSTALL = : -PRE_INSTALL = : -POST_INSTALL = : -NORMAL_UNINSTALL = : -PRE_UNINSTALL = : -POST_UNINSTALL = : -build_triplet = @build@ -host_triplet = @host@ -subdir = doc -DIST_COMMON = README $(info_TEXINFOS) $(srcdir)/Makefile.am \ - $(srcdir)/Makefile.in $(srcdir)/stamp-1 $(srcdir)/stamp-vti \ - $(srcdir)/version-stnd.texi $(srcdir)/version.texi texinfo.tex -ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 -am__aclocal_m4_deps = $(top_srcdir)/gnulib/m4/alloca.m4 \ - $(top_srcdir)/gnulib/m4/argz.m4 \ - $(top_srcdir)/gnulib/m4/codeset.m4 \ - $(top_srcdir)/gnulib/m4/eealloc.m4 \ - $(top_srcdir)/gnulib/m4/environ.m4 \ - $(top_srcdir)/gnulib/m4/error.m4 \ - $(top_srcdir)/gnulib/m4/exitfail.m4 \ - $(top_srcdir)/gnulib/m4/extensions.m4 \ - $(top_srcdir)/gnulib/m4/getopt.m4 \ - $(top_srcdir)/gnulib/m4/gettext.m4 \ - $(top_srcdir)/gnulib/m4/gettimeofday.m4 \ - $(top_srcdir)/gnulib/m4/glibc21.m4 \ - $(top_srcdir)/gnulib/m4/gnulib-common.m4 \ - $(top_srcdir)/gnulib/m4/gnulib-comp.m4 \ - $(top_srcdir)/gnulib/m4/iconv.m4 \ - $(top_srcdir)/gnulib/m4/include_next.m4 \ - $(top_srcdir)/gnulib/m4/inline.m4 \ - $(top_srcdir)/gnulib/m4/intlmacosx.m4 \ - $(top_srcdir)/gnulib/m4/lib-ld.m4 \ - $(top_srcdir)/gnulib/m4/lib-link.m4 \ - $(top_srcdir)/gnulib/m4/lib-prefix.m4 \ - $(top_srcdir)/gnulib/m4/localcharset.m4 \ - $(top_srcdir)/gnulib/m4/longlong.m4 \ - $(top_srcdir)/gnulib/m4/malloc.m4 \ - $(top_srcdir)/gnulib/m4/malloca.m4 \ - $(top_srcdir)/gnulib/m4/mbchar.m4 \ - $(top_srcdir)/gnulib/m4/mbiter.m4 \ - $(top_srcdir)/gnulib/m4/mbrtowc.m4 \ - $(top_srcdir)/gnulib/m4/mbscasecmp.m4 \ - $(top_srcdir)/gnulib/m4/mbsncasecmp.m4 \ - $(top_srcdir)/gnulib/m4/mbstate_t.m4 \ - $(top_srcdir)/gnulib/m4/mbswidth.m4 \ - $(top_srcdir)/gnulib/m4/memchr.m4 \ - $(top_srcdir)/gnulib/m4/memcpy.m4 \ - $(top_srcdir)/gnulib/m4/memmove.m4 \ - $(top_srcdir)/gnulib/m4/mkstemp.m4 \ - $(top_srcdir)/gnulib/m4/nls.m4 \ - $(top_srcdir)/gnulib/m4/onceonly.m4 \ - $(top_srcdir)/gnulib/m4/po.m4 \ - $(top_srcdir)/gnulib/m4/progtest.m4 \ - $(top_srcdir)/gnulib/m4/setenv.m4 \ - $(top_srcdir)/gnulib/m4/stdbool.m4 \ - $(top_srcdir)/gnulib/m4/stdint.m4 \ - $(top_srcdir)/gnulib/m4/stdlib_h.m4 \ - $(top_srcdir)/gnulib/m4/strdup.m4 \ - $(top_srcdir)/gnulib/m4/strerror.m4 \ - $(top_srcdir)/gnulib/m4/string_h.m4 \ - $(top_srcdir)/gnulib/m4/sys_stat_h.m4 \ - $(top_srcdir)/gnulib/m4/sys_time_h.m4 \ - $(top_srcdir)/gnulib/m4/tempname.m4 \ - $(top_srcdir)/gnulib/m4/unistd_h.m4 \ - $(top_srcdir)/gnulib/m4/wchar.m4 \ - $(top_srcdir)/gnulib/m4/wchar_t.m4 \ - $(top_srcdir)/gnulib/m4/wctype.m4 \ - $(top_srcdir)/gnulib/m4/wcwidth.m4 \ - $(top_srcdir)/gnulib/m4/wint_t.m4 \ - $(top_srcdir)/gnulib/m4/xalloc.m4 $(top_srcdir)/configure.ac -am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ - $(ACLOCAL_M4) -mkinstalldirs = $(install_sh) -d -CONFIG_HEADER = $(top_builddir)/config.h -CONFIG_CLEAN_FILES = -SOURCES = -DIST_SOURCES = -INFO_DEPS = texinfo info-stnd.info info.info -TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex -am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux -DVIS = texinfo.dvi info-stnd.dvi info.dvi -PDFS = texinfo.pdf info-stnd.pdf info.pdf -PSS = texinfo.ps info-stnd.ps info.ps -HTMLS = texinfo.html info-stnd.html info.html -TEXINFOS = texinfo.txi info-stnd.texi info.texi -TEXI2DVI = texi2dvi -TEXI2PDF = $(TEXI2DVI) --pdf --batch -MAKEINFOHTML = $(MAKEINFO) --html -AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) -DVIPS = dvips -am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" \ - "$(DESTDIR)$(man5dir)" -am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; -am__vpath_adj = case $$p in \ - $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ - *) f=$$p;; \ - esac; -am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; -man1dir = $(mandir)/man1 -man5dir = $(mandir)/man5 -NROFF = nroff -MANS = $(man_MANS) -DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) -ACLOCAL = @ACLOCAL@ -ALLOCA = @ALLOCA@ -ALLOCA_H = @ALLOCA_H@ -AMTAR = @AMTAR@ -ARGZ_H = @ARGZ_H@ -AUTOCONF = @AUTOCONF@ -AUTOHEADER = @AUTOHEADER@ -AUTOMAKE = @AUTOMAKE@ -AWK = @AWK@ -BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@ -BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@ -BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@ -BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@ -BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@ -CC = @CC@ -CCDEPMODE = @CCDEPMODE@ -CFLAGS = @CFLAGS@ -CPP = @CPP@ -CPPFLAGS = @CPPFLAGS@ -CYGPATH_W = @CYGPATH_W@ -DEFS = @DEFS@ -DEPDIR = @DEPDIR@ -ECHO_C = @ECHO_C@ -ECHO_N = @ECHO_N@ -ECHO_T = @ECHO_T@ -EGREP = @EGREP@ -EXEEXT = @EXEEXT@ -GETOPT_H = @GETOPT_H@ -GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@ -GLIBC21 = @GLIBC21@ -GMSGFMT = @GMSGFMT@ -GMSGFMT_015 = @GMSGFMT_015@ -GNULIB_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@ -GNULIB_CHOWN = @GNULIB_CHOWN@ -GNULIB_DUP2 = @GNULIB_DUP2@ -GNULIB_ENVIRON = @GNULIB_ENVIRON@ -GNULIB_FCHDIR = @GNULIB_FCHDIR@ -GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@ -GNULIB_GETCWD = @GNULIB_GETCWD@ -GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@ -GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@ -GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@ -GNULIB_LCHOWN = @GNULIB_LCHOWN@ -GNULIB_LSEEK = @GNULIB_LSEEK@ -GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@ -GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@ -GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@ -GNULIB_MBSCHR = @GNULIB_MBSCHR@ -GNULIB_MBSCSPN = @GNULIB_MBSCSPN@ -GNULIB_MBSLEN = @GNULIB_MBSLEN@ -GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@ -GNULIB_MBSNLEN = @GNULIB_MBSNLEN@ -GNULIB_MBSPBRK = @GNULIB_MBSPBRK@ -GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@ -GNULIB_MBSRCHR = @GNULIB_MBSRCHR@ -GNULIB_MBSSEP = @GNULIB_MBSSEP@ -GNULIB_MBSSPN = @GNULIB_MBSSPN@ -GNULIB_MBSSTR = @GNULIB_MBSSTR@ -GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@ -GNULIB_MEMMEM = @GNULIB_MEMMEM@ -GNULIB_MEMPCPY = @GNULIB_MEMPCPY@ -GNULIB_MEMRCHR = @GNULIB_MEMRCHR@ -GNULIB_MKDTEMP = @GNULIB_MKDTEMP@ -GNULIB_MKSTEMP = @GNULIB_MKSTEMP@ -GNULIB_PUTENV = @GNULIB_PUTENV@ -GNULIB_READLINK = @GNULIB_READLINK@ -GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@ -GNULIB_SETENV = @GNULIB_SETENV@ -GNULIB_SLEEP = @GNULIB_SLEEP@ -GNULIB_STPCPY = @GNULIB_STPCPY@ -GNULIB_STPNCPY = @GNULIB_STPNCPY@ -GNULIB_STRCASESTR = @GNULIB_STRCASESTR@ -GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@ -GNULIB_STRDUP = @GNULIB_STRDUP@ -GNULIB_STRERROR = @GNULIB_STRERROR@ -GNULIB_STRNDUP = @GNULIB_STRNDUP@ -GNULIB_STRNLEN = @GNULIB_STRNLEN@ -GNULIB_STRPBRK = @GNULIB_STRPBRK@ -GNULIB_STRSEP = @GNULIB_STRSEP@ -GNULIB_STRSIGNAL = @GNULIB_STRSIGNAL@ -GNULIB_STRSTR = @GNULIB_STRSTR@ -GNULIB_STRTOD = @GNULIB_STRTOD@ -GNULIB_STRTOK_R = @GNULIB_STRTOK_R@ -GNULIB_UNSETENV = @GNULIB_UNSETENV@ -GNULIB_WCWIDTH = @GNULIB_WCWIDTH@ -GREP = @GREP@ -HAVE_CALLOC_POSIX = @HAVE_CALLOC_POSIX@ -HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@ -HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@ -HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@ -HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@ -HAVE_DECL_MKDIR = @HAVE_DECL_MKDIR@ -HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@ -HAVE_DECL_STRERROR = @HAVE_DECL_STRERROR@ -HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@ -HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@ -HAVE_DECL_STRSIGNAL = @HAVE_DECL_STRSIGNAL@ -HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@ -HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@ -HAVE_DUP2 = @HAVE_DUP2@ -HAVE_FTRUNCATE = @HAVE_FTRUNCATE@ -HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@ -HAVE_GETSUBOPT = @HAVE_GETSUBOPT@ -HAVE_INTTYPES_H = @HAVE_INTTYPES_H@ -HAVE_IO_H = @HAVE_IO_H@ -HAVE_ISWCNTRL = @HAVE_ISWCNTRL@ -HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@ -HAVE_LSTAT = @HAVE_LSTAT@ -HAVE_MALLOC_POSIX = @HAVE_MALLOC_POSIX@ -HAVE_MEMPCPY = @HAVE_MEMPCPY@ -HAVE_MKDTEMP = @HAVE_MKDTEMP@ -HAVE_OS_H = @HAVE_OS_H@ -HAVE_READLINK = @HAVE_READLINK@ -HAVE_REALLOC_POSIX = @HAVE_REALLOC_POSIX@ -HAVE_SETENV = @HAVE_SETENV@ -HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@ -HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@ -HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@ -HAVE_SLEEP = @HAVE_SLEEP@ -HAVE_STDINT_H = @HAVE_STDINT_H@ -HAVE_STPCPY = @HAVE_STPCPY@ -HAVE_STPNCPY = @HAVE_STPNCPY@ -HAVE_STRCASESTR = @HAVE_STRCASESTR@ -HAVE_STRCHRNUL = @HAVE_STRCHRNUL@ -HAVE_STRNDUP = @HAVE_STRNDUP@ -HAVE_STRPBRK = @HAVE_STRPBRK@ -HAVE_STRSEP = @HAVE_STRSEP@ -HAVE_STRTOD = @HAVE_STRTOD@ -HAVE_STRUCT_TIMEVAL = @HAVE_STRUCT_TIMEVAL@ -HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@ -HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@ -HAVE_SYS_PARAM_H = @HAVE_SYS_PARAM_H@ -HAVE_SYS_TIME_H = @HAVE_SYS_TIME_H@ -HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@ -HAVE_UNISTD_H = @HAVE_UNISTD_H@ -HAVE_UNSETENV = @HAVE_UNSETENV@ -HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@ -HAVE_WCHAR_H = @HAVE_WCHAR_H@ -HAVE_WCTYPE_H = @HAVE_WCTYPE_H@ -HAVE_WINT_T = @HAVE_WINT_T@ -HAVE__BOOL = @HAVE__BOOL@ -HELP2MAN = @HELP2MAN@ -HEVEA = @HEVEA@ -INCLUDE_NEXT = @INCLUDE_NEXT@ -INSTALL = @INSTALL@ -INSTALL_DATA = @INSTALL_DATA@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_SCRIPT = @INSTALL_SCRIPT@ -INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ -INTLLIBS = @INTLLIBS@ -INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ -LDFLAGS = @LDFLAGS@ -LIBGNU_LIBDEPS = @LIBGNU_LIBDEPS@ -LIBGNU_LTLIBDEPS = @LIBGNU_LTLIBDEPS@ -LIBICONV = @LIBICONV@ -LIBINTL = @LIBINTL@ -LIBOBJS = @LIBOBJS@ -LIBS = @LIBS@ -LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@ -LTLIBICONV = @LTLIBICONV@ -LTLIBINTL = @LTLIBINTL@ -LTLIBOBJS = @LTLIBOBJS@ -MAINT = @MAINT@ - -# Use the programs built in our distribution, taking account of possible -# cross-compiling. -MAKEINFO = $(top_builddir)/$(native_tools)/makeinfo/makeinfo -MKDIR_P = @MKDIR_P@ -MSGFMT = @MSGFMT@ -MSGFMT_015 = @MSGFMT_015@ -MSGMERGE = @MSGMERGE@ -NEXT_STDINT_H = @NEXT_STDINT_H@ -NEXT_STDLIB_H = @NEXT_STDLIB_H@ -NEXT_STRING_H = @NEXT_STRING_H@ -NEXT_SYS_STAT_H = @NEXT_SYS_STAT_H@ -NEXT_SYS_TIME_H = @NEXT_SYS_TIME_H@ -NEXT_UNISTD_H = @NEXT_UNISTD_H@ -NEXT_WCHAR_H = @NEXT_WCHAR_H@ -NEXT_WCTYPE_H = @NEXT_WCTYPE_H@ -OBJEXT = @OBJEXT@ -PACKAGE = @PACKAGE@ -PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ -PACKAGE_NAME = @PACKAGE_NAME@ -PACKAGE_STRING = @PACKAGE_STRING@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH_SEPARATOR = @PATH_SEPARATOR@ -POSUB = @POSUB@ -PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@ -RANLIB = @RANLIB@ -REPLACE_CHOWN = @REPLACE_CHOWN@ -REPLACE_FCHDIR = @REPLACE_FCHDIR@ -REPLACE_GETCWD = @REPLACE_GETCWD@ -REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@ -REPLACE_GETTIMEOFDAY = @REPLACE_GETTIMEOFDAY@ -REPLACE_LCHOWN = @REPLACE_LCHOWN@ -REPLACE_LSEEK = @REPLACE_LSEEK@ -REPLACE_MEMMEM = @REPLACE_MEMMEM@ -REPLACE_MKSTEMP = @REPLACE_MKSTEMP@ -REPLACE_PUTENV = @REPLACE_PUTENV@ -REPLACE_STRCASESTR = @REPLACE_STRCASESTR@ -REPLACE_STRERROR = @REPLACE_STRERROR@ -REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@ -REPLACE_STRSTR = @REPLACE_STRSTR@ -REPLACE_STRTOD = @REPLACE_STRTOD@ -REPLACE_WCWIDTH = @REPLACE_WCWIDTH@ -SET_MAKE = @SET_MAKE@ -SHELL = @SHELL@ -SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@ -SIZE_T_SUFFIX = @SIZE_T_SUFFIX@ -STDBOOL_H = @STDBOOL_H@ -STDINT_H = @STDINT_H@ -STRIP = @STRIP@ -SYS_STAT_H = @SYS_STAT_H@ -SYS_TIME_H = @SYS_TIME_H@ -TERMLIBS = @TERMLIBS@ -TEX = @TEX@ -USE_NLS = @USE_NLS@ -VERSION = @VERSION@ -VOID_UNSETENV = @VOID_UNSETENV@ -WCHAR_H = @WCHAR_H@ -WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@ -WCTYPE_H = @WCTYPE_H@ -WINT_T_SUFFIX = @WINT_T_SUFFIX@ -XGETTEXT = @XGETTEXT@ -XGETTEXT_015 = @XGETTEXT_015@ -XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@ -abs_builddir = @abs_builddir@ -abs_srcdir = @abs_srcdir@ -abs_top_builddir = @abs_top_builddir@ -abs_top_srcdir = @abs_top_srcdir@ -ac_ct_CC = @ac_ct_CC@ -am__include = @am__include@ -am__leading_dot = @am__leading_dot@ -am__quote = @am__quote@ -am__tar = @am__tar@ -am__untar = @am__untar@ -bindir = @bindir@ -build = @build@ -build_alias = @build_alias@ -build_cpu = @build_cpu@ -build_os = @build_os@ -build_vendor = @build_vendor@ -builddir = @builddir@ -datadir = @datadir@ -datarootdir = @datarootdir@ -docdir = @docdir@ -dvidir = @dvidir@ -exec_prefix = @exec_prefix@ -gl_LIBOBJS = @gl_LIBOBJS@ -gl_LTLIBOBJS = @gl_LTLIBOBJS@ -gltests_LIBOBJS = @gltests_LIBOBJS@ -gltests_LTLIBOBJS = @gltests_LTLIBOBJS@ -host = @host@ -host_alias = @host_alias@ -host_cpu = @host_cpu@ -host_os = @host_os@ -host_vendor = @host_vendor@ -htmldir = @htmldir@ -includedir = @includedir@ -infodir = @infodir@ -install_sh = @install_sh@ -libdir = @libdir@ -libexecdir = @libexecdir@ -localedir = @localedir@ -localstatedir = @localstatedir@ -mandir = @mandir@ -mkdir_p = @mkdir_p@ -native_tools = @native_tools@ -oldincludedir = @oldincludedir@ -pdfdir = @pdfdir@ -prefix = @prefix@ -program_transform_name = @program_transform_name@ -psdir = @psdir@ -sbindir = @sbindir@ -sharedstatedir = @sharedstatedir@ -srcdir = @srcdir@ -sysconfdir = @sysconfdir@ -target_alias = @target_alias@ -top_build_prefix = @top_build_prefix@ -top_builddir = @top_builddir@ -top_srcdir = @top_srcdir@ - -# Put texinfo.txi first because that's the most important. -info_TEXINFOS = texinfo.txi info-stnd.texi info.texi -DISTCLEANFILES = texinfo texinfo-* info*.info* -man_MANS = info.1 infokey.1 install-info.1 makeinfo.1 texindex.1 \ - info.5 texinfo.5 texi2dvi.1 texi2pdf.1 pdftexi2dvi.1 - -# We'd also like to use something like this, but Automake calls -# "install-info" directly. -# INSTALL_INFO = $(top_builddir)/$(native_tools)/util/ginstall-info -TXI_XLATE = txi-cs.tex txi-de.tex txi-en.tex txi-es.tex txi-fr.tex \ - txi-it.tex txi-nl.tex txi-nb.tex txi-pl.tex txi-pt.tex \ - txi-ru.tex txi-sr.tex txi-tr.tex txi-uk.tex - - -# Include our texinfo.tex, not Automake's. -EXTRA_DIST = epsf.tex texinfo.tex \ - fdl.texi \ - $(man_MANS) $(TXI_XLATE) - -texmf_texinfo = $(TEXMF)/tex/texinfo -texmf_dvips = $(TEXMF)/tex/generic/epsf - -# The man pages depend on the --help strings and the version number. -common_mandeps = $(top_srcdir)/configure.ac - -# Set up the variables: -man_rule_0 = \ - program=`expr '/$@' : '.*/\(.*\)\.1'` && \ - case $$program in makeinfo) dir=makeinfo;; info*) dir=info;; \ - *install-info) dir=install-info;; *) dir=util;; esac && \ - dir="$(top_builddir)/$(native_tools)/$$dir" && \ - case $$program in info|install-info) program=g$$program;; \ - esac - - -# Update the manpage for a binary program; set up the variables, -# make sure the binary is up-to-date and then generate the man page. -man_rule_bin = echo "Updating man page $@" && \ - $(man_rule_0) && \ - echo cd "$$dir" '&&' $(MAKE) $(AM_MAKEFLAGS) $$program$(EXEEXT) && \ - (cd "$$dir" && $(MAKE) $(AM_MAKEFLAGS) $$program$(EXEEXT)) && \ - echo $(HELP2MAN) --name=\""$$name"\" "$$dir/$$program" -o '$@' && \ - $(HELP2MAN) --name="$$name" "$$dir/$$program" -o '$@' - -util_srcdir = $(top_srcdir)/util -# Do not depend on the current user's settings. -unset_envvars = unset TEXI2DVI_BUILD_MODE; unset TEXI2DVI_BUILD_DIRECTORY -common_texi2dvi_deps = $(common_mandeps) \ - $(util_srcdir)/texi2dvi $(util_srcdir)/texi2pdf - -all: all-am - -.SUFFIXES: -.SUFFIXES: .dvi .ps -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) - @for dep in $?; do \ - case '$(am__configure_deps)' in \ - *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ - exit 1;; \ - esac; \ - done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --gnu doc/Makefile -.PRECIOUS: Makefile -Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status - @case '$?' in \ - *config.status*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ - *) \ - echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ - cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ - esac; - -$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh -$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -texinfo: texinfo.txi $(srcdir)/version.texi - restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - rm -rf $$backupdir && mkdir $$backupdir && \ - if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ - for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ - if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ - done; \ - else :; fi && \ - if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ `test -f 'texinfo.txi' || echo '$(srcdir)/'`texinfo.txi; \ - then \ - rc=0; \ - else \ - rc=$$?; \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; exit $$rc - -texinfo.dvi: texinfo.txi $(srcdir)/version.texi - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) -o $@ `test -f 'texinfo.txi' || echo '$(srcdir)/'`texinfo.txi - -texinfo.pdf: texinfo.txi $(srcdir)/version.texi - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) -o $@ `test -f 'texinfo.txi' || echo '$(srcdir)/'`texinfo.txi - -texinfo.html: texinfo.txi $(srcdir)/version.texi - rm -rf $(@:.html=.htp) - if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $(@:.html=.htp) `test -f 'texinfo.txi' || echo '$(srcdir)/'`texinfo.txi; \ - then \ - rm -rf $@; \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ - else \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ - exit 1; \ - fi -$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti -$(srcdir)/stamp-vti: texinfo.txi $(top_srcdir)/configure - @(dir=.; test -f ./texinfo.txi || dir=$(srcdir); \ - set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/texinfo.txi`; \ - echo "@set UPDATED $$1 $$2 $$3"; \ - echo "@set UPDATED-MONTH $$2 $$3"; \ - echo "@set EDITION $(VERSION)"; \ - echo "@set VERSION $(VERSION)") > vti.tmp - @cmp -s vti.tmp $(srcdir)/version.texi \ - || (echo "Updating $(srcdir)/version.texi"; \ - cp vti.tmp $(srcdir)/version.texi) - -@rm -f vti.tmp - @cp $(srcdir)/version.texi $@ - -mostlyclean-vti: - -rm -f vti.tmp - -maintainer-clean-vti: -@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi - -info-stnd.info: info-stnd.texi $(srcdir)/version-stnd.texi - restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - rm -rf $$backupdir && mkdir $$backupdir && \ - if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ - for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ - if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ - done; \ - else :; fi && \ - if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi; \ - then \ - rc=0; \ - else \ - rc=$$?; \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; exit $$rc - -info-stnd.dvi: info-stnd.texi $(srcdir)/version-stnd.texi - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) -o $@ `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi - -info-stnd.pdf: info-stnd.texi $(srcdir)/version-stnd.texi - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) -o $@ `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi - -info-stnd.html: info-stnd.texi $(srcdir)/version-stnd.texi - rm -rf $(@:.html=.htp) - if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $(@:.html=.htp) `test -f 'info-stnd.texi' || echo '$(srcdir)/'`info-stnd.texi; \ - then \ - rm -rf $@; \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ - else \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ - exit 1; \ - fi -$(srcdir)/version-stnd.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-1 -$(srcdir)/stamp-1: info-stnd.texi $(top_srcdir)/configure - @(dir=.; test -f ./info-stnd.texi || dir=$(srcdir); \ - set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/info-stnd.texi`; \ - echo "@set UPDATED $$1 $$2 $$3"; \ - echo "@set UPDATED-MONTH $$2 $$3"; \ - echo "@set EDITION $(VERSION)"; \ - echo "@set VERSION $(VERSION)") > 1.tmp - @cmp -s 1.tmp $(srcdir)/version-stnd.texi \ - || (echo "Updating $(srcdir)/version-stnd.texi"; \ - cp 1.tmp $(srcdir)/version-stnd.texi) - -@rm -f 1.tmp - @cp $(srcdir)/version-stnd.texi $@ - -mostlyclean-1: - -rm -f 1.tmp - -maintainer-clean-1: -@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-1 $(srcdir)/version-stnd.texi - -info.info: info.texi $(info_TEXINFOS) - restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - rm -rf $$backupdir && mkdir $$backupdir && \ - if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ - for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ - if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ - done; \ - else :; fi && \ - if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ `test -f 'info.texi' || echo '$(srcdir)/'`info.texi; \ - then \ - rc=0; \ - else \ - rc=$$?; \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; exit $$rc - -info.dvi: info.texi $(info_TEXINFOS) - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) -o $@ `test -f 'info.texi' || echo '$(srcdir)/'`info.texi - -info.pdf: info.texi $(info_TEXINFOS) - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) -o $@ `test -f 'info.texi' || echo '$(srcdir)/'`info.texi - -info.html: info.texi $(info_TEXINFOS) - rm -rf $(@:.html=.htp) - if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $(@:.html=.htp) `test -f 'info.texi' || echo '$(srcdir)/'`info.texi; \ - then \ - rm -rf $@; \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ - else \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ - exit 1; \ - fi -.dvi.ps: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - $(DVIPS) -o $@ $< - -uninstall-dvi-am: - @$(NORMAL_UNINSTALL) - @list='$(DVIS)'; for p in $$list; do \ - f=$(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ - rm -f "$(DESTDIR)$(dvidir)/$$f"; \ - done - -uninstall-html-am: - @$(NORMAL_UNINSTALL) - @list='$(HTMLS)'; for p in $$list; do \ - f=$(am__strip_dir) \ - echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ - rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ - done - -uninstall-info-am: - @$(PRE_UNINSTALL) - @if test -d '$(DESTDIR)$(infodir)' && \ - (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ - install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ - done; \ - else :; fi - @$(NORMAL_UNINSTALL) - @list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ - (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ - echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ - rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ - else :; fi); \ - done - -uninstall-pdf-am: - @$(NORMAL_UNINSTALL) - @list='$(PDFS)'; for p in $$list; do \ - f=$(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ - rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ - done - -uninstall-ps-am: - @$(NORMAL_UNINSTALL) - @list='$(PSS)'; for p in $$list; do \ - f=$(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ - rm -f "$(DESTDIR)$(psdir)/$$f"; \ - done - -mostlyclean-aminfo: - -rm -rf texinfo.aux texinfo.cp texinfo.cps texinfo.fn texinfo.fns texinfo.ky \ - texinfo.kys texinfo.log texinfo.op texinfo.pg texinfo.tmp \ - texinfo.toc texinfo.tp texinfo.tps texinfo.vr texinfo.dvi \ - texinfo.pdf texinfo.ps texinfo.html info-stnd.aux \ - info-stnd.cp info-stnd.cps info-stnd.fn info-stnd.ky \ - info-stnd.log info-stnd.pg info-stnd.pgs info-stnd.tmp \ - info-stnd.toc info-stnd.tp info-stnd.tps info-stnd.vr \ - info-stnd.dvi info-stnd.pdf info-stnd.ps info-stnd.html \ - info.aux info.cp info.cps info.fn info.ky info.log info.pg \ - info.pgs info.tmp info.toc info.tp info.tps info.vr info.dvi \ - info.pdf info.ps info.html - -maintainer-clean-aminfo: - @list='$(INFO_DEPS)'; for i in $$list; do \ - i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ - echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ - rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ - done -install-man1: $(man1_MANS) $(man_MANS) - @$(NORMAL_INSTALL) - test -z "$(man1dir)" || $(MKDIR_P) "$(DESTDIR)$(man1dir)" - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ - else file=$$i; fi; \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ - done -uninstall-man1: - @$(NORMAL_UNINSTALL) - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ - done -install-man5: $(man5_MANS) $(man_MANS) - @$(NORMAL_INSTALL) - test -z "$(man5dir)" || $(MKDIR_P) "$(DESTDIR)$(man5dir)" - @list='$(man5_MANS) $(dist_man5_MANS) $(nodist_man5_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.5*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ - else file=$$i; fi; \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 5*) ;; \ - *) ext='5' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man5dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man5dir)/$$inst"; \ - done -uninstall-man5: - @$(NORMAL_UNINSTALL) - @list='$(man5_MANS) $(dist_man5_MANS) $(nodist_man5_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.5*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 5*) ;; \ - *) ext='5' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " rm -f '$(DESTDIR)$(man5dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man5dir)/$$inst"; \ - done -tags: TAGS -TAGS: - -ctags: CTAGS -CTAGS: - - -distdir: $(DISTFILES) - @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ - topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ - list='$(DISTFILES)'; \ - dist_files=`for file in $$list; do echo $$file; done | \ - sed -e "s|^$$srcdirstrip/||;t" \ - -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ - case $$dist_files in \ - */*) $(MKDIR_P) `echo "$$dist_files" | \ - sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ - sort -u` ;; \ - esac; \ - for file in $$dist_files; do \ - if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ - if test -d $$d/$$file; then \ - dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ - if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ - fi; \ - cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ - else \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file \ - || exit 1; \ - fi; \ - done - $(MAKE) $(AM_MAKEFLAGS) \ - top_distdir="$(top_distdir)" distdir="$(distdir)" \ - dist-info -check-am: all-am -check: check-am -all-am: Makefile $(INFO_DEPS) $(MANS) -installdirs: - for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man5dir)"; do \ - test -z "$$dir" || $(MKDIR_P) "$$dir"; \ - done -install: install-am -install-exec: install-exec-am -install-data: install-data-am -uninstall: uninstall-am - -install-am: all-am - @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am - -installcheck: installcheck-am -install-strip: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install -mostlyclean-generic: - -clean-generic: - -distclean-generic: - -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) - -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES) - -maintainer-clean-generic: - @echo "This command is intended for maintainers to use" - @echo "it deletes files that may require special tools to rebuild." -@INSTALL_WARNINGS_FALSE@install-data-local: -clean: clean-am - -clean-am: clean-generic mostlyclean-am - -distclean: distclean-am - -rm -f Makefile -distclean-am: clean-am distclean-generic - -dvi: dvi-am - -dvi-am: $(DVIS) - -html: html-am - -html-am: $(HTMLS) - -info: info-am - -info-am: $(INFO_DEPS) - -install-data-am: install-data-local install-info-am install-man - -install-dvi: install-dvi-am - -install-dvi-am: $(DVIS) - @$(NORMAL_INSTALL) - test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" - @list='$(DVIS)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ - done -install-exec-am: - -install-html: install-html-am - -install-html-am: $(HTMLS) - @$(NORMAL_INSTALL) - test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" - @list='$(HTMLS)'; for p in $$list; do \ - if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - if test -d "$$d$$p"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ - $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ - echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ - else \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ - fi; \ - done -install-info: install-info-am - -install-info-am: $(INFO_DEPS) - @$(NORMAL_INSTALL) - test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ - file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ - for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ - $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ - if test -f $$ifile; then \ - relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ - echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ - $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ - else : ; fi; \ - done; \ - done - @$(POST_INSTALL) - @if (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ - install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ - done; \ - else : ; fi -install-man: install-man1 install-man5 - -install-pdf: install-pdf-am - -install-pdf-am: $(PDFS) - @$(NORMAL_INSTALL) - test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" - @list='$(PDFS)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ - done -install-ps: install-ps-am - -install-ps-am: $(PSS) - @$(NORMAL_INSTALL) - test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" - @list='$(PSS)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ - done -installcheck-am: - -maintainer-clean: maintainer-clean-am - -rm -f Makefile -maintainer-clean-am: distclean-am maintainer-clean-1 \ - maintainer-clean-aminfo maintainer-clean-generic \ - maintainer-clean-vti - -mostlyclean: mostlyclean-am - -mostlyclean-am: mostlyclean-1 mostlyclean-aminfo mostlyclean-generic \ - mostlyclean-vti - -pdf: pdf-am - -pdf-am: $(PDFS) - -ps: ps-am - -ps-am: $(PSS) - -uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ - uninstall-man uninstall-pdf-am uninstall-ps-am - -uninstall-man: uninstall-man1 uninstall-man5 - -.MAKE: install-am install-strip - -.PHONY: all all-am check check-am clean clean-generic dist-info \ - distclean distclean-generic distdir dvi dvi-am html html-am \ - info info-am install install-am install-data install-data-am \ - install-data-local install-dvi install-dvi-am install-exec \ - install-exec-am install-html install-html-am install-info \ - install-info-am install-man install-man1 install-man5 \ - install-pdf install-pdf-am install-ps install-ps-am \ - install-strip installcheck installcheck-am installdirs \ - maintainer-clean maintainer-clean-1 maintainer-clean-aminfo \ - maintainer-clean-generic maintainer-clean-vti mostlyclean \ - mostlyclean-1 mostlyclean-aminfo mostlyclean-generic \ - mostlyclean-vti pdf pdf-am ps ps-am uninstall uninstall-am \ - uninstall-dvi-am uninstall-html-am uninstall-info-am \ - uninstall-man uninstall-man1 uninstall-man5 uninstall-pdf-am \ - uninstall-ps-am - - -@INSTALL_WARNINGS_TRUE@install-data-local: -@INSTALL_WARNINGS_TRUE@ @echo -@INSTALL_WARNINGS_TRUE@ @echo "WARNING: If your texmf tree does not already contain" -@INSTALL_WARNINGS_TRUE@ @echo " up-to-date versions, you must install" -@INSTALL_WARNINGS_TRUE@ @echo " texinfo.tex and txi-??.tex manually," -@INSTALL_WARNINGS_TRUE@ @echo " perhaps in TEXMF/tex/texinfo/," -@INSTALL_WARNINGS_TRUE@ @echo " where TEXMF is a root of your TeX tree." -@INSTALL_WARNINGS_TRUE@ @echo " See doc/README for some considerations." -@INSTALL_WARNINGS_TRUE@ @echo " You can run make TEXMF=/your/texmf install-tex to do this." -@INSTALL_WARNINGS_TRUE@ @echo -@INSTALL_WARNINGS_TRUE@ @echo " You may also need to install epsf.tex in" -@INSTALL_WARNINGS_TRUE@ @echo " TEXMF/tex/generic/dvips, if your TeX" -@INSTALL_WARNINGS_TRUE@ @echo " installation did not include it." -install-tex: - test -n "$(TEXMF)" || (echo "TEXMF must be set." >&2; exit 1) - $(mkinstalldirs) $(DESTDIR)$(texmf_texinfo) $(DESTDIR)$(texmf_dvips) - $(INSTALL_DATA) $(srcdir)/texinfo.tex $(DESTDIR)$(texmf_texinfo)/texinfo.tex - $(INSTALL_DATA) $(srcdir)/epsf.tex $(DESTDIR)$(texmf_dvips)/epsf.tex - for f in $(TXI_XLATE); do \ - $(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(texmf_texinfo)/$$f; done - -$(srcdir)/info.1: $(top_srcdir)/info/info.c $(common_mandeps) - @name="read Info documents" && $(man_rule_bin) -$(srcdir)/infokey.1: $(top_srcdir)/info/infokey.c $(common_mandeps) - @name="compile customizations for Info" && $(man_rule_bin) -$(srcdir)/install-info.1: $(top_srcdir)/install-info/install-info.c $(common_mandeps) - @name="update info/dir entries" && $(man_rule_bin) - -# Here we need some postprocessing: -$(srcdir)/makeinfo.1: $(top_srcdir)/makeinfo/makeinfo.c $(common_mandeps) - @name="translate Texinfo documents" && $(man_rule_bin) - mv $@ $@.tmp - sed '/^\.IP$$/N;/\nAlso/s/I//;/\nThe/s/I//' $@.tmp >$@ - rm $@.tmp - -$(srcdir)/texindex.1: $(util_srcdir)/texindex.c $(common_mandeps) - @name="sort Texinfo index files" && $(man_rule_bin) - -$(srcdir)/texi2dvi.1: $(common_texi2dvi_deps) - $(unset_envvars); $(HELP2MAN) --name="convert Texinfo documents to DVI" $(util_srcdir)/texi2dvi >$@ - -$(srcdir)/texi2pdf.1: $(common_texi2dvi_deps) - $(unset_envvars); $(HELP2MAN) --name="convert Texinfo documents to PDF" $(util_srcdir)/texi2pdf >$@ - -$(srcdir)/pdftexi2dvi.1: $(common_texi2dvi_deps) - $(unset_envvars); $(HELP2MAN) --name="convert Texinfo documents to PDF" $(util_srcdir)/pdftexi2dvi >$@ - -# Do not create info files for distribution. -dist-info: -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/Build/source/utils/texinfo/doc/README b/Build/source/utils/texinfo/doc/README deleted file mode 100644 index 1b64f637e47..00000000000 --- a/Build/source/utils/texinfo/doc/README +++ /dev/null @@ -1,44 +0,0 @@ -$Id: README,v 1.5 2007/07/02 21:40:32 olegkat Exp $ -texinfo/doc/README - - Copyright (C) 2002 Free Software Foundation, Inc. - - Copying and distribution of this file, with or without modification, - are permitted in any medium without royalty provided the copyright - notice and this notice are preserved. - -This directory contains documentation on the Texinfo system and the TeX -sources needed to process Texinfo sources. We recommend using the -texi2dvi included in this distribution to run a Texinfo manual through -TeX to produce a DVI file. - -The .tex files are not installed automatically because TeX installations -vary so widely. Installing them in the wrong place would give a false -sense of security. So, you should simply cp *.tex to the appropriate -place. If your installation follows the TeX Directory Structure -standard (http://tug.org/tds/), this will be the directory -TEXMF/tex/texinfo/ for texinfo.tex, and TEXMF/tex/generic/dvips/ for -epsf.tex. If you use the default installation paths, TEXMF will be -/usr/local/share/texmf. On systems with TeX preinstalled, as most -GNU/Linux distributions offer, TEXMF will often be something like -/usr/share/texmf. - -It is also possible to put these .tex files in a `local' place instead -of overwriting existing ones, but this is more complicated. See your TeX -documentation in general and the texmf.cnf file in particular for information. - -If you add files to your TeX installations, not just replace existing -ones, you very likely have to update your ls-R file; do this with the -mktexlsr command. In older versions, this was named MakeTeXls-R. - -You can get the latest texinfo.tex from -ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex (and all GNU mirrors) -ftp://tug.org/tex/texinfo.tex (and all CTAN mirrors) -or on the FSF machines in /home/gd/gnu/doc/texinfo.tex. -If you have problems with the version in this distribution, please check -for a newer version. - -epsf.tex comes with dvips distributions, and you may already have it -installed. The version here is functionally identical but slightly -nicer than the one in dvips574. The changes have been sent to the -epsf.tex maintainer. diff --git a/Build/source/utils/texinfo/doc/epsf.tex b/Build/source/utils/texinfo/doc/epsf.tex deleted file mode 100644 index 00b12c81738..00000000000 --- a/Build/source/utils/texinfo/doc/epsf.tex +++ /dev/null @@ -1,644 +0,0 @@ -%%% -*-TeX-*- -%%% ==================================================================== -%%% @TeX-file{ -%%% author = "Tom Rokicki", -%%% version = "2.7.3", -%%% date = "23 July 2005", -%%% time = "14:32:01 MDT", -%%% filename = "epsf.tex", -%%% address = "Tom Rokicki -%%% Box 2081 -%%% Stanford, CA 94309 -%%% USA", -%%% telephone = "+1 415 855 9989", -%%% checksum = "20914 644 3054 26594", -%%% email = "rokicki@cs.stanford.edu (Internet)", -%%% codetable = "ISO/ASCII", -%%% copyright = "This file is freely redistributable and -%%% placed into the public domain by Tomas -%%% Rokicki.", -%%% keywords = "PostScript, TeX", -%%% supported = "yes", -%%% abstract = "This file contains macros to support the -%%% inclusion of Encapsulated PostScript files -%%% in TeX documents.", -%%% docstring = "This file contains TeX macros to include an -%%% Encapsulated PostScript graphic. It works -%%% by finding the bounding box comment, -%%% calculating the correct scale values, and -%%% inserting a vbox of the appropriate size at -%%% the current position in the TeX document. -%%% -%%% To use, simply use -%%% -%%% \input epsf % somewhere early on in your TeX file -%%% -%%% % then where you want to insert a vbox for a figure: -%%% \epsfbox{filename.ps} -%%% -%%% Alternatively, you can supply your own -%%% bounding box by -%%% -%%% \epsfbox[0 0 30 50]{filename.ps} -%%% -%%% This will not read in the file, and will -%%% instead use the bounding box you specify. -%%% -%%% The effect will be to typeset the figure as -%%% a TeX box, at the point of your \epsfbox -%%% command. By default, the graphic will have -%%% its `natural' width (namely the width of -%%% its bounding box, as described in -%%% filename.ps). The TeX box will have depth -%%% zero. -%%% -%%% You can enlarge or reduce the figure by -%%% using -%%% -%%% \epsfxsize = <dimen> \epsfbox{filename.ps} -%%% or -%%% \epsfysize = <dimen> \epsfbox{filename.ps} -%%% -%%% instead. Then the width of the TeX box will -%%% be \epsfxsize and its height will be scaled -%%% proportionately (or the height will be -%%% \epsfysize and its width will be scaled -%%% proportionately). -%%% -%%% The width (and height) is restored to zero -%%% after each use, so \epsfxsize or \epsfysize -%%% must be specified before EACH use of -%%% \epsfbox. -%%% -%%% A more general facility for sizing is -%%% available by defining the \epsfsize macro. -%%% Normally you can redefine this macro to do -%%% almost anything. The first parameter is -%%% the natural x size of the PostScript -%%% graphic, the second parameter is the -%%% natural y size of the PostScript graphic. -%%% It must return the xsize to use, or 0 if -%%% natural scaling is to be used. Common uses -%%% include: -%%% -%%% \epsfxsize % just leave the old value alone -%%% 0pt % use the natural sizes -%%% #1 % use the natural sizes -%%% \hsize % scale to full width -%%% 0.5#1 % scale to 50% of natural size -%%% \ifnum #1 > \hsize \hsize \else #1\fi -%%% % smaller of natural, hsize -%%% -%%% If you want TeX to report the size of the -%%% figure (as a message on your terminal when -%%% it processes each figure), use -%%% `\epsfverbosetrue'. -%%% -%%% If you only want to get the bounding box -%%% extents, without producing any output boxes -%%% or \special{}, then use \epsfgetbb{filename}. -%%% The bounding box corner coordinates are saved -%%% in the macros \epsfllx, \epsflly, \epsfurx, -%%% and \epsfury in PostScript units of big -%%% points. -%%% -%%% Revision history: -%%% -%%% --------------------------------------------- -%%% epsf.tex macro file: -%%% Originally written by Tomas Rokicki of -%%% Radical Eye Software, 29 Mar 1989. -%%% -%%% --------------------------------------------- -%%% Revised by Don Knuth, 3 Jan 1990. -%%% -%%% --------------------------------------------- -%%% Revised by Tomas Rokicki, 18 Jul 1990. -%%% Accept bounding boxes with no space after -%%% the colon. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 03 Dec 1991 [2.0]. -%%% Add version number and date typeout. -%%% -%%% Use \immediate\write16 instead of \message -%%% to ensure output on new line. -%%% -%%% Handle nested EPS files. -%%% -%%% Handle %%BoundingBox: (atend) lines. -%%% -%%% Do not quit when blank lines are found. -%%% -%%% Add a few percents to remove generation of -%%% spurious blank space. -%%% -%%% Move \special output to -%%% \epsfspecial{filename} so that other macro -%%% packages can input this one, then change -%%% the definition of \epsfspecial to match -%%% another DVI driver. -%%% -%%% Move size computation to \epsfsetsize which -%%% can be called by the user; the verbose -%%% output of the bounding box and scaled width -%%% and height happens here. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 05 May 1992 [2.1]. -%%% Wrap \leavevmode\hbox{} around \vbox{} with -%%% the \special so that \epsffile{} can be -%%% used inside \begin{center}...\end{center} -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 09 Dec 1992 [2.2]. -%%% Introduce \epsfshow{true,false} and -%%% \epsfframe{true,false} macros; the latter -%%% suppresses the insertion of the PostScript, -%%% and instead just creates an empty box, -%%% which may be handy for rapid prototyping. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 14 Dec 1992 [2.3]. -%%% Add \epsfshowfilename{true,false}. When -%%% true, and \epsfshowfalse is specified, the -%%% PostScript file name will be displayed -%%% centered in the figure box. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 20 June 1993 [2.4]. -%%% Remove non-zero debug setting of \epsfframemargin, -%%% and change margin handling to preserve EPS image -%%% size and aspect ratio, so that the actual -%%% box is \epsfxsize+\epsfframemargin wide by -%%% \epsfysize+\epsfframemargin high. -%%% Reduce output of \epsfshowfilenametrue to -%%% just the bare file name. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 13 July 1993 [2.5]. -%%% Add \epsfframethickness for control of -%%% \epsfframe frame lines. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 02 July 1996 [2.6] -%%% Add missing initialization \epsfatendfalse; -%%% the lack of this resulted in the wrong -%%% BoundingBox being picked up, mea culpa, sigh... -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 25 October 1996 [2.7] -%%% Update to match changes in from dvips 5-600 -%%% distribution: new user-accessible macros: -%%% \epsfclipon, \epsfclipoff, \epsfdrafton, -%%% \epsfdraftoff, change \empty to \epsfempty. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 18 May 2002 [2.7.1] -%%% Add write statements to echo input file -%%% names. Prior to that change, an error in -%%% such a file could be quite hard to track -%%% down: a long list of TeX page numbers could -%%% suddenly be followed by ``TeX buffer -%%% capacity'' exceeded, without any indication -%%% of the file that was responsible. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, 16 May 2003 [2.7.2] -%%% Supply two critical percent characters that -%%% were mistakenly omitted in version 2.7.1, -%%% and resulted in a small amount of spurious -%%% horizontal space. -%%% -%%% --------------------------------------------- -%%% Revised by Nelson H. F. Beebe -%%% <beebe@math.utah.edu>, Karl Berry -%%% <karl@freefriends.org>, and Robin Fairbairns -%%% <Robin.Fairbairns@cl.cam.ac.uk>, -%%% 23 July 2005 [2.7.3] -%%% Add critical \hbox{} wrapper in \epsfsetgraph -%%% so that \epsfbox{} does not conflict with -%%% LaTeX center environment when \epsfbox{} is -%%% surrounded by other horizonal objects. -%%% Improve macro readability by adding legal, -%%% but invisible-in-typeset-output, spaces. -%%% Ensure that verbose status reports come -%%% inside (filename ...) list. -%%% -%%% --------------------------------------------- -%%% The checksum field above contains a CRC-16 -%%% checksum as the first value, followed by -%%% the equivalent of the standard UNIX wc -%%% (word count) utility output of lines, -%%% words, and characters. This is produced by -%%% Robert Solovay's checksum utility.", -%%% } -%%% ==================================================================== - -%\immediate \write16 {This is `epsf.tex' v2.0 <02 Dec 1991>}% -%\immediate \write16 {This is `epsf.tex' v2.1 <05 May 1992>}% -%\immediate \write16 {This is `epsf.tex' v2.2 <09 Dec 1992>}% -%\immediate \write16 {This is `epsf.tex' v2.3 <14 Dec 1992>}% -%\immediate \write16 {This is `epsf.tex' v2.4 <20 June 1993>}% -%\immediate \write16 {This is `epsf.tex' v2.5 <13 July 1993>}% -%\immediate \write16 {This is `epsf.tex' v2.6 <02 July 1996>}% -%\immediate \write16 {This is `epsf.tex' v2.7 <25 October 1996>}% -%\immediate \write16 {This is `epsf.tex' v2.7.1 <18 May 2002>}% -%\immediate \write16 {This is `epsf.tex' v2.7.2 <16 May 2003>}% -\immediate \write16 {This is `epsf.tex' v2.7.3 <23 July 2005>}% -% -\newread \epsffilein % file to \read -\newif \ifepsfatend % need to scan to LAST %%BoundingBox comment? -\newif \ifepsfbbfound % success? -\newif \ifepsfdraft % use draft mode? -\newif \ifepsffileok % continue looking for the bounding box? -\newif \ifepsfframe % frame the bounding box? -\newif \ifepsfshow % show PostScript file, or just bounding box? -\epsfshowtrue % default is to display PostScript file -\newif \ifepsfshowfilename % show the file name if \epsfshowfalse specified? -\newif \ifepsfverbose % report what you're making? -\newdimen \epsfframemargin % margin between box and frame -\newdimen \epsfframethickness % thickness of frame rules -\newdimen \epsfrsize % vertical size before scaling -\newdimen \epsftmp % register for arithmetic manipulation -\newdimen \epsftsize % horizontal size before scaling -\newdimen \epsfxsize % horizontal size after scaling -\newdimen \epsfysize % vertical size after scaling -\newdimen \pspoints % conversion factor -% -\pspoints = 1bp % Adobe points are `big' -\epsfxsize = 0pt % default value, means `use natural size' -\epsfysize = 0pt % ditto -\epsfframemargin = 0pt % default value: frame box flush around picture -\epsfframethickness = 0.4pt % TeX's default rule thickness -% -\def \epsfbox #1{% - \global \def \epsfllx {72}% - \global \def \epsflly {72}% - \global \def \epsfurx {540}% - \global \def \epsfury {720}% - \def \lbracket {[}% - \def \testit {#1}% - \ifx \testit \lbracket - \let \next = \epsfgetlitbb - \else - \let \next = \epsfnormal - \fi - \next{#1}% -}% -% -% We use \epsfgetlitbb if the user specified an explicit bounding box, -% and \epsfnormal otherwise. Because \epsfgetbb can be called -% separately to retrieve the bounding box, we move the verbose -% printing the bounding box extents and size on the terminal to -% \epsfstatus. Therefore, when the user provided the bounding box, -% \epsfgetbb will not be called, so we must call \epsfsetsize and -% \epsfstatus ourselves. -% -\def \epsfgetlitbb #1#2 #3 #4 #5]#6{% - \epsfgrab #2 #3 #4 #5 .\\% - \epsfsetsize - \epsfstatus{#6}% - \epsfsetgraph{#6}% -}% -% -\def \epsfnormal #1{% - \epsfgetbb{#1}% - \epsfsetgraph{#1}% -}% -% -\def \epsfgetbb #1{% -% -% The first thing we need to do is to open the -% PostScript file, if possible. -% - \openin\epsffilein=#1 - \immediate \write16 {(#1}% - \ifeof \epsffilein - \errmessage{Could not open file #1, ignoring it}% - \else %process the file - {% %start a group to contain catcode changes - % Make all special characters, except space, to be of type - % `other' so we process the file in almost verbatim mode - % (TeXbook, p. 344). - \chardef \other = 12% - \def \do ##1{\catcode`##1=\other}% - \dospecials - \catcode `\ = 10% - \epsffileoktrue %true while we are looping - \epsfatendfalse %[02-Jul-1996]: add forgotten initialization - \loop %reading lines from the EPS file - \read \epsffilein to \epsffileline - \ifeof \epsffilein %then no more input - \epsffileokfalse %so set completion flag - \else %otherwise process one line - \expandafter \epsfaux \epsffileline :. \\% - \fi - \ifepsffileok - \repeat - \ifepsfbbfound - \else - \ifepsfverbose - \immediate \write16 {No BoundingBox comment found in % - file #1; using defaults}% - \fi - \fi - }% %end catcode changes - \closein\epsffilein - \fi %end of file processing - \epsfsetsize %compute size parameters - \epsfstatus{#1}% - \immediate \write16 {)}% -}% -% -% Clipping control: -\def \epsfclipon {\def \epsfclipstring { clip}}% -\def \epsfclipoff {\def \epsfclipstring {\ifepsfdraft \space clip\fi}}% -\epsfclipoff % default for dvips is OFF -% -% The special that is emitted by \epsfsetgraph comes from this macro. -% It is defined separately to allow easy customization by other -% packages that first \input epsf.tex, then redefine \epsfspecial. -% This macro is invoked in the lower-left corner of a box of the -% width and height determined from the arguments to \epsffile, or -% from the %%BoundingBox in the EPS file itself. -% -% This version is for dvips: -\def \epsfspecial #1{% - \epsftmp=10\epsfxsize - \divide \epsftmp by \pspoints - \ifnum \epsfrsize = 0% - \relax - \special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space - llx=\epsfllx\space - lly=\epsflly\space - urx=\epsfurx\space - ury=\epsfury\space - rwi=\number\epsftmp - \epsfclipstring - }% - \else - \epsfrsize=10\epsfysize - \divide \epsfrsize by \pspoints - \special{PSfile=\ifepsfdraft psdraft.ps\else#1\fi\space - llx=\epsfllx\space - lly=\epsflly\space - urx=\epsfurx\space - ury=\epsfury\space - rwi=\number\epsftmp - rhi=\number\epsfrsize - \epsfclipstring - }% - \fi -}% -% -% \epsfframe macro adapted from the TeXbook, exercise 21.3, p. 223, 331. -% but modified to set the box width to the natural width, rather -% than the line width, and to include space for margins and rules -\def \epsfframe #1% -{% - % method for detecting latex suggested by Robin Fairbairns, May 2005. - \ifx \documentstyle \epsfundefined - \relax - \else -% \leavevmode % so we can put this inside - % a latex centered environment - % The \leavevmode breaks under plain when this is inside a box, - % because it forces the figure to be the entire \hsize. On the - % other hand, we need the \leavevmode for it to work in LaTeX, - % because the {center} environment works by adjusting TeX's - % paragraph parameters. - % - % Compare the LaTeX sequence - % \begin{center} - % \epsfbox{tip.eps}q - % \end{center} - % (needs the \leavevmode to put the q right next to the image) - % - % with the plain TeX sequence: - % \leftline{\vbox{\epsfbox{tip.eps}}q} - % (had the q all the way over to the right, when \leavevmode was used) - \fi - % - \setbox0 = \hbox{#1}% - \dimen0 = \wd0 % natural width of argument - \advance \dimen0 by 2\epsfframemargin % plus width of 2 margins - \advance \dimen0 by 2\epsfframethickness % plus width of 2 rule lines - \relax - \hbox{% - \vbox - {% - \hrule height \epsfframethickness depth 0pt - \hbox to \dimen0 - {% - \hss - \vrule width \epsfframethickness - \kern \epsfframemargin - \vbox {\kern \epsfframemargin \box0 \kern \epsfframemargin }% - \kern \epsfframemargin - \vrule width \epsfframethickness - \hss - }% end hbox - \hrule height 0pt depth \epsfframethickness - }% end vbox - }% end hbox - \relax -}% -% -\def \epsfsetgraph #1% -{% - % - % Make the vbox and stick in a \special that the DVI driver can - % parse. \vfil and \hfil are used to place the \special origin at - % the lower-left corner of the vbox. \epsfspecial can be redefined - % to produce alternate \special syntaxes. - % - \ifvmode \leavevmode \fi - \relax - \hbox{% so we can put this in \begin{center}...\end{center} - \ifepsfframe \expandafter \epsfframe \fi - {\vbox to\epsfysize - {% - \ifepsfshow - % output \special{} at lower-left corner of figure box - \vfil - \hbox to \epsfxsize{\epsfspecial{#1}\hfil}% - \else - \vfil - \hbox to\epsfxsize{% - \hss - \ifepsfshowfilename - {% - \epsfframemargin=3pt % local change of margin - \epsfframe{{\tt #1}}% - }% - \fi - \hss - }% - \vfil - \fi - }% - }}% - \relax - % - % Reset \epsfxsize and \epsfysize, as documented above. - % - \global \epsfxsize = 0pt - \global \epsfysize = 0pt -}% -% -% Now we have to calculate the scale and offset values to use. -% First we compute the natural sizes. -% -\def \epsfsetsize -{% - \epsfrsize = \epsfury \pspoints - \advance \epsfrsize by -\epsflly \pspoints - \epsftsize = \epsfurx \pspoints - \advance \epsftsize by -\epsfllx \pspoints -% -% If `epsfxsize' is 0, we default to the natural size of the picture. -% Otherwise we scale the graph to be \epsfxsize wide. -% - \epsfxsize = \epsfsize{\epsftsize}{\epsfrsize}% - \ifnum \epsfxsize = 0 - \ifnum \epsfysize = 0 - \epsfxsize = \epsftsize - \epsfysize = \epsfrsize - \epsfrsize = 0pt -% -% We have a sticky problem here: TeX doesn't do floating point arithmetic! -% Our goal is to compute y = rx/t. The following loop does this reasonably -% fast, with an error of at most about 16 sp (about 1/4000 pt). -% - \else - \epsftmp = \epsftsize - \divide \epsftmp by \epsfrsize - \epsfxsize = \epsfysize - \multiply \epsfxsize by \epsftmp - \multiply \epsftmp by \epsfrsize - \advance \epsftsize by -\epsftmp - \epsftmp = \epsfysize - \loop - \advance \epsftsize by \epsftsize - \divide \epsftmp by 2 - \ifnum \epsftmp > 0 - \ifnum \epsftsize < \epsfrsize - \else - \advance \epsftsize -\epsfrsize - \advance \epsfxsize \epsftmp - \fi - \repeat - \epsfrsize = 0pt - \fi - \else - \ifnum \epsfysize = 0 - \epsftmp = \epsfrsize - \divide \epsftmp by \epsftsize - \epsfysize = \epsfxsize - \multiply \epsfysize by \epsftmp - \multiply \epsftmp by \epsftsize - \advance \epsfrsize by -\epsftmp - \epsftmp = \epsfxsize - \loop - \advance \epsfrsize by \epsfrsize - \divide \epsftmp by 2 - \ifnum \epsftmp > 0 - \ifnum \epsfrsize < \epsftsize - \else - \advance \epsfrsize by -\epsftsize - \advance \epsfysize by \epsftmp - \fi - \repeat - \epsfrsize = 0pt - \else - \epsfrsize = \epsfysize - \fi - \fi -}% -% -% Issue some status messages if the user requested them -% -\def \epsfstatus #1{% arg = filename - \ifepsfverbose - \immediate \write16 {#1: BoundingBox: - llx = \epsfllx \space lly = \epsflly \space - urx = \epsfurx \space ury = \epsfury \space}% - \immediate \write16 {#1: scaled width = \the\epsfxsize \space - scaled height = \the\epsfysize}% - \fi -}% -% -% We still need to define the tricky \epsfaux macro. This requires -% a couple of magic constants for comparison purposes. -% -{\catcode`\%=12 \global \let \epsfpercent=%\global \def \epsfbblit {%BoundingBox}}% -\global \def \epsfatend{(atend)}% -% -% So we're ready to check for `%BoundingBox:' and to grab the -% values if they are found. -% -% If we find a line -% -% %%BoundingBox: (atend) -% -% then we ignore it, but set a flag to force parsing all of the -% file, so the last %%BoundingBox parsed will be the one used. This -% is necessary, because EPS files can themselves contain other EPS -% files with their own %%BoundingBox comments. -% -% If we find a line -% -% %%BoundingBox: llx lly urx ury -% -% then we save the 4 values in \epsfllx, \epsflly, \epsfurx, \epsfury. -% Then, if we have not previously parsed an (atend), we flag completion -% and can stop reading the file. Otherwise, we must keep on reading -% to end of file so that we find the values on the LAST %%BoundingBox. -\long \def \epsfaux#1#2:#3\\% -{% - \def \testit {#2}% % save second character up to just before colon - \ifx#1\epsfpercent % then first char is percent (quick test) - \ifx \testit \epsfbblit % then (slow test) we have %%BoundingBox - \epsfgrab #3 . . . \\% - \ifx \epsfllx\epsfatend % then ignore %%BoundingBox: (atend) - \global \epsfatendtrue - \else % else found %%BoundingBox: llx lly urx ury - \ifepsfatend % then keep parsing ALL %%BoundingBox lines - \else % else stop after first one parsed - \epsffileokfalse - \fi - \global \epsfbbfoundtrue - \fi - \fi - \fi -}% -% -% Here we grab the values and stuff them in the appropriate definitions. -% -\def \epsfempty {}% -\def \epsfgrab #1 #2 #3 #4 #5\\{% - \global \def \epsfllx {#1}\ifx \epsfllx\epsfempty - \epsfgrab #2 #3 #4 #5 .\\\else - \global \def \epsflly {#2}% - \global \def \epsfurx {#3}\global \def \epsfury {#4}\fi -}% -% -% We default the epsfsize macro. -% -\def \epsfsize #1#2{\epsfxsize}% -% -% Finally, another definition for compatibility with older macros. -% -\let \epsffile = \epsfbox -\endinput diff --git a/Build/source/utils/texinfo/doc/fdl.texi b/Build/source/utils/texinfo/doc/fdl.texi deleted file mode 100644 index 7b93651f1fa..00000000000 --- a/Build/source/utils/texinfo/doc/fdl.texi +++ /dev/null @@ -1,451 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.2, November 2002 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. -51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - diff --git a/Build/source/utils/texinfo/doc/help2man b/Build/source/utils/texinfo/doc/help2man deleted file mode 100755 index ea180b70a89..00000000000 --- a/Build/source/utils/texinfo/doc/help2man +++ /dev/null @@ -1,559 +0,0 @@ -#!/usr/local/bin/perl -w - -# Generate a short man page from --help and --version output. -# Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software -# Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software Foundation, -# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - -# Written by Brendan O'Dea <bod@debian.org> -# Available from ftp://ftp.gnu.org/gnu/help2man/ - -use 5.005; -use strict; -use Getopt::Long; -use Text::Tabs qw(expand); -use POSIX qw(strftime setlocale LC_TIME); - -my $this_program = 'help2man'; -my $this_version = '1.29'; -my $version_info = <<EOT; -GNU $this_program $this_version - -Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. -This is free software; see the source for copying conditions. There is NO -warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - -Written by Brendan O'Dea <bod\@debian.org> -EOT - -my $help_info = <<EOT; -`$this_program' generates a man page out of `--help' and `--version' output. - -Usage: $this_program [OPTION]... EXECUTABLE - - -n, --name=STRING description for the NAME paragraph - -s, --section=SECTION section number for manual page (1, 6, 8) - -m, --manual=TEXT name of manual (User Commands, ...) - -S, --source=TEXT source of program (FSF, Debian, ...) - -i, --include=FILE include material from `FILE' - -I, --opt-include=FILE include material from `FILE' if it exists - -o, --output=FILE send output to `FILE' - -p, --info-page=TEXT name of Texinfo manual - -N, --no-info suppress pointer to Texinfo manual - --help print this help, then exit - --version print version number, then exit - -EXECUTABLE should accept `--help' and `--version' options although -alternatives may be specified using: - - -h, --help-option=STRING help option string - -v, --version-option=STRING version option string - -Report bugs to <bug-help2man\@gnu.org>. -EOT - -my $section = 1; -my $manual = ''; -my $source = ''; -my $help_option = '--help'; -my $version_option = '--version'; -my ($opt_name, @opt_include, $opt_output, $opt_info, $opt_no_info); - -my %opt_def = ( - 'n|name=s' => \$opt_name, - 's|section=s' => \$section, - 'm|manual=s' => \$manual, - 'S|source=s' => \$source, - 'i|include=s' => sub { push @opt_include, [ pop, 1 ] }, - 'I|opt-include=s' => sub { push @opt_include, [ pop, 0 ] }, - 'o|output=s' => \$opt_output, - 'p|info-page=s' => \$opt_info, - 'N|no-info' => \$opt_no_info, - 'h|help-option=s' => \$help_option, - 'v|version-option=s' => \$version_option, -); - -# Parse options. -Getopt::Long::config('bundling'); -GetOptions (%opt_def, - help => sub { print $help_info; exit }, - version => sub { print $version_info; exit }, -) or die $help_info; - -die $help_info unless @ARGV == 1; - -my %include = (); -my %append = (); -my @include = (); # retain order given in include file - -# Process include file (if given). Format is: -# -# [section name] -# verbatim text -# -# or -# -# /pattern/ -# verbatim text -# - -while (@opt_include) -{ - my ($inc, $required) = @{shift @opt_include}; - - next unless -f $inc or $required; - die "$this_program: can't open `$inc' ($!)\n" - unless open INC, $inc; - - my $key; - my $hash = \%include; - - while (<INC>) - { - # [section] - if (/^\[([^]]+)\]/) - { - $key = uc $1; - $key =~ s/^\s+//; - $key =~ s/\s+$//; - $hash = \%include; - push @include, $key unless $include{$key}; - next; - } - - # /pattern/ - if (m!^/(.*)/([ims]*)!) - { - my $pat = $2 ? "(?$2)$1" : $1; - - # Check pattern. - eval { $key = qr($pat) }; - if ($@) - { - $@ =~ s/ at .*? line \d.*//; - die "$inc:$.:$@"; - } - - $hash = \%append; - next; - } - - # Check for options before the first section--anything else is - # silently ignored, allowing the first for comments and - # revision info. - unless ($key) - { - # handle options - if (/^-/) - { - local @ARGV = split; - GetOptions %opt_def; - } - - next; - } - - $hash->{$key} ||= ''; - $hash->{$key} .= $_; - } - - close INC; - - die "$this_program: no valid information found in `$inc'\n" - unless $key; -} - -# Compress trailing blank lines. -for my $hash (\(%include, %append)) -{ - for (keys %$hash) { $hash->{$_} =~ s/\n+$/\n/ } -} - -# Turn off localisation of executable's ouput. -@ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3; - -# Turn off localisation of date (for strftime). -setlocale LC_TIME, 'C'; - -# Grab help and version info from executable. -my ($help_text, $version_text) = map { - join '', map { s/ +$//; expand $_ } `$ARGV[0] $_ 2>/dev/null` - or die "$this_program: can't get `$_' info from $ARGV[0]\n" -} $help_option, $version_option; - -my $date = strftime "%B %Y", localtime; -(my $program = $ARGV[0]) =~ s!.*/!!; -my $package = $program; -my $version; - -if ($opt_output) -{ - unlink $opt_output - or die "$this_program: can't unlink $opt_output ($!)\n" - if -e $opt_output; - - open STDOUT, ">$opt_output" - or die "$this_program: can't create $opt_output ($!)\n"; -} - -# The first line of the --version information is assumed to be in one -# of the following formats: -# -# <version> -# <program> <version> -# {GNU,Free} <program> <version> -# <program> ({GNU,Free} <package>) <version> -# <program> - {GNU,Free} <package> <version> -# -# and seperated from any copyright/author details by a blank line. - -($_, $version_text) = split /\n+/, $version_text, 2; - -if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or - /^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/) -{ - $program = $1; - $package = $2; - $version = $3; -} -elsif (/^((?:GNU|Free) +)?(\S+) +(.*)/) -{ - $program = $2; - $package = $1 ? "$1$2" : $2; - $version = $3; -} -else -{ - $version = $_; -} - -$program =~ s!.*/!!; - -# No info for `info' itself. -$opt_no_info = 1 if $program eq 'info'; - -# --name overrides --include contents. -$include{NAME} = "$program \\- $opt_name\n" if $opt_name; - -# Default (useless) NAME paragraph. -$include{NAME} ||= "$program \\- manual page for $program $version\n"; - -# Man pages traditionally have the page title in caps. -my $PROGRAM = uc $program; - -# Set default page head/footers -$source ||= "$program $version"; -unless ($manual) -{ - for ($section) - { - if (/^(1[Mm]|8)/) { $manual = 'System Administration Utilities' } - elsif (/^6/) { $manual = 'Games' } - else { $manual = 'User Commands' } - } -} - -# Extract usage clause(s) [if any] for SYNOPSIS. -if ($help_text =~ s/^Usage:( +(\S+))(.*)((?:\n(?: {6}\1| *or: +\S).*)*)//m) -{ - my @syn = $2 . $3; - - if ($_ = $4) - { - s/^\n//; - for (split /\n/) { s/^ *(or: +)?//; push @syn, $_ } - } - - my $synopsis = ''; - for (@syn) - { - $synopsis .= ".br\n" if $synopsis; - s!^\S*/!!; - s/^(\S+) *//; - $synopsis .= ".B $1\n"; - s/\s+$//; - s/(([][]|\.\.+)+)/\\fR$1\\fI/g; - s/^/\\fI/ unless s/^\\fR//; - $_ .= '\fR'; - s/(\\fI)( *)/$2$1/g; - s/\\fI\\fR//g; - s/^\\fR//; - s/\\fI$//; - s/^\./\\&./; - - $synopsis .= "$_\n"; - } - - $include{SYNOPSIS} ||= $synopsis; -} - -# Process text, initial section is DESCRIPTION. -my $sect = 'DESCRIPTION'; -$_ = "$help_text\n\n$version_text"; - -# Normalise paragraph breaks. -s/^\n+//; -s/\n*$/\n/; -s/\n\n+/\n\n/g; - -# Temporarily exchange leading dots, apostrophes and backslashes for -# tokens. -s/^\./\x80/mg; -s/^'/\x81/mg; -s/\\/\x82/g; - -# Start a new paragraph (if required) for these. -s/([^\n])\n(Report +bugs|Email +bug +reports +to|Written +by)/$1\n\n$2/g; - -sub convert_option; - -while (length) -{ - # Convert some standard paragraph names. - if (s/^(Options|Examples): *\n//) - { - $sect = uc $1; - next; - } - - # Copyright section - if (/^Copyright +[(\xa9]/) - { - $sect = 'COPYRIGHT'; - $include{$sect} ||= ''; - $include{$sect} .= ".PP\n" if $include{$sect}; - - my $copy; - ($copy, $_) = split /\n\n/, $_, 2; - - for ($copy) - { - # Add back newline - s/\n*$/\n/; - - # Convert iso9959-1 copyright symbol or (c) to nroff - # character. - s/^Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/mg; - - # Insert line breaks before additional copyright messages - # and the disclaimer. - s/(.)\n(Copyright |This +is +free +software)/$1\n.br\n$2/g; - - # Join hyphenated lines. - s/([A-Za-z])-\n */$1/g; - } - - $include{$sect} .= $copy; - $_ ||= ''; - next; - } - - # Catch bug report text. - if (/^(Report +bugs|Email +bug +reports +to) /) - { - $sect = 'REPORTING BUGS'; - } - - # Author section. - elsif (/^Written +by/) - { - $sect = 'AUTHOR'; - } - - # Examples, indicated by an indented leading $, % or > are - # rendered in a constant width font. - if (/^( +)([\$\%>] )\S/) - { - my $indent = $1; - my $prefix = $2; - my $break = '.IP'; - $include{$sect} ||= ''; - while (s/^$indent\Q$prefix\E(\S.*)\n*//) - { - $include{$sect} .= "$break\n\\f(CW$prefix$1\\fR\n"; - $break = '.br'; - } - - next; - } - - my $matched = ''; - $include{$sect} ||= ''; - - # Sub-sections have a trailing colon and the second line indented. - if (s/^(\S.*:) *\n / /) - { - $matched .= $& if %append; - $include{$sect} .= qq(.SS "$1"\n); - } - - my $indent = 0; - my $content = ''; - - # Option with description. - if (s/^( {1,10}([+-]\S.*?))(?:( +(?!-))|\n( {20,}))(\S.*)\n//) - { - $matched .= $& if %append; - $indent = length ($4 || "$1$3"); - $content = ".TP\n\x83$2\n\x83$5\n"; - unless ($4) - { - # Indent may be different on second line. - $indent = length $& if /^ {20,}/; - } - } - - # Option without description. - elsif (s/^ {1,10}([+-]\S.*)\n//) - { - $matched .= $& if %append; - $content = ".HP\n\x83$1\n"; - $indent = 80; # not continued - } - - # Indented paragraph with tag. - elsif (s/^( +(\S.*?) +)(\S.*)\n//) - { - $matched .= $& if %append; - $indent = length $1; - $content = ".TP\n\x83$2\n\x83$3\n"; - } - - # Indented paragraph. - elsif (s/^( +)(\S.*)\n//) - { - $matched .= $& if %append; - $indent = length $1; - $content = ".IP\n\x83$2\n"; - } - - # Left justified paragraph. - else - { - s/(.*)\n//; - $matched .= $& if %append; - $content = ".PP\n" if $include{$sect}; - $content .= "$1\n"; - } - - # Append continuations. - while (s/^ {$indent}(\S.*)\n//) - { - $matched .= $& if %append; - $content .= "\x83$1\n" - } - - # Move to next paragraph. - s/^\n+//; - - for ($content) - { - # Leading dot and apostrophe protection. - s/\x83\./\x80/g; - s/\x83'/\x81/g; - s/\x83//g; - - # Convert options. - s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge; - } - - # Check if matched paragraph contains /pat/. - if (%append) - { - for my $pat (keys %append) - { - if ($matched =~ $pat) - { - $content .= ".PP\n" unless $append{$pat} =~ /^\./; - $content .= $append{$pat}; - } - } - } - - $include{$sect} .= $content; -} - -# Refer to the real documentation. -unless ($opt_no_info) -{ - my $info_page = $opt_info || $program; - - $sect = 'SEE ALSO'; - $include{$sect} ||= ''; - $include{$sect} .= ".PP\n" if $include{$sect}; - $include{$sect} .= <<EOT; -The full documentation for -.B $program -is maintained as a Texinfo manual. If the -.B info -and -.B $program -programs are properly installed at your site, the command -.IP -.B info $info_page -.PP -should give you access to the complete manual. -EOT -} - -# Output header. -print <<EOT; -.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version. -.TH $PROGRAM "$section" "$date" "$source" "$manual" -EOT - -# Section ordering. -my @pre = qw(NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES); -my @post = ('AUTHOR', 'REPORTING BUGS', 'COPYRIGHT', 'SEE ALSO'); -my $filter = join '|', @pre, @post; - -# Output content. -for (@pre, (grep ! /^($filter)$/o, @include), @post) -{ - if ($include{$_}) - { - my $quote = /\W/ ? '"' : ''; - print ".SH $quote$_$quote\n"; - - for ($include{$_}) - { - # Replace leading dot, apostrophe and backslash tokens. - s/\x80/\\&./g; - s/\x81/\\&'/g; - s/\x82/\\e/g; - print; - } - } -} - -exit; - -# Convert option dashes to \- to stop nroff from hyphenating 'em, and -# embolden. Option arguments get italicised. -sub convert_option -{ - local $_ = '\fB' . shift; - - s/-/\\-/g; - unless (s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/) - { - s/=(.)/\\fR=\\fI$1/; - s/ (.)/ \\fI$1/; - $_ .= '\fR'; - } - - $_; -} diff --git a/Build/source/utils/texinfo/doc/info-stnd.texi b/Build/source/utils/texinfo/doc/info-stnd.texi deleted file mode 100644 index 39292494f7f..00000000000 --- a/Build/source/utils/texinfo/doc/info-stnd.texi +++ /dev/null @@ -1,2265 +0,0 @@ -vb\input texinfo.tex @c -*-texinfo-*- -@comment $Id: info-stnd.texi,v 1.21 2008/03/04 09:45:52 gray Exp $ -@c We must \input texinfo.tex instead of texinfo, otherwise make -@c distcheck in the Texinfo distribution fails, because the texinfo Info -@c file is made first, and texi2dvi must include . first in the path. -@comment %**start of header -@setfilename info-stnd.info -@include version-stnd.texi -@settitle GNU Info @value{VERSION} -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This manual is for GNU Info (version @value{VERSION}, @value{UPDATED}), -a program for viewing documents in Info format (usually created from -Texinfo source files). - -Copyright @copyright{} 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License' in the Texinfo manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end quotation - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end copying - -@dircategory Texinfo documentation system -@direntry -* info standalone: (info-stnd). Read Info documents without Emacs. -* infokey: (info-stnd)Invoking infokey. Compile Info customizations. -@end direntry - -@titlepage -@title GNU Info -@subtitle for version @value{VERSION}, @value{UPDATED} -@author Brian J. Fox -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Info - -If you do not know how to use Info, but have a working Info reader, -you should read the Info manual before this one (@pxref{Top, Getting -Started,,info, Info}), as it includes more background information and -a thorough tutorial. This documentation describes the standalone Info -reader that is part of the Texinfo distribution, not the Info reader -that is part of GNU Emacs. -@end ifnottex - -@menu -* What is Info:: What is Info? -* Invoking Info:: Options you can pass on the command line. -* Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for reading the text within a node. -* Node Commands:: Commands for selecting a new node. -* Searching Commands:: Commands for searching an Info file. -* Xref Commands:: Commands for selecting cross references. -* Window Commands:: Commands which manipulate multiple windows. -* Printing Nodes:: How to print out the contents of a node. -* Miscellaneous Commands:: A few commands that defy categories. -* Variables:: How to change the default behavior of Info. -* Custom Key Bindings:: How to define your own key-to-command bindings. -* Index:: Global index with keystrokes, command names, - variable names, and general concepts. -@end menu - - -@node What is Info -@chapter What is Info? - -The @dfn{Info} program is a standalone program, part of the Texinfo -distribution, which is used to view Info files on an ASCII terminal. -@dfn{Info files} are typically the result of processing Texinfo files -with the program @code{makeinfo} (also in the Texinfo distribution) - -Texinfo itself is a documentation system that uses a single source -file to produce both on-line information and printed output. You can -typeset and print the files that you read in Info. - -GNU Emacs also provides an Info reader (just type @kbd{M-x info} in -Emacs). Emacs Info and standalone Info have nearly identical user -interfaces, although customization and other details are different -(this manual explains the standalone Info reader). The Emacs Info -reader supports the X Window System and other such bitmapped -interfaces, not just plain ASCII, so if you want the prettiest -display for Info files, you should try it. You can use Emacs Info -without using Emacs for anything else. (Type @kbd{C-x C-c} to exit; -this also works in the standalone Info reader.) - - -@node Invoking Info -@chapter Invoking Info - -@cindex Info, invoking -@cindex invoking Info -@cindex command line options -@cindex options, command line -@cindex arguments, command line - -GNU Info accepts several options to control the initial node being -viewed, and to specify which directories to search for Info files. Here -is a template showing an invocation of GNU Info from the shell: - -@example -info [@var{option}]@dots{} [@var{menu-item}@dots{}] -@end example - -The program accepts the following options: - -@table @code -@anchor{--apropos} -@item --apropos=@var{string} -@itemx -k @var{string} -@cindex Searching all indices -@cindex Info files@r{, searching all indices} -@cindex Apropos@r{, in Info files} -Specify a string to search in every index of every Info file installed -on your system. Info looks up the named @var{string} in all the -indices it can find, prints the results to standard output, and then -exits. If you are not sure which Info file explains certain issues, -this option is your friend. (If your system has a lot of Info files -installed, searching all of them might take some time!) - -You can invoke the apropos command from inside Info; see -@ref{Searching Commands}. - -@cindex directory path -@item --directory @var{directory-path} -@itemx -d @var{directory-path} -Prepend @var{directory-path} to the list of directory paths searched -when Info needs to find a file. You may issue @code{--directory} -multiple times; once for each directory which contains Info files. The -list of directories searched by Info is constructed from the value of -the environment variable @code{INFOPATH}; @code{--directory} causes the -named @var{directory-path} to be prepended to that list. The value of -@code{INFOPATH} is a list of directories usually separated by a colon; -on MS-DOS/MS-Windows systems, the semicolon is used. If you do not -define @code{INFOPATH}, Info uses a default path defined when Info was -built as the initial list of directories. If the value of -@code{INFOPATH} ends with a colon (or semicolon on MS-DOS/MS-Windows), -the initial list of directories is constructed by appending the -build-time default to the value of @code{INFOPATH}. - -@cindex keystrokes, recording -@cindex remembering user keystrokes -@item --dribble=@var{dribble-file} -Specify a file where all user keystrokes will be recorded. This file -can be used later to replay the same sequence of commands, see the -@samp{--restore} option below. - -@item --file @var{filename} -@itemx -f @var{filename} -@cindex Info file, selecting -Specify a particular Info file to visit. By default, Info visits -the file @code{dir}; if you use this option, Info will start with -@code{(@var{filename})Top} as the first file and node. - -@cindex relative Info file names -@cindex file names, relative -@cindex Info files, relative -If @var{filename} is an absolute file name, or begins with @file{./} or -@file{../}, Info looks for @var{filename} only in the directory of the -specified @var{filename}, and adds the directory of @var{filename} to -the value of @code{INFOPATH}. In contrast, if @var{filename} is in the -form of a relative file name, but without the @file{./} or @file{../} -prefix, Info will only look for it in the directories specified in -@code{INFOPATH}. In other words, Info does @emph{not} treat file names -which lack @file{./} and @file{../} prefix as relative to the current -directory. - -@cindex compressed Info files -@cindex files, compressed -@cindex Info files, compressed -In every directory Info tries, if @var{filename} is not found, Info -looks for it with a number of known extensions of Info files@footnote{ -@file{.info}, @file{-info}, @file{/index}, and @file{.inf}.}. For every -known extension, Info looks for a compressed file, if a regular file -isn't found. Info supports files compressed with @code{gzip}, -@code{bzip2}, @code{compress} and @code{yabba} programs; it calls -@code{gunzip}, @code{bunzip2}, @code{uncompress} and @code{unyabba}, -accordingly, to decompress such files. Compressed Info files are -assumed to have @file{.z}, @file{.gz}, @file{.bz2}, @file{.Z}, or -@file{.Y} extensions, possibly in addition to one of the known Info -files extensions@footnote{The MS-DOS version allows for the Info -extension, such as @code{.inf}, and the short compressed file -extensions, such as @file{.z} and @file{.gz}, to be merged into a single -extension, since DOS doesn't allow more than a single dot in the -basename of a file. Thus, on MS-DOS, if Info looks for @file{bison}, -file names like @file{bison.igz} and @file{bison.inz} will be found and -decompressed by @code{gunzip}.}. - -@item --help -@itemx -h -Produces a relatively brief description of the available Info options. - -@item --index-search @var{string} -@cindex index search, selecting from the command line -@cindex online help, using Info as -After processing all command-line arguments, go to the index in the Info -file and search for index entries which match @var{string}. If such an -entry is found, the Info session begins with displaying the node pointed -to by the first matching index entry; press @kbd{,} to step through the -rest of the matching entries. If no such entry exists, print @samp{no -entries found} and exit with nonzero status. This can be used from -another program as a way to provide online help, or as a quick way of -starting to read an Info file at a certain node when you don't know the -exact name of that node. - -This command can also be invoked from inside Info; see @ref{Searching -Commands}. - -@item --node @var{nodename} -@itemx -n @var{nodename} -@cindex node, selecting from the command line -Specify a particular node to visit in the initial file that Info -loads. This is especially useful in conjunction with -@code{--file}@footnote{Of course, you can specify both the file and node -in a @code{--node} command; but don't forget to escape the open and -close parentheses and whitespace from the shell as in: @code{info --node -"(emacs)Buffers"}.}. You may specify @code{--node} multiple times; for -an interactive Info, each @var{nodename} is visited in its own window, -for a non-interactive Info (such as when @code{--output} is given) each -@var{nodename} is processed sequentially. - -@item --output @var{filename} -@itemx -o @var{filename} -@cindex file, outputting to -@cindex outputting to a file -Specify @var{filename} as the name of a file to which to direct output. -Each node that Info visits will be output to @var{filename} instead of -interactively viewed. A value of @code{-} for @var{filename} specifies -the standard output. - -@cindex colors in documents -@cindex ANSI escape sequences in documents -@item --raw-escapes -@itemx --no-raw-escapes -@itemx -R -Do not remove ANSI escape sequences from documents. Some versions of -Groff, the GNU document formatter, produce man pages with ANSI escape -sequences for bold, italics, and underlined characters, and for -colorized text. By default, Info lets those escape sequences pass -through directly to the terminal. If your terminal does not support -these escapes, use @code{--no-raw-escapes} to make Info remove them. - -@cindex replaying recorded keystrokes -@item --restore=@var{dribble-file} -Read keystrokes from @var{dribble-file}, presumably recorded during -previous Info session (see the description of the @samp{--dribble} -option above). When the keystrokes in the files are all read, Info -reverts its input to the usual interactive operation. - -@anchor{--show-options} -@cindex command-line options, how to find -@cindex invocation description, how to find -@item --show-options -@itemx --usage -@itemx -O -This option causes Info to look for the node that describes how to -invoke the program and its command-line options, and begin the session -by displaying that node. It is provided to make it easier to find the -most important usage information in a manual without the need to wade -through complex menu hierarchies. The effect is similar to the -@code{M-x goto-invocation} command (@pxref{goto-invocation}) from inside -Info. - -@cindex speech synthesizers -@item --speech-friendly -@itemx -b -On MS-DOS/MS-Windows only, this option causes Info to use standard file -I/O functions for screen writes. (By default, Info uses direct writes -to the video memory on these systems, for faster operation and colored -display support.) This allows the speech synthesizers used by blind -persons to catch the output and convert it to audible speech. - -@item --subnodes -@cindex @code{--subnodes}, command line option -This option only has meaning when given in conjunction with -@code{--output}. It means to recursively output the nodes appearing in -the menus of each node being output. Menu items which resolve to -external Info files are not output, and neither are menu items which are -members of an index. Each node is only output once. - -@item --version -@cindex version information -Prints the version information of Info and exits. - -@anchor{--vi-keys} -@cindex vi-like key bindings -@cindex Less-like key bindings -@item --vi-keys -This option binds functions to keys differently, to emulate the key -bindings of @code{vi} and Less. The default key bindings are generally -modeled after Emacs. -(@xref{Custom Key Bindings}, -for a more general way of altering GNU Info's key bindings.) - -@cindex Info manual location -@cindex Where is an Info manual? -@item --where -@itemx --location -@itemx -w -Show the filename that would be read and exit, instead of actually -reading it and starting Info. - -@item @var{menu-item} -@cindex menu, following -@anchor{command-line menu items} -Info treats its remaining arguments as the names of menu items. The -first argument is a menu item in the initial node visited (generally -@code{dir}), the second argument is a menu item in the first argument's -node, etc. You can easily move to the node of your choice by specifying -the menu names which describe the path to that node. For example, - -@example -info emacs buffers -@end example - -@noindent -first selects the menu item @samp{Emacs} in the node @samp{(dir)Top}, -and then selects the menu item @samp{Buffers} in the node -@samp{(emacs)Top}. -@end table - -To avoid searching the @file{dir} files and just show some arbitrary -file, use @samp{-f} and the filename, as in @samp{info -f ./foo.info}. - -The index search and the search for the node which describes program -invocation and command-line options begins @emph{after} processing all -the command-line menu items. Therefore, the Info file searched for the -index or the invocation node is the file where Info finds itself after -following all the menu items given on the command line. This is so -@samp{info emacs --show-options} does what you'd expect. - -Finally, Info defines many default key bindings and variables. -@xref{Custom Key Bindings}, for information on how to customize these -settings. - -@c FIXME: the feature with lowercasing the file name isn't documented - - -@node Cursor Commands -@chapter Moving the Cursor -@cindex cursor, moving -@cindex moving the cursor - -Many people find that reading screens of text page by page is made -easier when one is able to indicate particular pieces of text with -some kind of pointing device. Since this is the case, GNU Info (both -the Emacs and standalone versions) have several commands which allow -you to move the cursor about the screen. The notation used in this -manual to describe keystrokes is identical to the notation used within -the Emacs manual, and the GNU Readline manual. @xref{User Input,,, -emacs, The GNU Emacs Manual}, if you are unfamiliar with the -notation.@footnote{Here's a short summary. @kbd{C-@var{x}} means -press the @kbd{CTRL} key and the key @var{x}. @kbd{M-@var{x}} means -press the @kbd{META} key and the key @var{x}. On many terminals th -@kbd{META} key is known as the @kbd{ALT} key. @kbd{SPC} is the space -bar. The other keys are usually called by the names imprinted on -them.} - -The following table lists the basic cursor movement commands in Info. -Each entry consists of the key sequence you should type to execute the -cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it -invokes @code{execute-extended-command}. @xref{M-x, , Executing an -extended command, emacs, The GNU Emacs Manual}, for more detailed -information.} command name (displayed in parentheses), and a short -description of what the command does. All of the cursor motion commands -can take a @dfn{numeric} argument (see @ref{Miscellaneous Commands, -@code{universal-argument}, to find out how to supply them}. With a -numeric argument, the motion commands are simply executed that -many times; for example, a numeric argument of 4 given to -@code{next-line} causes the cursor to move down 4 lines. With a -negative numeric argument, the motion is reversed; an argument of -4 -given to the @code{next-line} command would cause the cursor to move -@emph{up} 4 lines. - -@table @asis -@item @key{C-n} (@code{next-line}) -@itemx @key{DOWN} (an arrow key) -@kindex C-n -@kindex DOWN (an arrow key) -@findex next-line -Move the cursor down to the next line. - -@item @key{C-p} (@code{prev-line}) -@itemx @key{UP} (an arrow key) -@kindex C-p -@kindex UP (an arrow key) -@findex prev-line -Move the cursor up to the previous line. - -@item @key{C-a} (@code{beginning-of-line}) -@itemx @key{Home} (on DOS/Windows only) -@kindex C-a, in Info windows -@kindex Home -@findex beginning-of-line -Move the cursor to the start of the current line. - -@item @key{C-e} (@code{end-of-line}) -@itemx @key{End} (on DOS/Windows only) -@kindex C-e, in Info windows -@kindex End -@findex end-of-line -Move the cursor to the end of the current line. - -@item @key{C-f} (@code{forward-char}) -@itemx @key{RIGHT} (an arrow key) -@kindex C-f, in Info windows -@kindex RIGHT (an arrow key) -@findex forward-char -Move the cursor forward a character. - -@item @key{C-b} (@code{backward-char}) -@itemx @key{LEFT} (an arrow key) -@kindex C-b, in Info windows -@kindex LEFT (an arrow key) -@findex backward-char -Move the cursor backward a character. - -@item @key{M-f} (@code{forward-word}) -@itemx @kbd{C-@key{RIGHT}} (on DOS/Windows only) -@kindex M-f, in Info windows -@kindex C-RIGHT -@findex forward-word -Move the cursor forward a word. - -@item @key{M-b} (@code{backward-word}) -@itemx @kbd{C-@key{LEFT}} (on DOS/Windows only) -@kindex M-b, in Info windows -@kindex C-LEFT -@findex backward-word -Move the cursor backward a word. - -@item @key{M-<} (@code{beginning-of-node}) -@itemx @key{C-@key{Home}} (on DOS/Windows only) -@itemx @key{b} -@itemx @key{M-b}, vi-like operation -@kindex b, in Info windows -@kindex M-< -@kindex C-Home -@kindex M-b, vi-like operation -@findex beginning-of-node -Move the cursor to the start of the current node. - -@item @key{M->} (@code{end-of-node}) -@itemx @key{C-@key{End}} (on DOS/Windows only) -@itemx @key{e} -@kindex M-> -@kindex e, in Info windows -@kindex C-End -@findex end-of-node -Move the cursor to the end of the current node. - -@item @key{M-r} (@code{move-to-window-line}) -@kindex M-r -@findex move-to-window-line -Move the cursor to a specific line of the window. Without a numeric -argument, @code{M-r} moves the cursor to the start of the line in the -center of the window. With a numeric argument of @var{n}, @code{M-r} -moves the cursor to the start of the @var{n}th line in the window. -@end table - - -@node Scrolling Commands -@chapter Moving Text Within a Window -@cindex scrolling - -Sometimes you are looking at a screenful of text, and only part of the -current paragraph you are reading is visible on the screen. The -commands detailed in this section are used to shift which part of the -current node is visible on the screen. - -Scrolling commands are bound differently when @samp{--vi-keys} -operation is in effect (@pxref{--vi-keys}). These key bindings are -designated with ``vi-like operation''. @xref{Custom Key Bindings}, -for information on arbitrarily customizing key bindings and variable -settings. - -@table @asis -@item @key{SPC} (@code{scroll-forward}) -@kindex SPC, in Info windows -@findex scroll-forward -Shift the text in this window up. That is, show more of the node which -is currently below the bottom of the window. With a numeric argument, -show that many more lines at the bottom of the window; a numeric -argument of 4 would shift all of the text in the window up 4 lines -(discarding the top 4 lines), and show you four new lines at the bottom -of the window. Without a numeric argument, @key{SPC} takes the bottom -two lines of the window and places them at the top of the window, -redisplaying almost a completely new screenful of lines. If you are at -the end of a node, @key{SPC} takes you to the ``next'' node, so that you can -read an entire manual from start to finish by repeating @key{SPC}. - -The default scroll size is one screen-full, but it can be changed by -invoking the (@code{scroll-forward-page-only-set-window}) command, -@samp{z} under @samp{--vi-keys}, with a numeric argument. - -@item @key{NEXT} (an arrow key) (@code{scroll-forward-page-only}) -@itemx @key{C-v} -@itemx @key{C-f}, vi-like operation -@itemx @key{f}, vi-like operation -@itemx @key{M-SPC}, vi-like operation -@kindex NEXT -@kindex C-v -@kindex C-f, vi-like operation -@kindex f, vi-like operation -@kindex M-SPC, vi-like operation -@findex scroll-forward-page-only -Shift the text in this window up. This is identical to the @key{SPC} -operation above, except that it never scrolls beyond the end of the -current node. - -@kindex PageDown -The @key{NEXT} key is known as the @key{PageDown} key on some -keyboards. - -@item @key{z} (@code{scroll-forward-page-only-set-window}, vi-like operation) -@kindex z, vi-like operation -@findex scroll-forward-page-only-set-window -Scroll forward, like with @key{NEXT}, but if a numeric argument is -specified, it becomes the default scroll size for subsequent -@code{scroll-forward} and @code{scroll-backward} commands and their -ilk. - -@item @key{DEL} (@code{scroll-backward}) -@kindex DEL, in Info windows -@findex scroll-backward -Shift the text in this window down. The inverse of -@code{scroll-forward}. -If you are at the start of a node, @key{DEL} takes you to the -``previous'' node, so that you can read an entire manual from finish to -start by repeating @key{DEL}. The default scroll size can be changed by -invoking the (@code{scroll-backward-page-only-set-window}) command, -@samp{w} under @samp{--vi-keys}, with a numeric argument. - -@itemx @key{PREVIOUS} (arrow key) (@code{scroll-backward-page-only}) -@itemx @key{PRIOR} (arrow key) -@itemx @key{M-v} -@itemx @key{b}, vi-like operation -@itemx @key{C-b}, vi-like operation -@kindex PREVIOUS -@kindex M-v -@kindex b, vi-like operation -@kindex C-b, vi-like operation -@findex scroll-backward-page-only -Shift the text in this window down. The inverse of -@code{scroll-forward-page-only}. Does not scroll beyond the start of -the current node. The default scroll size can be changed by invoking -the(@code{scroll-backward-page-only-set-window}) command, @samp{w} under -@samp{--vi-keys}, with a numeric argument. - -@item @key{w} (@code{scroll-backward-page-only-set-window}, vi-like operation) -@kindex w, vi-like operation -@findex scroll-backward-page-only-set-window -Scroll backward, like with @key{PREVIOUS}, but if a numeric argument is -specified, it becomes the default scroll size for subsequent -@code{scroll-forward} and @code{scroll-backward} commands. - -@item @key{C-n} (@code{down-line}, vi-like operation) -@itemx @key{C-e}, vi-like operation -@itemx @key{RET}, vi-like operation -@itemx @key{LFD}, vi-like operation -@itemx @key{DOWN}, vi-like operation -@kindex C-n, vi-like operation -@kindex C-e, vi-like operation -@kindex RET, vi-like operation -@kindex LFD, vi-like operation -@kindex DOWN, vi-like operation -@findex down-line -Scroll forward by one line. With a numeric argument, scroll forward -that many lines. - -@item @key{C-p} (@code{up-line}, vi-like operation) -@itemx @key{UP}, vi-like operation -@itemx @key{y}, vi-like operation -@itemx @key{k}, vi-like operation -@itemx @key{C-k}, vi-like operation -@itemx @key{C-y}, vi-like operation -@kindex C-p, vi-like operation -@kindex UP, vi-like operation -@kindex y, vi-like operation -@kindex k, vi-like operation -@kindex C-k, vi-like operation -@kindex C-y, vi-like operation -@findex up-line -Scroll backward one line. With a numeric argument, scroll backward that -many lines. - -@item @key{d} (@code{scroll-half-screen-down}, vi-like operation) -@itemx @key{C-d}, vi-like operation -@kindex d, vi-like operation -@kindex C-d, vi-like operation -@findex scroll-half-screen-down -Scroll forward by half of the screen size. With a numeric argument, -scroll that many lines. If an argument is specified, it becomes the new -default number of lines to scroll for subsequent @samp{d} and @samp{u} -commands. - -@item @key{u} (@code{scroll-half-screen-up}, vi-like operation) -@itemx @key{C-u}, vi-like operation -@kindex u, vi-like operation -@kindex C-u, vi-like operation -@findex scroll-half-screen-up -Scroll back by half of the screen size. With a numeric argument, -scroll that many lines. If an argument is specified, it becomes the new -default number of lines to scroll for subsequent @samp{u} and @samp{d} -commands. -@end table - -@cindex scrolling through node structure -The @code{scroll-forward} and @code{scroll-backward} commands can also -move forward and backward through the node structure of the file. If -you press @key{SPC} while viewing the end of a node, or @key{DEL} while -viewing the beginning of a node, what happens is controlled by the -variable @code{scroll-behavior} (@pxref{scroll-behavior}). - -The @code{scroll-forward-page-only} and @code{scroll-backward-page-only} -commands never scroll beyond the current node. - -@kindex PageUp -The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs -refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or -@key{PageUp} to scroll, Info never scrolls beyond the beginning of the -current node. - -@kindex BS (backspace) -If your keyboard lacks the @key{DEL} key, look for a key called -@key{BS}, or @samp{BackSpace}, sometimes designated with an arrow which -points to the left, which should perform the same function. - -@table @asis -@item @key{C-l} (@code{redraw-display}) -@kindex C-l -@findex redraw-display -Redraw the display from scratch, or shift the line containing the cursor -to a specified location. With no numeric argument, @samp{C-l} clears -the screen, and then redraws its entire contents. Given a numeric -argument of @var{n}, the line containing the cursor is shifted so that -it is on the @var{n}th line of the window. - -@item @kbd{C-x @key{w}} (@code{toggle-wrap}) -@kindex C-w -@findex toggle-wrap -Toggles the state of line wrapping in the current window. Normally, -lines which are longer than the screen width @dfn{wrap}, i.e., they are -continued on the next line. Lines which wrap have a @samp{\} appearing -in the rightmost column of the screen. You can cause such lines to be -terminated at the rightmost column by changing the state of line -wrapping in the window with @code{C-x w}. When a line which needs more -space than one screen width to display is displayed, a @samp{$} appears -in the rightmost column of the screen, and the remainder of the line is -invisible. When long lines are truncated, the modeline displays the -@samp{$} character near its left edge. -@end table - - -@node Node Commands -@chapter Selecting a Node -@cindex nodes, selection of - -This section details the numerous Info commands which select a new node -to view in the current window. - -The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and -@samp{l}. Note that the commands to select nodes are mapped differently -when @samp{--vi-keys} is in effect; these keybindings are designated -below as ``vi-like operation''. - -When you are viewing a node, the top line of the node contains some Info -@dfn{pointers} which describe where the next, previous, and up nodes -are. Info uses this line to move about the node structure of the file -when you use the following commands: - -@table @asis -@item @key{n} (@code{next-node}) -@itemx @kbd{C-@key{NEXT}} (on DOS/Windows only) -@itemx @kbd{C-x @key{n}}, vi-like operation -@kindex n -@kindex C-NEXT -@kindex C-x n, vi-like operation -@findex next-node -Select the `Next' node. - -@kindex C-PgDn -The @key{NEXT} key is known as the @key{PgDn} key on some -keyboards. - -@item @key{p} (@code{prev-node}) -@itemx @kbd{C-@key{PREVIOUS}} (on DOS/Windows only) -@kindex p -@kindex C-PREVIOUS -@findex prev-node -Select the `Prev' node. - -@kindex C-PgUp -The @key{PREVIOUS} key is known as the @key{PgUp} key on some -keyboards. - -@item @key{u} (@code{up-node}) -@itemx @kbd{C-@key{UP}} (an arrow key on DOS/Windows only) -@itemx @kbd{C-x @key{u}}, vi-like operation -@kindex u -@kindex C-UP -@kindex C-x u, vi-like operation -@findex up-node -Select the `Up' node. -@end table - -You can easily select a node that you have already viewed in this window -by using the @samp{l} command---this name stands for ``last'', and -actually moves backwards through the history of visited nodes for this -window. This is handy when you followed a reference to another node, -possibly to read about a related issue, and would like then to resume -reading at the same place where you started the excursion. - -Each node where you press @samp{l} is discarded from the history. Thus, -by the time you get to the first node you visited in a window, the -entire history of that window is discarded. - -@table @asis -@item @key{l} (@code{history-node}) -@itemx @key{C-@key{CENTER}} (on DOS/Windows only) -@itemx @key{'}, vi-like operation -@kindex l -@kindex C-CENTER -@kindex ', vi-like operation -@findex history-node -Pop the most recently selected node in this window from the node -history. -@end table - -Two additional commands make it easy to select the most commonly -selected nodes; they are @samp{t} and @samp{d}. - -@table @asis -@item @key{t} (@code{top-node}) -@itemx @key{M-t}, vi-like operation -@kindex t -@kindex M-t, vi-like operation -@findex top-node -Select the node @samp{Top} in the current Info file. - -@item @key{d} (@code{dir-node}) -@itemx @key{M-d}, vi-like operation -@kindex d -@kindex M-d, vi-like operation -@findex dir-node -Select the directory node (i.e., the node @samp{(dir)}). -@end table - -Here are some other commands which immediately result in the selection -of a different node in the current window: - -@table @asis -@item @key{<} (@code{first-node}) -@itemx @key{g}, vi-like operation -@kindex < -@kindex g, vi-like operation -@findex first-node -Selects the first node which appears in this file. This node is most -often @samp{Top}, but it does not have to be. With a numeric argument -@var{N}, select the @var{N}th node (the first node is node 1). An -argument of zero is the same as the argument of 1. - -@item @key{>} (@code{last-node}) -@itemx @key{G}, vi-like operation -@kindex > -@kindex G, vi-like operation -@findex last-node -Select the last node which appears in this file. With a numeric argument -@var{N}, select the @var{N}th node (the first node is node 1). An -argument of zero is the same as no argument, i.e., it selects the last -node. - -@item @key{]} (@code{global-next-node}) -@kindex ] -@findex global-next-node -Move forward or down through node structure. If the node that you are -currently viewing has a @samp{Next} pointer, that node is selected. -Otherwise, if this node has a menu, the first menu item is selected. If -there is no @samp{Next} and no menu, the same process is tried with the -@samp{Up} node of this node. - -@item @key{[} (@code{global-prev-node}) -@kindex [ -@findex global-prev-node -Move backward or up through node structure. If the node that you are -currently viewing has a @samp{Prev} pointer, that node is selected. -Otherwise, if the node has an @samp{Up} pointer, that node is selected, -and if it has a menu, the last item in the menu is selected. -@end table - -You can get the same behavior as @code{global-next-node} and -@code{global-prev-node} while simply scrolling through the file with -@key{SPC} and @key{DEL} (@pxref{scroll-behavior}). - -@table @asis -@anchor{goto-node} -@item @key{g} (@code{goto-node}) -@itemx @kbd{C-x @key{g}}, vi-like operation -@kindex g -@kindex C-x g, vi-like operation -@findex goto-node -Read the name of a node and select it. While reading the node name, -completion (@pxref{The Echo Area, completion}) is only done for the -nodes which reside in one of the Info files that were loaded in the -current Info session; if the desired node resides in some other file, -you must type the node exactly as it appears in that Info file, and you -must include the Info file of the other file. For example, - -@example -@code{g(emacs)Buffers} -@end example - -finds the node @samp{Buffers} in the Info file @file{emacs}. - -@anchor{goto-invocation} -@item @key{O} (@code{goto-invocation} -@itemx @key{I} -@kindex O -@kindex I -@findex goto-invocation -@cindex finding the Invocation node -Read the name of a program and look for a node in the current Info file -which describes the invocation and the command-line options for that -program. The default program name is derived from the name of the -current Info file. This command does the same as the -@samp{--show-options} command-line option (@pxref{--show-options}), but -it also allows to specify the program name; this is important for those -manuals which describe several programs. - -If you need to find the Invocation node of a program that is documented -in another Info file, you need to visit that file before invoking -@samp{I}. For example, if you are reading the Emacs manual and want to -see the command-line options of the @code{makeinfo} program, type @kbd{g -(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't -know what Info file documents the command, or if invoking @samp{I} -doesn't display the right node, go to the @samp{(dir)} node (using the -@samp{d} command) and invoke @samp{I} from there. - -@item @key{G} (@code{menu-sequence}) -@kindex G -@findex menu-sequence -@cindex menu, following, from inside Info -Read a sequence of menu entries and follow it. Info prompts for a -sequence of menu items separated by commas. (Since commas are not -allowed in a node name, they are a natural choice for a delimiter in a -list of menu items.) Info then looks up the first item in the menu of -the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info -uses @samp{Top}). If such an entry is found, Info goes to the node it -points to and looks up the second item in the menu of that node, etc. -In other words, you can specify a complete path which descends through -the menu hierarchy of a particular Info file starting at the -@samp{(dir)} node. This has the same effect as if you typed the menu -item sequence on Info's command line, see @ref{command-line menu items,, -Info command-line arguments processing}. For example, - -@example - @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}} -@end example - -@noindent -displays the node @samp{Reporting Bugs} in the Texinfo manual. (You -don't actually need to type the menu items in their full length, or in -their exact letter-case. However, if you do type the menu items -exactly, Info will find it faster.) - -If any of the menu items you type are not found, Info stops at the last -entry it did find and reports an error. - -@item @kbd{C-x @key{k}} (@code{kill-node}) -@kindex C-x k -@findex kill-node -Kill a node. The node name is prompted for in the echo area, with a -default of the current node. @dfn{Killing} a node means that Info tries -hard to forget about it, removing it from the list of history nodes kept -for the window where that node is found. Another node is selected in -the window which contained the killed node. - -@item @kbd{C-x C-f} (@code{view-file}) -@kindex C-x C-f -@findex view-file -Read the name of a file and selects the entire file. The command -@example -@code{C-x C-f @var{filename}} -@end example -is equivalent to typing -@example -@code{g(@var{filename})*} -@end example - -@item @kbd{C-x C-b} (@code{list-visited-nodes}) -@kindex C-x C-b -@findex list-visited-nodes -Make a window containing a menu of all of the currently visited nodes. -This window becomes the selected window, and you may use the standard -Info commands within it. - -@item @kbd{C-x @key{b}} (@code{select-visited-node}) -@kindex C-x b -@findex select-visited-node -Select a node which has been previously visited in a visible window. -This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is -created. -@end table - - -@node Searching Commands -@chapter Searching an Info File -@cindex searching - -GNU Info allows you to search for a sequence of characters throughout an -entire Info file, search through the indices of an Info file, or find -areas within an Info file which discuss a particular topic. - -@table @asis -@item @key{s} (@code{search}) -@itemx @key{/} -@kindex s -@kindex / -@findex search -@cindex regular expression search -Read a string in the echo area and search for it, either as a regular -expression (by default) or a literal string. If the string includes -upper-case characters, the Info file is searched case-sensitively; -otherwise Info ignores the letter case. With a numeric argument of -@var{N}, search for @var{N}th occurrence of the string. Negative -arguments search backwards. - -@item @key{?} (@code{search-backward}, vi-like operation) -@kindex ?, vi-like operation -@findex search-backward -Read a string in the echo area and search backward through the Info file -for that string. If the string includes upper-case characters, the Info -file is searched case-sensitively; otherwise Info ignores the letter -case. With a numeric argument of @var{N}, search for @var{N}th -occurrence of the string. Negative arguments search forward. - -@item @key{R} (@code{toggle-regexp}) -@kindex R -@findex toggle-regexp -Toggle between using regular expressions and literal strings for -searching. Info uses so-called `extended' regular expression syntax, -similar to Emacs (@pxref{Regexps, , Using Regular Expressions, emacs, -The GNU Emacs Manual}). - -@item @key{S} (@code{search-case-sensitively} -@kindex S -@findex search-case-sensitively -@cindex search, case-sensitive -@cindex case-sensitive search -Read a string in the echo area and search for it case-sensitively, even -if the string includes only lower-case letters. With a numeric argument -of @var{N}, search for @var{N}th occurrence of the string. Negative -arguments search backwards. - -@item @kbd{C-x @key{n}} (@code{search-next}) -@itemx @key{n}, vi-like operation -@kindex C-x n -@kindex n, vi-like operation -@findex search-next -@cindex repeated search -Search for the same string used in the last search command, in the same -direction, and with the same case-sensitivity option. With a numeric -argument of @var{N}, search for @var{N}th next occurrence. - -@item @kbd{C-x @key{N}} (@code{search-previous}) -@itemx @key{N}, vi-like operation -@kindex C-x N -@kindex n, vi-like operation -@findex search-previous -Search for the same string used in the last search command, and with the -same case-sensitivity option, but in the reverse direction. With a -numeric argument of @var{N}, search for @var{N}th previous occurrence. - -@item @key{C-s} (@code{isearch-forward}) -@kindex C-s -@findex isearch-forward -@cindex incremental search -Interactively search forward through the Info file for a string as you -type it. If the string includes upper-case characters, the search is -case-sensitive; otherwise Info ignores the letter case. - -@item @key{C-r} (@code{isearch-backward}) -@kindex C-r -@findex isearch-backward -Interactively search backward through the Info file for a string as -you type it. If the string includes upper-case characters, the search -is case-sensitive; otherwise Info ignores the letter case. - -@item @key{i} (@code{index-search}) -@kindex i -@findex index-search -@cindex index, searching -@cindex searching, in the indices -Look up a string in the indices for this Info file, and select a node -to which the found index entry points. - -@item @key{,} (@code{next-index-match}) -@kindex , -@findex next-index-match -Move to the node containing the next matching index item from the last -@samp{i} command. - -@item @kbd{M-x index-apropos} -@findex index-apropos -Grovel the indices of all the known Info files on your system for a -string, and build a menu of the possible matches. -@end table - -The most basic searching command is @samp{s} or @samp{/} -(@code{search}). The @samp{s} command prompts you for a string in the -echo area, and then searches the remainder of the Info file for an -occurrence of that string. If the string is found, the node containing -it is selected, and the cursor is left positioned at the start of the -found string. Subsequent @samp{s} commands show you the default search -string within @samp{[} and @samp{]}; pressing @key{RET} instead of -typing a new string will use the default search string. Under -@samp{--vi-keys} (@pxref{--vi-keys}), using the @samp{n} or @samp{N} -commands is a faster way of searching for the same string. - -@dfn{Incremental searching} is similar to basic searching, but the -string is looked up while you are typing it, instead of waiting until -the entire search string has been specified. - -@cindex search, and case-sensitivity -@cindex case-sensitivity, and search -Both incremental and non-incremental search by default ignore the case -of letters when comparing the Info file text with the search string. -However, an uppercase letter in the search string makes the search -case-sensitive. You can force a case-sensitive non-incremental search, -even for a string that includes only lower-case letters, by using the -@samp{S} command (@code{search-case-sensitively}). The @samp{n} and -@samp{N} commands operate case-sensitively if the last search command -was @samp{S}. - -The most efficient means of finding something quickly in a manual is -the @samp{i} command (@code{index-search}). This command prompts for -a string, and then looks for that string in all the indices of the -current Info manual. If it finds a matching index entry, it displays -the node to which that entry refers and prints the full text of the -entry in the echo area. You can press @samp{,} -(@code{next-index-match}) to find more matches. A good Info manual -has all of its important concepts indexed, so the @samp{i} command -lets you use a manual as a reference. - -If you don't know what manual documents something, try the @kbd{M-x -index-apropos} command. It prompts for a string and then looks up -that string in all the indices of all the Info documents installed on -your system. It can also be invoked from the command line; see -@ref{--apropos}. - - -@node Xref Commands -@chapter Selecting Cross References - -We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} -pointers which appear at the top of a node. In addition to these -pointers, a node may contain other pointers which refer you to a -different node, perhaps in another Info file. Such pointers are called -@dfn{cross references}, or @dfn{xrefs} for short. - -@menu -* Parts of an Xref:: What a cross reference is made of. -* Selecting Xrefs:: Commands for selecting menu or note items. -@end menu - -@node Parts of an Xref -@section Parts of an Xref - -Cross references have two major parts: the first part is called the -@dfn{label}; it is the name that you can use to refer to the cross -reference, and the second is the @dfn{target}; it is the full name of -the node that the cross reference points to. - -The target is separated from the label by a colon @samp{:}; first the -label appears, and then the target. For example, in the sample menu -cross reference below, the single colon separates the label from the -target. - -@example -* Foo Label: Foo Target. More information about Foo. -@end example - -Note the @samp{.} which ends the name of the target. The @samp{.} is -not part of the target; it serves only to let Info know where the target -name ends. - -A shorthand way of specifying references allows two adjacent colons to -stand for a target name which is the same as the label name: - -@example -* Foo Commands:: Commands pertaining to Foo. -@end example - -In the above example, the name of the target is the same as the name of -the label, in this case @code{Foo Commands}. - -You will normally see two types of cross reference while viewing nodes: -@dfn{menu} references, and @dfn{note} references. Menu references -appear within a node's menu; they begin with a @samp{*} at the beginning -of a line, and continue with a label, a target, and a comment which -describes what the contents of the node pointed to contains. - -Note references appear within the body of the node text; they begin with -@code{*Note}, and continue with a label and a target. - -Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross references -can point to any valid node. They are used to refer you to a place -where more detailed information can be found on a particular subject. -Here is a cross reference which points to a node within the Texinfo -documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo -Manual}, for more information on creating your own texinfo cross -references. - -@node Selecting Xrefs -@section Selecting Xrefs - -The following table lists the Info commands which operate on menu items. - -@table @asis -@item @key{1} (@code{menu-digit}) -@itemx @key{2} @dots{} @key{9} -@itemx @key{M-1}, vi-like operation -@itemx @key{M-2} @dots{} @key{M-9}, vi-like operation -@cindex 1 @dots{} 9, in Info windows -@cindex M-1 @dots{} M-9, vi-like operation -@kindex 1 @dots{} 9, in Info windows -@kindex M-1 @dots{} M-9, vi-like operation -@findex menu-digit -Within an Info window, pressing a single digit, (such as @samp{1}), -selects that menu item, and places its node in the current window. -For convenience, there is one exception; pressing @samp{0} selects the -@emph{last} item in the node's menu. When @samp{--vi-keys} is in -effect, digits set the numeric argument, so these commands are remapped -to their @samp{M-} varieties. For example, to select the last menu -item, press @key{M-0}. - -@item @key{0} (@code{last-menu-item}) -@itemx @key{M-0}, vi-like operation -@kindex 0, in Info windows -@kindex M-0, vi-like operation -@findex last-menu-item -Select the last item in the current node's menu. - -@item @key{m} (@code{menu-item}) -@kindex m -@findex menu-item -Reads the name of a menu item in the echo area and selects its node. -Completion is available while reading the menu label. @xref{The Echo -Area, completion}. - -@item @kbd{M-x find-menu} -@findex find-menu -Move the cursor to the start of this node's menu. -@end table - -This table lists the Info commands which operate on cross references. - -@table @asis -@item @key{f} (@code{xref-item}) -@itemx @key{r} -@item @key{M-f}, vi-like operation -@itemx @kbd{C-x @key{r}}, vi-like operation -@kindex f -@kindex r -@kindex M-f, vi-like operation -@kindex C-x r, vi-like operation -@findex xref-item -Reads the name of a note cross reference in the echo area and selects -its node. Completion is available while reading the cross reference -label. @xref{The Echo Area, completion}. -@end table - -Finally, the next few commands operate on menu or note references alike: - -@table @asis -@item @key{TAB} (@code{move-to-next-xref}) -@kindex TAB, in Info windows -@findex move-to-next-xref -Move the cursor to the start of the next nearest menu item or note -reference in this node. You can then use @key{RET} -(@code{select-reference-this-line}) to select the menu or note reference. - -@item @key{M-TAB} (@code{move-to-prev-xref}) -@itemx @key{Shift-@key{TAB}} (on DOS/Windows only) -@kindex M-TAB, in Info windows -@findex move-to-prev-xref -Move the cursor the start of the nearest previous menu item or note -reference in this node. - -@kindex Shift-TAB, in Info windows -@kindex BackTab, in Info windows -On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for -@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. - -@item @key{RET} (@code{select-reference-this-line}) -@itemx @key{M-g}, vi-like operation -@kindex RET, in Info windows -@kindex M-g, vi-like operation -@findex select-reference-this-line -Select the menu item or note reference appearing on this line. -@end table - - -@node Window Commands -@chapter Manipulating Multiple Windows -@cindex windows, manipulating - -A @dfn{window} is a place to show the text of a node. Windows have a -view area where the text of the node is displayed, and an associated -@dfn{mode line}, which briefly describes the node being viewed. - -GNU Info supports multiple windows appearing in a single screen; each -window is separated from the next by its modeline. At any time, there -is only one @dfn{active} window, that is, the window in which the cursor -appears. There are commands available for creating windows, changing -the size of windows, selecting which window is active, and for deleting -windows. - -@menu -* The Mode Line:: What appears in the mode line? -* Basic Windows:: Manipulating windows in Info. -* The Echo Area:: Used for displaying errors and reading input. -@end menu - -@node The Mode Line -@section The Mode Line - -A @dfn{mode line} is a line of inverse video which appears at the bottom -of an Info window. It describes the contents of the window just above -it; this information includes the name of the file and node appearing in -that window, the number of screen lines it takes to display the node, -and the percentage of text that is above the top of the window. It can -also tell you if the indirect tags table for this Info file needs to be -updated, and whether or not the Info file was compressed when stored on -disk. - -Here is a sample mode line for a window containing an uncompressed file -named @file{dir}, showing the node @samp{Top}. - -@example -@group ------Info: (dir)Top, 40 lines --Top------------------------------------- - ^^ ^ ^^^ ^^ - (file)Node #lines where -@end group -@end example - -When a node comes from a file which is compressed on disk, this is -indicated in the mode line with two small @samp{z}'s. In addition, if -the Info file containing the node has been split into subfiles, the name -of the subfile containing the node appears in the modeline as well: - -@example ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z------------- -@end example - -Truncation of long lines (as opposed to wrapping them to the next -display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a -@samp{$} at the left edge of the mode line: - -@example ---$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1----------- -@end example - -When Info makes a node internally, such that there is no corresponding -info file on disk, the name of the node is surrounded by asterisks -(@samp{*}). The name itself tells you what the contents of the window -are; the sample mode line below shows an internally constructed node -showing possible completions: - -@example ------Info: *Completions*, 7 lines --All--------------------------------- -@end example - -@node Basic Windows -@section Window Commands - -It can be convenient to view more than one node at a time. To allow -this, Info can display more than one @dfn{window}. Each window has its -own mode line (@pxref{The Mode Line}) and history of nodes viewed in that -window (@pxref{Node Commands, , @code{history-node}}). - -@table @asis -@item @kbd{C-x @key{o}} (@code{next-window}) -@cindex windows, selecting -@kindex C-x o -@findex next-window -Select the next window on the screen. Note that the echo area can only be -selected if it is already in use, and you have left it temporarily. -Normally, @samp{C-x o} simply moves the cursor into the next window on -the screen, or if you are already within the last window, into the first -window on the screen. Given a numeric argument, @samp{C-x o} moves over -that many windows. A negative argument causes @samp{C-x o} to select -the previous window on the screen. - -@item @kbd{M-x prev-window} -@findex prev-window -Select the previous window on the screen. This is identical to -@samp{C-x o} with a negative argument. - -@item @kbd{C-x @key{2}} (@code{split-window}) -@cindex windows, creating -@kindex C-x 2 -@findex split-window -Split the current window into two windows, both showing the same node. -Each window is one half the size of the original window, and the cursor -remains in the original window. The variable @code{automatic-tiling} -can cause all of the windows on the screen to be resized for you -automatically (@pxref{Variables, , automatic-tiling}). - -@item @kbd{C-x @key{0}} (@code{delete-window}) -@cindex windows, deleting -@kindex C-x 0 -@findex delete-window -Delete the current window from the screen. If you have made too many -windows and your screen appears cluttered, this is the way to get rid of -some of them. - -@item @kbd{C-x @key{1}} (@code{keep-one-window}) -@kindex C-x 1 -@findex keep-one-window -Delete all of the windows excepting the current one. - -@item @kbd{ESC @key{C-v}} (@code{scroll-other-window}) -@kindex ESC C-v, in Info windows -@findex scroll-other-window -Scroll the other window, in the same fashion that @samp{C-v} might -scroll the current window. Given a negative argument, scroll the -``other'' window backward. - -@item @kbd{C-x @key{^}} (@code{grow-window}) -@kindex C-x ^ -@findex grow-window -Grow (or shrink) the current window. Given a numeric argument, grow -the current window that many lines; with a negative numeric argument, -shrink the window instead. - -@item @kbd{C-x @key{t}} (@code{tile-windows}) -@cindex tiling -@kindex C-x t -@findex tile-windows -Divide the available screen space among all of the visible windows. -Each window is given an equal portion of the screen in which to display -its contents. The variable @code{automatic-tiling} can cause -@code{tile-windows} to be called when a window is created or deleted. -@xref{Variables, , @code{automatic-tiling}}. -@end table - -@node The Echo Area -@section The Echo Area -@cindex echo area - -The @dfn{echo area} is a one line window which appears at the bottom of -the screen. It is used to display informative or error messages, and to -read lines of input from you when that is necessary. Almost all of the -commands available in the echo area are identical to their Emacs -counterparts, so please refer to that documentation for greater depth of -discussion on the concepts of editing a line of text. The following -table briefly lists the commands that are available while input is being -read in the echo area: - -@table @asis -@item @key{C-f} (@code{echo-area-forward}) -@itemx @key{RIGHT} (an arrow key) -@itemx @key{M-h}, vi-like operation -@kindex C-f, in the echo area -@kindex RIGHT, in the echo area -@kindex M-h, in the echo area, vi-like operation -@findex echo-area-forward -Move forward a character. - -@item @key{C-b} (@code{echo-area-backward}) -@itemx @key{LEFT} (an arrow key) -@itemx @key{M-l}, vi-like operation -@kindex LEFT, in the echo area -@kindex C-b, in the echo area -@kindex M-l, in the echo area, vi-like operation -@findex echo-area-backward -Move backward a character. - -@item @key{C-a} (@code{echo-area-beg-of-line}) -@itemx @key{M-0}, vi-like operation -@kindex C-a, in the echo area -@kindex M-0, in the echo area, vi-like operation -@findex echo-area-beg-of-line -Move to the start of the input line. - -@item @key{C-e} (@code{echo-area-end-of-line}) -@itemx @key{M-$}, vi-like operation -@kindex C-e, in the echo area -@kindex M-$, vi-like operation -@findex echo-area-end-of-line -Move to the end of the input line. - -@item @key{M-f} (@code{echo-area-forward-word}) -@itemx @key{C-@key{RIGHT}} (DOS/Windows only) -@itemx @key{M-w}, vi-like operation -@kindex M-f, in the echo area -@kindex M-w, in the echo area, vi-like operation -@findex echo-area-forward-word -Move forward a word. - -@kindex C-RIGHT, in the echo area -On DOS/Windows, @kbd{C-@key{RIGHT}} moves forward by words. - -@item @key{M-b} (@code{echo-area-backward-word}) -@itemx @key{C-@key{LEFT}} (DOS/Windows only) -@kindex M-b, in the echo area -@findex echo-area-backward-word -Move backward a word. - -@kindex C-LEFT, in the echo area -On DOS/Windows, @kbd{C-@key{LEFT}} moves backward by words. - -@item @key{C-d} (@code{echo-area-delete}) -@itemx @key{M-x}, vi-like operation -@kindex C-d, in the echo area -@kindex M-x, in the echo area, vi-like operation -@findex echo-area-delete -Delete the character under the cursor. - -@item @key{DEL} (@code{echo-area-rubout}) -@kindex DEL, in the echo area -@findex echo-area-rubout -Delete the character behind the cursor. - -On some keyboards, this key is designated @key{BS}, for -@samp{BackSpace}. Those keyboards will usually bind @key{DEL} in the -echo area to @code{echo-area-delete}. - -@item @key{C-g} (@code{echo-area-abort}) -@itemx @key{C-u}, vi-like operation -@kindex C-g, in the echo area -@kindex C-u, in the echo area, vi-like operation -@findex echo-area-abort -Cancel or quit the current operation. If completion is being read, this -command discards the text of the input line which does not match any -completion. If the input line is empty, it aborts the calling function. - -@item @key{RET} (@code{echo-area-newline}) -@kindex RET, in the echo area -@findex echo-area-newline -Accept (or forces completion of) the current input line. - -@item @key{C-q} (@code{echo-area-quoted-insert}) -@itemx @key{C-v}, vi-like operation -@kindex C-q, in the echo area -@kindex C-v, in the echo area, vi-like operation -@findex echo-area-quoted-insert -Insert the next character verbatim. This is how you can insert control -characters into a search string, for example, or the @samp{?} character -when Info prompts with completion. - -@item @var{printing character} (@code{echo-area-insert}) -@kindex printing characters, in the echo area -@findex echo-area-insert -Insert the character. Characters that have their 8th bit set, and not -bound to @samp{M-} commands, are also inserted verbatim; this is useful -for terminals which support Latin scripts. - -@item @key{M-TAB} (@code{echo-area-tab-insert}) -@itemx @key{Shift-@key{TAB}} (on DOS/Windows only) -@kindex M-TAB, in the echo area -@kindex Shift-TAB, in the echo area -@findex echo-area-tab-insert -Insert a TAB character. - -@kindex Shift-TAB, in the echo area -@kindex BackTab, in the echo area -On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for -@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. - -@item @key{C-t} (@code{echo-area-transpose-chars}) -@kindex C-t, in the echo area -@findex echo-area-transpose-chars -Transpose the characters at the cursor. -@end table - -The next group of commands deal with @dfn{killing}, and @dfn{yanking} -text@footnote{ -Some people are used to calling these operations @dfn{cut} and -@dfn{paste}, respectively.}. For an in-depth discussion of killing and -yanking, see @ref{Killing, , Killing and Deleting, emacs, the GNU Emacs -Manual}. - -@table @asis -@item @key{M-d} (@code{echo-area-kill-word}) -@itemx @key{M-X}, vi-like operation -@kindex M-d, in the echo area -@kindex M-X, in the echo area, vi-like operation -@findex echo-area-kill-word -Kill the word following the cursor. - -@item @key{M-DEL} (@code{echo-area-backward-kill-word}) -@itemx @key{M-@key{BS}} -@kindex M-DEL, in the echo area -@findex echo-area-backward-kill-word -Kill the word preceding the cursor. - -@kindex M-BS, in the echo area -On some keyboards, the @code{Backspace} key is used instead of -@code{DEL}, so @code{M-@key{Backspace}} has the same effect as -@code{M-@key{DEL}}. - -@item @key{C-k} (@code{echo-area-kill-line}) -@kindex C-k, in the echo area -@findex echo-area-kill-line -Kill the text from the cursor to the end of the line. - -@item @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line}) -@kindex C-x DEL, in the echo area -@findex echo-area-backward-kill-line -Kill the text from the cursor to the beginning of the line. - -@item @key{C-y} (@code{echo-area-yank}) -@kindex C-y, in the echo area -@findex echo-area-yank -Yank back the contents of the last kill. - -@item @key{M-y} (@code{echo-area-yank-pop}) -@kindex M-y, in the echo area -@findex echo-area-yank-pop -Yank back a previous kill, removing the last yanked text first. -@end table - -@cindex completion -Sometimes when reading input in the echo area, the command that needed -input will only accept one of a list of several choices. The choices -represent the @dfn{possible completions}, and you must respond with one -of them. Since there are a limited number of responses you can make, -Info allows you to abbreviate what you type, only typing as much of the -response as is necessary to uniquely identify it. In addition, you can -request Info to fill in as much of the response as is possible; this -is called @dfn{completion}. - -The following commands are available when completing in the echo area: - -@table @asis -@item @key{TAB} (@code{echo-area-complete}) -@itemx @key{SPC} -@kindex TAB, in the echo area -@kindex SPC, in the echo area -@findex echo-area-complete -Insert as much of a completion as is possible. - -@item @key{?} (@code{echo-area-possible-completions}) -@kindex ?, in the echo area -@findex echo-area-possible-completions -Display a window containing a list of the possible completions of what -you have typed so far. For example, if the available choices are: - -@example -@group -bar -foliate -food -forget -@end group -@end example - -@noindent -and you have typed an @samp{f}, followed by @samp{?}, Info will pop up a -window showing a node called @samp{*Completions*} which lists the -possible completions like this: - -@example -@group -3 completions: -foliate food -forget -@end group -@end example - -@noindent -i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} -or @key{TAB} would result in @samp{fo} appearing in the echo area, since -all of the choices which begin with @samp{f} continue with @samp{o}. -Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} -appearing in the echo area, since that is the only choice which begins -with @samp{fol}. - -@item @key{ESC C-v} (@code{echo-area-scroll-completions-window}) -@kindex ESC C-v, in the echo area -@findex echo-area-scroll-completions-window -Scroll the completions window, if that is visible, or the ``other'' -window if not. -@end table - - -@node Printing Nodes -@chapter Printing Nodes -@cindex printing - -In general, we recommend that you use @TeX{} to format the document and -print sections of it, by running @code{tex} on the Texinfo source file. -However, you may wish to print out the contents of a node as a quick -reference document for later use, or if you don't have @TeX{} installed. -Info provides you with a command for doing this. - -@table @asis -@item @kbd{M-x print-node} -@findex print-node -@cindex INFO_PRINT_COMMAND, environment variable -Pipe the contents of the current node through the command in the -environment variable @code{INFO_PRINT_COMMAND}. If the variable does not -exist, the node is simply piped to @code{lpr} (on DOS/Windows, the -default is to print the node to the local printer device, @file{PRN}). - -@cindex printing nodes to the local printer -@cindex local printer device -The value of @code{INFO_PRINT_COMMAND} may begin with the @samp{>} -character, as in @samp{>/dev/printer}, in which case Info treats the -rest as the name of a file or a device. Instead of piping to a command, -Info opens the file, writes the node contents, and closes the file, -under the assumption that text written to that file will be printed by -the underlying OS. -@end table - - -@node Miscellaneous Commands -@chapter Miscellaneous Commands - -GNU Info contains several commands which self-document GNU Info: - -@table @asis -@item @kbd{M-x describe-command} -@cindex functions, describing -@cindex commands, describing -@findex describe-command -Read the name of an Info command in the echo area and then display a -brief description of what that command does. - -@item @kbd{M-x describe-key} -@cindex keys, describing -@findex describe-key -Read a key sequence in the echo area, and then display the name and -documentation of the Info command that the key sequence invokes. - -@item @kbd{M-x describe-variable} -Read the name of a variable in the echo area and then display a brief -description of what the variable affects. - -@item @kbd{M-x where-is} -@findex where-is -Read the name of an Info command in the echo area, and then display -a key sequence which can be typed in order to invoke that command. - -@item @key{C-h} (@code{get-help-window}) -@itemx @key{?} -@itemx @key{F1} (on DOS/Windows only) -@itemx h, vi-like operation -@kindex C-h -@kindex ?, in Info windows -@kindex F1 -@kindex h, vi-like operation -@findex get-help-window -Create (or Move into) the window displaying @code{*Help*}, and place -a node containing a quick reference card into it. This window displays -the most concise information about GNU Info available. - -@item @key{h} (@code{get-info-help-node}) -@itemx @key{M-h}, vi-like operation -@kindex h -@kindex M-h, vi-like operation -@findex get-info-help-node -Try hard to visit the node @code{(info)Help}. The Info file -@file{info.texi} distributed with GNU Info contains this node. Of -course, the file must first be processed with @code{makeinfo}, and then -placed into the location of your Info directory. -@end table - -Here are the commands for creating a numeric argument: - -@table @asis -@item @key{C-u} (@code{universal-argument}) -@cindex numeric arguments -@kindex C-u -@findex universal-argument -Start (or multiply by 4) the current numeric argument. @samp{C-u} is -a good way to give a small numeric argument to cursor movement or -scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while -@samp{C-u C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed -by digit keys sets the numeric argument to the number thus typed: -@kbd{C-u 1 2 0} sets the argument to 120. - -@item @key{M-1} (@code{add-digit-to-numeric-arg}) -@itemx @key{1}, vi-like operation -@itemx @key{M-2} @dots{} @key{M-9} -@itemx @key{2} @dots{} @key{9}, vi-like operation -@itemx @key{M-0} -@itemx @key{0}, vi-like operation -@kindex M-0 @dots{} M-9 -@kindex 0 @dots{} 9, vi-like operation -@findex add-digit-to-numeric-arg -Add the digit value of the invoking key to the current numeric -argument. Once Info is reading a numeric argument, you may just type -the digits of the argument, without the Meta prefix. For example, you -might give @samp{C-l} a numeric argument of 32 by typing: - -@example -@kbd{C-u 3 2 C-l} -@end example - -@noindent -or - -@example -@kbd{M-3 2 C-l} -@end example - -@item @key{M--} (@code{add-digit-to-numeric-arg} -@itemx @key{-} -@kindex M-- -@kindex - -@cindex negative arguments -@cindex arguments, negative -@cindex numeric arguments, negative -To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes a -negative argument with a value of -1. If you continue to type digit or -Meta-digit keys after @kbd{-}, the result is a negative number produced -by those digits. - -@kbd{-} doesn't work when you type in the echo area, because you need to -be able to insert the @samp{-} character itself; use @kbd{M--} instead, -if you need to specify negative arguments in the echo area. -@end table - -@samp{C-g} is used to abort the reading of a multi-character key -sequence, to cancel lengthy operations (such as multi-file searches) and -to cancel reading input in the echo area. - -@table @asis -@item @key{C-g} (@code{abort-key}) -@itemx @key{C-u}, vi-like operation -@cindex cancelling typeahead -@cindex cancelling the current operation -@kindex C-g, in Info windows -@kindex C-u cancels typeahead, vi-like operation -@findex abort-key -Cancel current operation. -@end table - -The @samp{q} command of Info simply quits running Info. Under -@samp{--vi-keys} (@pxref{--vi-keys}), you can also exit with @samp{:q} -or @samp{ZZ}. - -@table @asis -@item @key{q} (@code{quit}) -@itemx @kbd{C-x C-c} -@itemx @kbd{:q}, vi-like operation -@itemx @kbd{ZZ}, vi-like operation -@cindex quitting -@kindex q -@kindex C-x C-c -@kindex ZZ, vi-like operation -@findex quit -Exit GNU Info. -@end table - -If the operating system tells GNU Info that the screen is 60 lines tall, -and it is actually only 40 lines tall, here is a way to tell Info that -the operating system is correct. - -@table @asis -@item @kbd{M-x set-screen-height} -@findex set-screen-height -@cindex screen, changing the height of -Read a height value in the echo area and set the height of the -displayed screen to that value. -@end table - -On MS-DOS/MS-Windows, this command actually tries to change the -dimensions of the visible screen to the value you type in the echo -area. - -Finally, Info provides a convenient way to display footnotes which might -be associated with the current node that you are viewing: - -@table @asis -@item @key{ESC C-f} (@code{show-footnotes}) -@kindex ESC C-f -@findex show-footnotes -@cindex footnotes, displaying -Show the footnotes (if any) associated with the current node in another -window. You can have Info automatically display the footnotes -associated with a node when the node is selected by setting the variable -@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}. -@end table - - -@node Variables -@chapter Manipulating Variables - -GNU Info contains several @dfn{variables} whose values are looked at by -various Info commands. You can change the values of these variables, -and thus change the behavior of Info to more closely match your -environment and Info file reading manner. - -There are two ways to set the value of a variable: interactively, using -the @code{set-variable} command described below, or in the @code{#var} -section of the @code{.infokey} file. @xref{Custom Key Bindings}. - -@table @asis -@item @kbd{M-x set-variable} -@cindex variables, setting -@findex set-variable -Read the name of a variable, and the value for it, in the echo area and -then set the variable to that value. Completion is available when -reading the variable name (@pxref{The Echo Area, completion}); often, -completion is available when reading the value to give to the variable, -but that depends on the variable itself. If a variable does @emph{not} -supply multiple choices to complete over, it expects a numeric value. - -@item @kbd{M-x describe-variable} -@cindex variables, describing -@findex describe-variable -Read the name of a variable in the echo area and then display a brief -description of what the variable affects. -@end table - -Here is a list of the variables that you can set in Info. - -@table @code -@item automatic-footnotes -@vindex automatic-footnotes -When set to @code{On}, footnotes appear and disappear automatically; -else, they appear at the bottom of the node text. This variable is -@code{Off} by default. When a node is selected, a window containing -the footnotes which appear in that node is created, and the footnotes -are displayed within the new window. The window that Info creates to -contain the footnotes is called @samp{*Footnotes*}. If a node is -selected which contains no footnotes, and a @samp{*Footnotes*} window -is on the screen, the @samp{*Footnotes*} window is deleted. Footnote -windows created in this fashion are not automatically tiled so that -they can use as little of the display as is possible. - -@item automatic-tiling -@vindex automatic-tiling -When set to @code{On}, creating or deleting a window resizes other -windows. This variable is @code{Off} by default. Normally, typing -@samp{C-x 2} divides the current window into two equal parts. When -@code{automatic-tiling} is set to @code{On}, all of the windows are -resized automatically, keeping an equal number of lines visible in each -window. There are exceptions to the automatic tiling; specifically, the -windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} -resized through automatic tiling; they remain their original size. - -@anchor{cursor-movement-scrolls} -@item cursor-movement-scrolls -Normally, cursor movement commands (@pxref{Cursor Commands}) stop when -top or bottom of a node is reached. When this variable is set to -@code{On}, cursor movement commands act as scrolling ones and their -behavior is controlled by the @code{scroll-behavior} variable (see below). - -@item errors-ring-bell -@vindex errors-ring-bell -When set to @code{On}, errors cause the bell to ring. The default -setting of this variable is @code{On}. - -@item gc-compressed-files -@vindex gc-compressed-files -When set to @code{On}, Info garbage collects files which had to be -uncompressed. The default value of this variable is @code{Off}. -Whenever a node is visited in Info, the Info file containing that node -is read into core, and Info reads information about the tags and nodes -contained in that file. Once the tags information is read by Info, it -is never forgotten. However, the actual text of the nodes does not need -to remain in core unless a particular Info window needs it. For -non-compressed files, the text of the nodes does not remain in core when -it is no longer in use. But de-compressing a file can be a time -consuming operation, and so Info tries hard not to do it twice. -@code{gc-compressed-files} tells Info it is okay to garbage collect the -text of the nodes of a file which was compressed on disk. - -@item ISO-Latin -@cindex ISO Latin characters -@vindex ISO-Latin -When set to @code{On}, Info accepts and displays ISO Latin characters. -By default, Info assumes an ASCII character set. @code{ISO-Latin} tells -Info that it is running in an environment where the European standard -character set is in use, and allows you to input such characters to -Info, as well as display them. - -@anchor{scroll-behavior} -@item scroll-behavior -@itemx scroll-behaviour -@vindex scroll-behavior -@vindex scroll-behaviour -Control what happens when forward scrolling is requested at the end of -a node, or when backward scrolling is requested at the beginning of a -node. The default value for this variable is @code{Continuous}. -There are three possible values for this variable: - -@table @code -@item Continuous -Try to get the first item in this node's menu, or failing that, the -@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. -This behavior is identical to using the @samp{]} -(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) -commands. - -@item scroll-last-node -@vindex scroll-last-node -Control what happens when a scrolling command is issued at the end of -the last node. Possible values are: - -@table @code -@item Stop -Do not scroll. Display the @samp{No more nodes within this document.} -message. This is the default. - -@item Scroll -Scroll as usual. Since the last node is usually an index, this means -that the very first node from the menu will be selected. - -@item Top -Go to the top node of this document. -@end table - -This variable is in effect only if @code{scroll-behaviour} is set to -@code{Continuous}. - -Notice that the default behavior has changed in version 4.12. Previous -versions behaved as if @code{scroll-last-node=Scroll} was set. This -behavior was counter-intuitive, therefore since version 4.12 the -default is to stop at the last node. - -@item Next Only -Only try to get the @samp{Next} node. - -@item Page Only -Simply give up, changing nothing. If @code{scroll-behavior} is -@code{Page Only}, no scrolling command can change the node that is being -viewed. -@end table - -This variable normally affects only scrolling commands. -@xref{cursor-movement-scrolls}, for information on how to widen its -scope. - -The two names, @code{scroll-behavior} and @code{scroll-behaviour}, are -a historical accident. They are merely synonyms. - -@item scroll-step -@vindex scroll-step -The number of lines to scroll when the cursor moves out of the window. -Scrolling happens automatically if the cursor has moved out of the -visible portion of the node text when it is time to display. Usually -the scrolling is done so as to put the cursor on the center line of the -current window. However, if the variable @code{scroll-step} has a -nonzero value, Info attempts to scroll the node text by that many lines; -if that is enough to bring the cursor back into the window, that is what -is done. The default value of this variable is 0, thus placing the -cursor (and the text it is attached to) in the center of the window. -Setting this variable to 1 causes a kind of ``smooth scrolling'' which -some people prefer. - -@item show-index-match -@vindex show-index-match -When set to @code{On}, the portion of the matched search string is -highlighted in the message which explains where the matched search -string was found. The default value of this variable is @code{On}. -When Info displays the location where an index match was found, -(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the -string that you had typed is highlighted by displaying it in the inverse -case from its surrounding characters. - -@item visible-bell -@vindex visible-bell -When set to @code{On}, GNU Info attempts to flash the screen instead of -ringing the bell. This variable is @code{Off} by default. Of course, -Info can only flash the screen if the terminal allows it; in the case -that the terminal does not allow it, the setting of this variable has no -effect. However, you can make Info perform quietly by setting the -@code{errors-ring-bell} variable to @code{Off}. - -@end table - - -@node Custom Key Bindings -@chapter Customizing Key Bindings and Variables - -@cindex default key bindings, overriding -@cindex overriding default key bindings -@cindex customizing key bindings -@cindex key bindings, customizing -@cindex infokey -@cindex .info -@cindex .infokey -@cindex _info file (MS-DOS) - -GNU Info provides a way to define arbitrary key-to-command bindings -and variable settings, overriding the defaults described in this -document. (The @option{--vi-keys} option rebinds many keys at once; -@pxref{--vi-keys}.) - -On startup, GNU Info looks for a configuration file in the invoker's -HOME directory called @file{.info}@footnote{Due to the limitations of -DOS filesystems, the MS-DOS version of Info looks for a file -@file{_info} instead. If the @env{HOME} variable is not defined, Info -additionally looks in the current directory.}. If it is present, and -appears to contain Info configuration data, and was created with the -current version of the @code{infokey} command, then Info adopts the -key bindings and variable settings contained therein. - -The @file{.info} file contains compact, non-textual data for reasons of -efficiency and because its design was lifted wholesale from the GNU Less -program, which also does it that way. It must be created by compiling a -textual source file using the @code{infokey} command. - -@menu -* Invoking infokey:: -* infokey source format:: -@end menu - - -@node Invoking infokey -@section Invoking @command{infokey} - -@cindex invoking infokey -@cindex infokey, invoking -@cindex _infokey file (MS-DOS) - -@command{infokey} compiles a source file -(@file{$HOME/.infokey}@footnote{This file is named @file{_infokey} in -the MS-DOS version, and is looked for in the current directory if -@env{HOME} is undefined.} by default) containing Info customizations -into a binary format (@file{$HOME/.info} by default). GNU Info reads -the binary file at startup to override the default key bindings and -variable definitions. Synopsis: - -@example -infokey [@var{option}@dots{}] [@var{input-file}] -@end example - -Besides the standard @option{--help} and @option{--version}, the only -option is @option{--output @var{file}}. This tells @command{infokey} to -write the binary data to @var{file} instead of @file{$HOME/.info}. - - -@node infokey source format -@section @command{infokey} source format - -@cindex infokey source format -@cindex .infokey source format -@cindex format of .infokey source - -The format of the source file read by @command{infokey} is most easily -illustrated by example. For instance, here is a sample @file{.infokey} -source file suitable for aficionados of @command{vi} or @command{less}: - -@example -#info -j next-line -k prev-line -l forward-char -h backward-char -\kd next-line -\ku prev-line -\kr forward-char -\kl backward-char -\ scroll-forward -\kD scroll-forward-page-only -b scroll-backward -\kU scroll-backward-page-only -g beginning-of-node -\kh beginning-of-node -G end-of-node -\ke end-of-node -\t select-reference-this-line -- history-node -n next-node -p prev-node -u up-node -t top-node -d dir-node -#var -scroll-step=1 -@end example - -The source file consists of one or more @dfn{sections}. -Each section starts with a line that identifies the type of section. -Possible sections are: - -@table @code -@item #info -Key bindings for Info windows. -The start of this section is indicated by a line containing just -@code{#info} by itself. If this is the first section in the source -file, the @code{#info} line can be omitted. The rest of this section -consists of lines of the form: - -@example -@var{string} whitespace @var{action} [ whitespace [ # comment ] ] newline -@end example - -Whitespace is any sequence of one or more spaces and/or tabs. Comment -is any sequence of any characters, excluding newline. @var{string} is -the key sequence which invokes the action. @var{action} is the name of -an Info command. The characters in @var{string} are interpreted -literally or prefixed by a caret (@code{^}) to indicate a control -character. A backslash followed by certain characters specifies input -keystrokes as follows: - -@table @code -@item \b -Backspace -@item \e -Escape (ESC) -@item \n -Newline -@item \r -Return -@item \t -Tab -@item \ku -Up arrow -@item \kd -Down arrow -@item \kl -Left arrow -@item \kr -Right arrow -@item \kU -Page Up -@item \kD -Page Down -@item \kh -HOME -@item \ke -END -@item \kx -Delete (DEL) -@item \m@var{x} -Meta-@var{x} where @var{x} is any character as described above. -@end table - -Backslash followed by any other character indicates that character is to -be taken literally. Characters which must be preceded by a backslash -include caret, space, tab, and backslash itself. - -@item #echo-area -Key bindings for the echo area. -The start of this section is indicated by a line containing just -@code{#echo-area} by itself. The rest of this section has a syntax -identical to that for the key definitions for the Info area, described -above. - -@item #var -Variable initializations. -The start of this section is indicated by a line containing just -@code{#var} by itself. Following this line is a list of variable -assignments, one per line. Each line consists of a variable name -(@xref{Variables},) followed by @code{=} followed by a value. -There may be no white space between the variable name and the @code{=}, -and all characters following the @code{=}, including white space, -are included in the value. -@end table - -Blank lines and lines starting with @code{#} are ignored, except for -the special section header lines. - -Key bindings defined in the @file{.info} file take precedence over GNU -Info's default key bindings, whether or not @samp{--vi-keys} is used. A -default key binding may be disabled by overriding it in the @file{.info} -file with the action @code{invalid}. In addition, @emph{all} default -key bindings can be disabled by adding this line @emph{anywhere} in the -relevant section: - -@example -#stop -@end example - -This will cause GNU Info to ignore all the default key commands for that -section. - -Beware: @code{#stop} can be dangerous. Since it disables all default -key bindings, you must supply enough new key bindings to enable all -necessary actions. Failure to bind any key to the @code{quit} command, -for example, can lead to frustration. - -The order in which key bindings are defined in the @file{.info} file is -not important, except that the command summary produced by the -@code{get-help-window} command only displays the @emph{first} key that -is bound to each command. - - -@c the following is incomplete -@ignore -@c node Info for Sys Admins -@c chapter Info for System Administrators - -This text describes some common ways of setting up an Info hierarchy -from scratch, and details the various options that are available when -installing Info. This text is designed for the person who is installing -GNU Info on the system; although users may find the information present -in this section interesting, none of it is vital to understanding how to -use GNU Info. - -@menu -* Setting the INFOPATH:: Where are my Info files kept? -* Editing the DIR node:: What goes in `DIR', and why? -* Storing Info files:: Alternate formats allow flexibility in setups. -* Using `localdir':: Building DIR on the fly. -* Example setups:: Some common ways to organize Info files. -@end menu - -@c node Setting the INFOPATH -@c section Setting the INFOPATH - -Where are my Info files kept? - -@c node Editing the DIR node -@c section Editing the DIR node - -What goes in `DIR', and why? - -@c node Storing Info files -@c section Storing Info files - -Alternate formats allow flexibility in setups. - -@c node Using `localdir' -@c section Using `localdir' - -Building DIR on the fly. - -@c node Example setups -@c section Example setups - -Some common ways to organize Info files. -@end ignore - - -@node Index -@appendix Index - -@printindex cp - -@bye diff --git a/Build/source/utils/texinfo/doc/info.1 b/Build/source/utils/texinfo/doc/info.1 deleted file mode 100644 index aadae61022c..00000000000 --- a/Build/source/utils/texinfo/doc/info.1 +++ /dev/null @@ -1,93 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH INFO "1" "April 2008" "info 4.12" "User Commands" -.SH NAME -info \- read Info documents -.SH SYNOPSIS -.B info -[\fIOPTION\fR]... [\fIMENU-ITEM\fR...] -.SH DESCRIPTION -Read documentation in Info format. -.SH OPTIONS -.TP -\fB\-k\fR, \fB\-\-apropos\fR=\fISTRING\fR -look up STRING in all indices of all manuals. -.TP -\fB\-d\fR, \fB\-\-directory\fR=\fIDIR\fR -add DIR to INFOPATH. -.TP -\fB\-\-dribble\fR=\fIFILENAME\fR -remember user keystrokes in FILENAME. -.TP -\fB\-f\fR, \fB\-\-file\fR=\fIFILENAME\fR -specify Info file to visit. -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-index\-search\fR=\fISTRING\fR -go to node pointed by index entry STRING. -.TP -\fB\-n\fR, \fB\-\-node\fR=\fINODENAME\fR -specify nodes in first visited Info file. -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIFILENAME\fR -output selected nodes to FILENAME. -.TP -\fB\-R\fR, \fB\-\-raw\-escapes\fR -output "raw" ANSI escapes (default). -.TP -\fB\-\-no\-raw\-escapes\fR -output escapes as literal text. -.TP -\fB\-\-restore\fR=\fIFILENAME\fR -read initial keystrokes from FILENAME. -.TP -\fB\-O\fR, \fB\-\-show\-options\fR, \fB\-\-usage\fR -go to command\-line options node. -.TP -\fB\-\-subnodes\fR -recursively output menu items. -.TP -\fB\-\-vi\-keys\fR -use vi\-like and less\-like key bindings. -.TP -\fB\-\-version\fR -display version information and exit. -.TP -\fB\-w\fR, \fB\-\-where\fR, \fB\-\-location\fR -print physical location of Info file. -.PP -The first non\-option argument, if present, is the menu entry to start from; -it is searched for in all `dir' files along INFOPATH. -If it is not present, info merges all `dir' files and shows the result. -Any remaining arguments are treated as the names of menu -items relative to the initial node visited. -.SH EXAMPLES -.TP -info -show top\-level dir menu -.TP -info emacs -start at emacs node from top\-level dir -.TP -info emacs buffers -start at buffers node within emacs manual -.TP -info \fB\-\-show\-options\fR emacs -start at node with emacs' command line options -.TP -info \fB\-\-subnodes\fR \fB\-o\fR out.txt emacs -dump entire manual to out.txt -.TP -info \fB\-f\fR ./foo.info -show file ./foo.info, not searching dir -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. diff --git a/Build/source/utils/texinfo/doc/info.5 b/Build/source/utils/texinfo/doc/info.5 deleted file mode 100644 index 488d2a107ac..00000000000 --- a/Build/source/utils/texinfo/doc/info.5 +++ /dev/null @@ -1,72 +0,0 @@ -.\" info(5) -.\" $Id: info.5,v 1.3 2005/01/20 22:38:32 karl Exp $ -.\" -.\" Copyright (C) 1998 Free Software Foundation, Inc. -.\" -.\" Permission is granted to make and distribute verbatim copies of this -.\" manual provided the copyright notice and this permission notice are -.\" preserved on all copies. -.\" -.\" Permission is granted to copy and distribute modified versions of -.\" this manual under the conditions for verbatim copying, provided that -.\" the entire resulting derived work is distributed under the terms of a -.\" permission notice identical to this one. -.\" -.\" Permission is granted to copy and distribute translations of this -.\" manual into another language, under the above conditions for modified -.\" versions, except that this permission notice may be stated in a -.\" translation approved by the Foundation. -.\" -.de EX -.nf -.ft CW -.in +5 -.. -.de EE -.in -5 -.ft R -.fi -.. -.TH INFO 5 "GNU Info" "FSF" -.SH NAME -info \- readable online documentation -.SH DESCRIPTION -The Info file format is an easily-parsable representation for online -documents. It can be read by -.I emacs(1) -and -.I info(1) -among other programs. -.PP -Info files are usually created from -.I texinfo(5) -sources by -.IR makeinfo(1) , -but can be created from scratch if so desired. -.PP -For a full description of the Texinfo language and associated tools, -please see the Texinfo manual (written in Texinfo itself). Most likely, -running this command from your shell: -.EX -info texinfo -.EE -or this key sequence from inside Emacs: -.EX -M-x info RET m texinfo RET -.EE -will get you there. -.SH AVAILABILITY -ftp://ftp.gnu.org/pub/gnu/texinfo-<version>.tar.gz -.br -or any GNU mirror site. -.SH "REPORTING BUGS" -Please send bug reports to bug-texinfo@gnu.org, -general questions and discussion to help-texinfo@gnu.org. -.SH "SEE ALSO" -info(1), install-info(1), makeinfo(1), texi2dvi(1), -.br -texindex(1). -.br -emacs(1), tex(1). -.br -texinfo(5). diff --git a/Build/source/utils/texinfo/doc/info.texi b/Build/source/utils/texinfo/doc/info.texi deleted file mode 100644 index 89229d61cd7..00000000000 --- a/Build/source/utils/texinfo/doc/info.texi +++ /dev/null @@ -1,1510 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c We must \input texinfo.tex instead of texinfo, otherwise make -@c distcheck in the Texinfo distribution fails, because the texinfo Info -@c file is made first, and texi2dvi must include . first in the path. -@comment %**start of header -@setfilename info.info -@settitle Info -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This file describes how to use Info, the on-line, menu-driven GNU -documentation system. - -Copyright @copyright{} 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, -2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and -modify this GNU Manual, like GNU software. Buying copies from GNU -Press supports the FSF in developing GNU and promoting software -freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* Info: (info). How to use the documentation browsing system. -@end direntry - -@titlepage -@title Info -@subtitle The online, hyper-text GNU documentation system -@author Brian Fox -@author and the GNU Texinfo community -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Info: An Introduction - -The GNU Project distributes most of its on-line manuals in the -@dfn{Info format}, which you read using an @dfn{Info reader}. You are -probably using an Info reader to read this now. - -There are two primary Info readers: @code{info}, a stand-alone program -designed just to read Info files, and the @code{info} package in GNU -Emacs, a general-purpose editor. At present, only the Emacs reader -supports using a mouse. - -@ifinfo -If you are new to the Info reader and want to learn how to use it, -type the command @kbd{h} now. It brings you to a programmed -instruction sequence. - -To read about advanced Info commands, type @kbd{n} twice. This -brings you to @cite{Advanced Info Commands}, skipping over the `Getting -Started' chapter. -@end ifinfo -@end ifnottex - -@menu -* Getting Started:: Getting started using an Info reader. -* Advanced:: Advanced Info commands. -* Expert Info:: Info commands for experts. -* Index:: An index of topics, commands, and variables. -@end menu - -@node Getting Started, Advanced, Top, Top -@comment node-name, next, previous, up -@chapter Getting Started - -This first part of this Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced -Info commands. The third part briefly explains how to generate Info -files from Texinfo files, and describes how to write an Info file -by hand. - -@ifnotinfo -This manual is primarily designed for browsing with an Info reader -program on a computer, so that you can try Info commands while reading -about them. Reading it on paper or with an HTML browser is less -effective, since you must take it on faith that the commands described -really do what the manual says. By all means go through this manual -now that you have it; but please try going through the on-line version -as well. - -@cindex Info reader, how to invoke -@cindex entering Info -There are two ways of looking at the online version of this manual: - -@enumerate -@item -Type @code{info} at your shell's command line. This approach uses a -stand-alone program designed just to read Info files. - -@item -Type @code{emacs} at the command line; then type @kbd{C-h i} -(@kbd{Control-h}, followed by @kbd{i}). This approach uses the Info -mode of the Emacs editor. -@end enumerate - -In either case, then type @kbd{mInfo} (just the letters), followed by -@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should -be ready to follow the instructions in this manual as you read them on -the screen. -@c FIXME! (pesch@cygnus.com, 14 dec 1992) -@c Is it worth worrying about what-if the beginner goes to somebody -@c else's Emacs session, which already has an Info running in the middle -@c of something---in which case these simple instructions won't work? -@end ifnotinfo - -@menu -* Help-Small-Screen:: Starting Info on a Small Screen. -* Help:: How to use Info. -* Help-P:: Returning to the Previous node. -* Help-^L:: The Space, DEL, B and ^L commands. -* Help-Inv:: Invisible text in Emacs Info. -* Help-M:: Menus. -* Help-Xref:: Following cross-references. -* Help-Int:: Some intermediate Info commands. -* Help-Q:: Quitting Info. -@end menu - -@node Help-Small-Screen -@section Starting Info on a Small Screen - -@ifnotinfo -(In Info, you only see this section if your terminal has a small -number of lines; most readers pass by it without seeing it.) -@end ifnotinfo - -@cindex small screen, moving around -Since your terminal has a relatively small number of lines on its -screen, it is necessary to give you special advice at the beginning. - -If the entire text you are looking at fits on the screen, the text -@samp{All} will be displayed at the bottom of the screen. In the -stand-alone Info reader, it is displayed at the bottom right corner of -the screen; in Emacs, it is displayed on the modeline. If you see the -text @samp{Top} instead, it means that there is more text below that -does not fit. To move forward through the text and see another screen -full, press @key{SPC}, the Space bar. To move back up, press the key -labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key -might be labeled @samp{Delete}). - -@ifinfo -Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and -see what they do. At the end are instructions of what you should do -next. - -@format -This is line 20 -This is line 21 -This is line 22 -This is line 23 -This is line 24 -This is line 25 -This is line 26 -This is line 27 -This is line 28 -This is line 29 -This is line 30 -This is line 31 -This is line 32 -This is line 33 -This is line 34 -This is line 35 -This is line 36 -This is line 37 -This is line 38 -This is line 39 -This is line 40 -This is line 41 -This is line 42 -This is line 43 -This is line 44 -This is line 45 -This is line 46 -This is line 47 -This is line 48 -This is line 49 -This is line 50 -This is line 51 -This is line 52 -This is line 53 -This is line 54 -This is line 55 -This is line 56 -This is line 57 -This is line 58 -This is line 59 -@end format - -If you have managed to get here, go back to the beginning with -@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you -understand the about the @samp{Space} and @samp{Backspace} keys. So -now type an @kbd{n}---just one character; don't type the quotes and -don't type the Return key afterward---to get to the normal start of -the course. -@end ifinfo - -@node Help, Help-P, Help-Small-Screen, Getting Started -@comment node-name, next, previous, up -@section How to use Info - -You are talking to the program Info, for reading documentation. - - There are two ways to use Info: from within Emacs or as a -stand-alone reader that you can invoke from a shell using the command -@command{info}. - -@cindex node, in Info documents - Right now you are looking at one @dfn{Node} of Information. -A node contains text describing a specific topic at a specific -level of detail. This node's topic is ``how to use Info''. The mode -line says that this is node @samp{Help} in the file @file{info}. - -@cindex header of Info node - The top line of a node is its @dfn{header}. This node's header -(look at it now) says that the @samp{Next} node after this one is the -node called @samp{Help-P}. An advanced Info command lets you go to -any node whose name you know. In the stand-alone Info reader program, -the header line shows the names of this node and the Info file as -well. In Emacs, the header line is displayed with a special typeface, -and remains at the top of the window all the time even if you scroll -through the node. - - Besides a @samp{Next}, a node can have a @samp{Previous} link, or an -@samp{Up} link, or both. As you can see, this node has all of these -links. - -@kindex n @r{(Info mode)} - Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. - -@format ->> Type @kbd{n} to move there. Type just one character; - do not type the quotes and do not type a @key{RET} afterward. -@end format - -@noindent -@samp{>>} in the margin means it is really time to try a command. - -@format ->> If you are in Emacs and have a mouse, and if you already practiced - typing @kbd{n} to get to the next node, click now with the left - mouse button on the @samp{Next} link to do the same ``the mouse way''. -@end format - -@node Help-P, Help-^L, Help, Getting Started -@comment node-name, next, previous, up -@section Returning to the Previous node - -@kindex p @r{(Info mode)} -This node is called @samp{Help-P}. The @samp{Previous} node, as you see, -is @samp{Help}, which is the one you just came from using the @kbd{n} -command. Another @kbd{n} command now would take you to the next -node, @samp{Help-^L}. - -@format ->> But do not type @kbd{n} yet. First, try the @kbd{p} command, or - (in Emacs) click on the @samp{Prev} link. That takes you to - the @samp{Previous} node. Then use @kbd{n} to return here. -@end format - - If you read this in Emacs, you will see an @samp{Info} item in the -menu bar, close to its right edge. Clicking the mouse on the -@samp{Info} menu-bar item opens a menu of commands which include -@samp{Next} and @samp{Previous} (and also some others which you didn't yet -learn about). - - This all probably seems insultingly simple so far, but @emph{please -don't} start skimming. Things will get complicated soon enough! -Also, please do not try a new command until you are told it is time -to. You could make Info skip past an important warning that was -coming up. - -@format ->> Now do an @kbd{n}, or (in Emacs) click the middle mouse button on - the @samp{Next} link, to get to the node @samp{Help-^L} and learn more. -@end format - -@node Help-^L, Help-Inv, Help-P, Getting Started -@comment node-name, next, previous, up -@section The Space, DEL, B and ^L commands - - This node's mode line tells you that you are now at node -@samp{Help-^L}, and the header line tells you that @kbd{p} would get -you back to @samp{Help-P}. The node's title is highlighted and may be -underlined as well; it says what the node is about. - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you -can see the text @samp{Top} rather than @samp{All} near the bottom of -the screen. - -@kindex SPC @r{(Info mode)} -@kindex DEL @r{(Info mode)} -@kindex BACKSPACE @r{(Info mode)} -@findex Info-scroll-up -@findex Info-scroll-down - The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which -we call ``Backspace or DEL'' in this manual is labeled differently on -different keyboards. Look for a key which is a little ways above the -@key{ENTER} or @key{RET} key and which you normally use outside Emacs -to erase the character before the cursor, i.e.@: the character you -typed last. It might be labeled @samp{Backspace} or @samp{<-} or -@samp{DEL}, or sometimes @samp{Delete}.} and @kbd{b} commands exist to -allow you to ``move around'' in a node that does not all fit on the -screen at once. @key{SPC} moves forward, to show what was below the -bottom of the screen. @key{DEL} or @key{BACKSPACE} moves backward, to -show what was above the top of the screen (there is not anything above -the top until you have typed some spaces). - -@format ->> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to - return here). -@end format - - When you type the @key{SPC}, the two lines that were at the bottom of -the screen appear at the top, followed by more lines. @key{DEL} or -@key{BACKSPACE} takes the two lines from the top and moves them to the -bottom, @emph{usually}, but if there are not a full screen's worth of -lines above them they may not make it all the way to the bottom. - - If you are reading this in Emacs, note that the header line is -always visible, never scrolling off the display. That way, you can -always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you -can conveniently go to one of these links at any time by -clicking the middle mouse button on the link. - -@cindex reading Info documents top to bottom -@cindex Info documents as tutorials - @key{SPC} and @key{DEL} not only move forward and backward through -the current node. They also move between nodes. @key{SPC} at the end -of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at -the beginning of a node moves to the previous node. In effect, these -commands scroll through all the nodes in an Info file as a single -logical sequence. You can read an entire manual top to bottom by just -typing @key{SPC}, and move backward through the entire manual from -bottom to top by typing @key{DEL} (or @key{BACKSPACE}). - - In this sequence, a node's subnodes appear following their parent. -If a node has a menu, @key{SPC} takes you into the subnodes listed in -the menu, one by one. Once you reach the end of a node, and have seen -all of its subnodes, @key{SPC} takes you to the next node or to the -parent's next node. - -@kindex PAGEUP @r{(Info mode)} -@kindex PAGEDOWN @r{(Info mode)} - Many keyboards nowadays have two scroll keys labeled @samp{PageUp} -and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}). If your -keyboard has these keys, you can use them to move forward and backward -through the text of one node, like @key{SPC} and @key{BACKSPACE} (or -@key{DEL}). However, @key{PAGEUP} and @key{PAGEDOWN} keys never -scroll beyond the beginning or the end of the current node. - -@kindex C-l @r{(Info mode)} - If your screen is ever garbaged, you can tell Info to display it -again by typing @kbd{C-l} (@kbd{Control-L}---that is, hold down -@key{CTRL} and type @kbd{L} or @kbd{l}). - -@format ->> Type @kbd{C-l} now. -@end format - -@kindex b @r{(Info mode)} - To move back to the beginning of the node you are on, you can type -the @key{BACKSPACE} key (or @key{DEL}) many times. You can also type -@kbd{b} just once. @kbd{b} stands for ``beginning.'' - -@format ->> Try that now. (We have put in enough verbiage to push this past - the first screenful, but screens are so big nowadays that perhaps it - isn't enough. You may need to shrink your Emacs or Info window.) - Then come back, by typing @key{SPC} one or more times. -@end format - -@kindex ? @r{(Info mode)} -@findex Info-summary - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type -@kbd{?}, which displays a brief list of commands. When you are -finished looking at the list, make it go away by typing @key{SPC} -repeatedly. - -@format ->> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of - the list until finished. Then type @key{SPC} several times. If - you are using Emacs, the help will then go away automatically. -@end format - - (If you are using the stand-alone Info reader, type @kbd{C-x 0} to -return here, that is---press and hold @key{CTRL}, type an @kbd{x}, -then release @key{CTRL} and @kbd{x}, and press @kbd{0}; that's a zero, -not the letter ``o''.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use @key{SPC} and @key{BACKSPACE} to -move around in them without being told. Since not all terminals have -the same size screen, it would be impossible to warn you anyway. - -@format ->> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link, - to visit the next node. -@end format - -@node Help-Inv, Help-M, Help-^L, Getting Started -@comment node-name, next, previous, up -@section Invisible text in Emacs Info - - Before discussing menus, we need to make some remarks that are only -relevant to users reading Info using Emacs. Users of the stand-alone -version can skip this node by typing @kbd{]} now. - -@cindex invisible text in Emacs - In Emacs, certain text that appears in the stand-alone version is -normally hidden, technically because it has the @samp{invisibility} -property. Invisible text is really a part of the text. It becomes -visible (by default) after killing and yanking, it appears in printed -output, it gets saved to file just like any other text, and so on. -Thus it is useful to know it is there. - -@findex visible-mode -You can make invisible text visible by using the command @kbd{M-x -visible-mode}. Visible mode is a minor mode, so using the command a -second time will make the text invisible again. Watch the effects of -the command on the ``menu'' below and the top line of this node. - -If you prefer to @emph{always} see the invisible text, you can set -@code{Info-hide-note-references} to @code{nil}. Enabling Visible mode -permanently is not a real alternative, because Emacs Info also uses -(although less extensively) another text property that can change the -text being displayed, the @samp{display} property. Only the -invisibility property is affected by Visible mode. When, in this -tutorial, we refer to the @samp{Emacs} behavior, we mean the -@emph{default} Emacs behavior. - -Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands. - -@menu -* ]: Help-]. Node telling about ]. -* stuff: Help-]. Same node. -* Help-]:: Yet again, same node. -@end menu - -@node Help-], , , Help-Inv -@subsection The @kbd{]} and @kbd{[} commands - -If you type @kbd{n} now, you get an error message saying that this -node has no next node. Similarly, if you type @kbd{p}, the error -message tells you that there is no previous node. (The exact message -depends on the Info reader you use.) This is because @kbd{n} and -@kbd{p} carry you to the next and previous node @emph{at the same -level}. The present node is contained in a menu (see next) of the -node you came from, and hence is considered to be at a lower level. -It is the only node in the previous node's menu (even though it was -listed three times). Hence it has no next or previous node that -@kbd{n} or @kbd{p} could move to. - -If you systematically move through a manual by typing @kbd{n}, you run -the risk of skipping many nodes. You do not run this risk if you -systematically use @kbd{@key{SPC}}, because, when you scroll to the -bottom of a node and type another @kbd{@key{SPC}}, then this carries -you to the following node in the manual @emph{regardless of level}. -If you immediately want to go to that node, without having to scroll -to the bottom of the screen first, you can type @kbd{]}. - -Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node -regardless of level, after you scrolled to the beginning of the -present node. If you want to go to the preceding node immediately, -you can type @kbd{[}. - -For instance, typing this sequence will come back here in three steps: -@kbd{[ n [}. To do the same backward, type @kbd{] p ]}. - -Now type @kbd{]} to go to the next node and learn about menus. - -@node Help-M, Help-Xref, Help-Inv, Getting Started -@comment node-name, next, previous, up -@section Menus and the @kbd{m} command - -@cindex menus in an Info document -@cindex Info menus - With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}}, -@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between -nodes, nodes are restricted to a linear sequence. Menus allow a -branching structure. A menu is a list of other nodes you can move to. -It is actually just part of the text of the node formatted specially -so that Info can interpret it. The beginning of a menu is always -identified by a line which starts with @w{@samp{* Menu:}}. A node -contains a menu if and only if it has a line in it which starts that -way. The only menu you can use at any moment is the one in the node -you are in. To use a menu in any other node, you must move to that -node first. - - After the start of the menu, each line that starts with a @samp{*} -identifies one subtopic. The line usually contains a brief name for -the subtopic (followed by a @samp{:}, normally hidden in Emacs), the -name of the node that talks about that subtopic (again, normally -hidden in Emacs), and optionally some further description of the -subtopic. Lines in the menu that do not start with a @samp{*} have no -special meaning---they are only for the human reader's benefit and do -not define additional subtopics. Here is an example: - -@example -* Foo: Node about FOO. This tells about FOO. -@end example - -The subtopic name is Foo, and the node describing it is @samp{Node -about FOO}. The rest of the line is just for the reader's -Information. [[ But this line is not a real menu item, simply because -there is no line above it which starts with @w{@samp{* Menu:}}. Also, -in a real menu item, the @samp{*} would appear at the very start of -the line. This is why the ``normally hidden'' text in Emacs, namely -@samp{: Node about FOO.}, is actually visible in this example, even -when Visible mode is off.]] - - When you use a menu to go to another node (in a way that will be -described soon), what you specify is the subtopic name, the first -thing in the menu line. Info uses it to find the menu line, extracts -the node name from it, and goes to that node. The reason that there -is both a subtopic name and a node name is that the node name must be -meaningful to the computer and may therefore have to be ugly looking. -The subtopic name can be chosen just to be convenient for the user to -specify. Often the node name is convenient for the user to specify -and so both it and the subtopic name are the same. There is an -abbreviation for this: - -@example -* Foo:: This tells about FOO. -@end example - -@noindent -This means that the subtopic name and node name are the same; they are -both @samp{Foo}. (The @samp{::} is normally hidden in Emacs.) - -@format ->> Now use @key{SPC} to find the menu in this node, then come back to - the front with a @kbd{b} and some @key{SPC}s. As you see, a menu is - actually visible in its node. If you cannot find a menu in a node - by looking at it, then the node does not have a menu and the - @kbd{m} command is not available. -@end format - -If you keep typing @key{SPC} once the menu appears on the screen, it -will move to another node (the first one in the menu). If that -happens, type @key{BACKSPACE} to come back. - -@kindex m @r{(Info mode)} - The command to go to one of the subnodes is @kbd{m}. This is very -different from the commands you have used: it is a command that -prompts you for more input. - - The Info commands you know do not need additional input; when you -type one of them, Info processes it instantly and then is ready for -another command. The @kbd{m} command is different: it needs to know -the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info -tries to read the subtopic name. - - Now, in the stand-alone Info, look for the line containing many -dashes near the bottom of the screen. (This is the stand-alone -equivalent for the mode line in Emacs.) There is one more line -beneath that one, but usually it is blank. (In Emacs, this is the -echo area.) When it is blank, Info is ready for a command, such as -@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains -text ending in a colon, it means Info is reading more input for the -last command. You can't type an Info command then, because Info is -trying to read input, not commands. You must either give the input -and finish the command you started, or type @kbd{Control-g} to cancel -the command. When you have done one of those things, the input entry -line becomes blank again. Then you can type Info commands again. - -@findex Info-menu - The command to go to a subnode via a menu is @kbd{m}. After you type -the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }. -You must then type the name of the subtopic you want, and end it with -a @key{RET}. - -@cindex abbreviating Info subnodes - You can abbreviate the subtopic name. If the abbreviation is not -unique, the first matching subtopic is chosen. Some menus put -the shortest possible abbreviation for each subtopic name in capital -letters, so you can see how much you need to type. It does not -matter whether you use upper case or lower case when you type the -subtopic. You should not put any spaces at the end, or inside of the -item name, except for one space where a space appears in the item in -the menu. - -@cindex completion of Info node names - You can also use the @dfn{completion} feature to help enter the -subtopic name. If you type the @key{TAB} key after entering part of a -name, it will fill in more of the name---as much as Info can deduce -from the part you have entered. - - If you move the cursor to one of the menu subtopic lines, then you do -not need to type the argument: you just type a @key{RET}, and it -stands for the subtopic of the line you are on. You can also click -the middle mouse button directly on the subtopic line to go there. - -Here is a menu to give you a chance to practice. This menu gives you -three ways of going to one place, Help-FOO: - -@menu -* Foo: Help-FOO. A node you can visit for fun. -* Bar: Help-FOO. We have made two ways to get to the same place. -* Help-FOO:: And yet another! -@end menu - -(Turn Visible mode on if you are using Emacs.) - -@format ->> Now type just an @kbd{m} and see what happens: -@end format - - Now you are ``inside'' an @kbd{m} command. Commands cannot be used -now; the next thing you will type must be the name of a subtopic. - - You can change your mind about doing the @kbd{m} by typing -@kbd{Control-g}. - -@format ->> Try that now; notice the bottom line clear. -@end format - -@format ->> Then type another @kbd{m}. -@end format - -@format ->> Now type @kbd{BAR}, the item name. Do not type @key{RET} yet. -@end format - - While you are typing the item name, you can use the @key{DEL} (or -@key{BACKSPACE}) key to cancel one character at a time if you make a -mistake. - -@format ->> Press @key{DEL} to cancel the @samp{R}. You could type another @kbd{R} - to replace it. But you do not have to, since @samp{BA} is a valid - abbreviation. -@end format - -@format ->> Now you are ready to go. Type a @key{RET}. -@end format - - After visiting @samp{Help-FOO}, you should return here. - - Another way to move to the menu subtopic lines and between them is -to type @key{TAB}. Each time you type a @key{TAB}, you move to the -next subtopic line. To move to a previous subtopic line in the -stand-alone reader, type @kbd{M-@key{TAB}}---that is, press and hold -the @key{META} key and then press @key{TAB}. (On some keyboards, the -@key{META} key might be labeled @samp{Alt}.) In Emacs Info, type -@kbd{S-@key{TAB}} to move to a previous subtopic line (press and hold -the @key{Shift} key and then press @key{TAB}). - - Once you move cursor to a subtopic line, press @key{RET} to go to -that subtopic's node. - -@cindex mouse support in Info mode -@kindex Mouse-2 @r{(Info mode)} - If your terminal supports a mouse, you have yet another way of going -to a subtopic. Move your mouse pointer to the subtopic line, -somewhere between the beginning @samp{*} and the colon @samp{:} which -ends the subtopic's brief name. You will see the subtopic's name -change its appearance (usually, its background color will change), and -the shape of the mouse pointer will change if your platform supports -that. After a while, if you leave the mouse on that spot, a small -window will pop up, saying ``Mouse-2: go to that node,'' or the same -message may appear at the bottom of the screen. - - @kbd{Mouse-2} is the second button of your mouse counting from the -left---the middle button on a 3-button mouse. (On a 2-button mouse, -you may have to press both buttons together to ``press the middle -button''.) The message tells you pressing @kbd{Mouse-2} with the -current position of the mouse pointer (on subtopic in the menu) will -go to that subtopic. - -@findex Info-mouse-follow-nearest-node - More generally, @kbd{Mouse-2} in an Info buffer finds the nearest -link to another node and goes there. For example, near a cross -reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the -node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At -end of the node's text @kbd{Mouse-2} moves to the next node, or up if -there's no next node. - -@format ->> Type @kbd{n} to see more commands. -@end format - -@node Help-FOO, , , Help-M -@subsection The @kbd{u} command - - Congratulations! This is the node @samp{Help-FOO}. It has an @samp{Up} -pointer @samp{Help-M}, the node you just came from via the @kbd{m} -command. This is the usual convention---the nodes you reach from a menu -have @samp{Up} nodes that lead back to the menu. Menus move Down in the -tree, and @samp{Up} moves Up. @samp{Previous}, on the other hand, is -usually used to ``stay on the same level but go backwards''. - -@kindex u @r{(Info mode)} -@findex Info-up - You can go back to the node @samp{Help-M} by typing the command -@kbd{u} for ``Up''. This puts you at the menu subtopic line pointing -to the subnode that the @kbd{u} command brought you from. (Some Info -readers may put you at the @emph{front} of the node instead---to get -back to where you were reading, you have to type some @key{SPC}s.) - - Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up} -pointer shown in the header line (provided that you have a mouse). - -@format ->> Now type @kbd{u} to move back up to @samp{Help-M}. -@end format - -@node Help-Xref, Help-Int, Help-M, Getting Started -@comment node-name, next, previous, up -@section Following Cross-References - -@cindex cross references in Info documents - In Info documentation, you will see many @dfn{cross references}. -Cross references look like this: @xref{Help-Cross, Cross}. That text -is a real, live cross reference, whose name is @samp{Cross} and which -points to the node named @samp{Help-Cross}. (The node name is hidden -in Emacs. Do @kbd{M-x visible-mode} to show or hide it.) - -@kindex f @r{(Info mode)} -@findex Info-follow-reference - You can follow a cross reference by moving the cursor to it and -press @key{RET}, just as in a menu. In Emacs, you can also click -@kbd{Mouse-1} on a cross reference to follow it; you can see that the -cross reference is mouse-sensitive by moving the mouse pointer to the -reference and watching how the underlying text and the mouse pointer -change in response. - - Another way to follow a cross reference is to type @kbd{f} and then -specify the name of the cross reference (in this case, @samp{Cross}) -as an argument. For this command, it does not matter where the cursor -was. If the cursor is on or near a cross reference, @kbd{f} suggests -that reference name in parentheses as the default; typing @key{RET} -will follow that reference. However, if you type a different -reference name, @kbd{f} will follow the other reference which has that -name. - -@format ->> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}. -@end format - - As you enter the reference name, you can use the @key{DEL} (or -@key{BACKSPACE}) key to edit your input. If you change your mind -about following any reference, you can use @kbd{Control-g} to cancel -the command. Completion is available in the @kbd{f} command; you can -complete among all the cross reference names in the current node by -typing a @key{TAB}. - - To get a list of all the cross references in the current node, you -can type @kbd{?} after an @kbd{f}. The @kbd{f} continues to await a -cross reference name even after displaying the list, so if you don't -actually want to follow a reference, you should type a @kbd{Control-g} -to cancel the @kbd{f}. - -@format ->> Type @kbd{f?} to get a list of the cross references in this node. Then - type a @kbd{Control-g} and see how the @samp{f} gives up. -@end format - - The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys, -which move between menu items in a menu, also move between cross -references outside of menus. - - Sometimes a cross reference (or a node) can lead to another file (in -other words another ``manual''), or, on occasion, even a file on a -remote machine (although Info files distributed with Emacs or the -stand-alone Info avoid using remote links). Such a cross reference -looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo: -The GNU Documentation Format}. (After following this link, type -@kbd{l} to get back to this node.) Here the name @samp{texinfo} -between parentheses refers to the file name. This file name appears -in cross references and node names if it differs from the current -file, so you can always know that you are going to be switching to -another manual and which one. - -However, Emacs normally hides some other text in cross-references. -If you put your mouse over the cross reference, then the information -appearing in a separate box (tool tip) or in the echo area will show -the full cross-reference including the file name and the node name of -the cross reference. If you have a mouse, just leave it over the -cross reference @xref{Top,, Overview of Texinfo, texinfo, Texinfo: -The GNU Documentation Format}, and watch what happens. If you -always like to have that information visible without having to move -your mouse over the cross reference, use @kbd{M-x visible-mode}, or -set @code{Info-hide-note-references} to a value other than @code{t} -(@pxref{Emacs Info Variables}). - -@format ->> Now type @kbd{n} to learn more commands. -@end format - -@node Help-Int, Help-Q, Help-Xref, Getting Started -@comment node-name, next, previous, up -@section Some intermediate Info commands - - The introductory course is almost over; please continue -a little longer to learn some intermediate-level commands. - - Most Info files have an index, which is actually a large node -containing little but a menu. The menu has one menu item for each -topic listed in the index. (As a special feature, menus for indices -may also include the line number within the node of the index entry. -This allows Info readers to go to the exact line of an entry, not just -the start of the containing node.) - - You can get to the index from the main menu of the file with the -@kbd{m} command and the name of the index node; then you can use the -@kbd{m} command again in the index node to go to the node that -describes the topic you want. - - There is also a short-cut Info command, @kbd{i}, which does all of -that for you. It searches the index for a given topic (a string) and -goes to the node which is listed in the index for that topic. -@xref{Search Index}, for a full explanation. - -@kindex l @r{(Info mode)} -@findex Info-history-back -@cindex going back in Info history - If you have been moving around to different nodes and wish to -retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will -do that, one node-step at a time. As you move from node to node, Info -records the nodes where you have been in a special history list. The -@kbd{l} command revisits nodes in the history list; each successive -@kbd{l} command moves one step back through the history. - -@format ->> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between -to see what each @kbd{l} does. You should wind up right back here. -@end format - - Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to -where @emph{you} last were, whereas @kbd{p} always moves to the node -which the header says is the @samp{Previous} node (from this node, the -@samp{Prev} link leads to @samp{Help-Xref}). - -@kindex r @r{(Info mode)} -@findex Info-history-forward -@cindex going forward in Info history - You can use the @kbd{r} command (@code{Info-history-forward} in Emacs) -to revisit nodes in the history list in the forward direction, so that -@kbd{r} will return you to the node you came from by typing @kbd{l}. - -@kindex L @r{(Info mode)} -@findex Info-history -@cindex history list of visited nodes - The @kbd{L} command (@code{Info-history} in Emacs) creates a virtual -node that contains a list of all nodes you visited. You can select -a previously visited node from this menu to revisit it. - -@kindex d @r{(Info mode)} -@findex Info-directory -@cindex go to Directory node - The @kbd{d} command (@code{Info-directory} in Emacs) gets you -instantly to the Directory node. This node, which is the first one -you saw when you entered Info, has a menu which leads (directly or -indirectly, through other menus), to all the nodes that exist. The -Directory node lists all the manuals and other Info documents that -are, or could be, installed on your system. - -@format ->> Try doing a @kbd{d}, then do an @kbd{l} to return here (yes, - @emph{do} return). -@end format - -@kindex t @r{(Info mode)} -@findex Info-top-node -@cindex go to Top node - The @kbd{t} command moves to the @samp{Top} node of the manual. -This is useful if you want to browse the manual's main menu, or select -some specific top-level menu item. The Emacs command run by @kbd{t} -is @code{Info-top-node}. - -@format ->> Now type @kbd{n} to see the last node of the course. -@end format - - @xref{Advanced}, for more advanced Info features. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -@node Help-Q, , Help-Int, Getting Started -@comment node-name, next, previous, up -@section Quitting Info - -@kindex q @r{(Info mode)} -@findex Info-exit -@cindex quitting Info mode - To get out of Info, back to what you were doing before, type @kbd{q} -for @dfn{Quit}. This runs @code{Info-exit} in Emacs. - - This is the end of the basic course on using Info. You have learned -how to move in an Info document, and how to follow menus and cross -references. This makes you ready for reading manuals top to bottom, -as new users should do when they learn a new package. - - Another set of Info commands is useful when you need to find -something quickly in a manual---that is, when you need to use a manual -as a reference rather than as a tutorial. We urge you to learn -these search commands as well. If you want to do that now, follow this -cross reference to @ref{Advanced}. - -Yet another set of commands are meant for experienced users; you can -find them by looking in the Directory node for documentation on Info. -Finding them will be a good exercise in using Info in the usual -manner. - -@format ->> Type @kbd{d} to go to the Info directory node; then type - @kbd{mInfo} and Return, to get to the node about Info and - see what other help is available. -@end format - - -@node Advanced -@chapter Advanced Info Commands - - This chapter describes various advanced Info commands. (If you -are using a stand-alone Info reader, there are additional commands -specific to it, which are documented in several chapters of @ref{Top,, -GNU Info, info-stnd, GNU Info}.) - -@kindex C-q @r{(Info mode)} - One advanced command useful with most of the others described here -is @kbd{C-q}, which ``quotes'' the next character so that it is -entered literally (@pxref{Inserting Text,,,emacs,The GNU Emacs -Manual}). For example, pressing @kbd{?} ordinarily brings up a list -of completion possibilities. If you want to (for example) search for -an actual @samp{?} character, the simplest way is to insert it using -@kbd{C-q ?}. This works the same in Emacs and stand-alone Info. - -@menu -* Search Text:: How to search Info documents. -* Search Index:: How to search the indices for specific subjects. -* Go to node:: How to go to a node by name. -* Choose menu subtopic:: How to choose a menu subtopic by its number. -* Create Info buffer:: How to create a new Info buffer in Emacs. -* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. -@end menu - - -@node Search Text, Search Index, , Advanced -@comment node-name, next, previous, up -@section @kbd{s} searches Info documents - -@cindex searching Info documents -@cindex Info document as a reference - The commands which move between and inside nodes allow you to read -the entire manual or its large portions. But what if you need to find -some information in the manual as fast as you can, and you don't know -or don't remember in what node to look for it? This need arises when -you use a manual as a @dfn{reference}, or when it is impractical to -read the entire manual before you start using the programs it -describes. - - Info has powerful searching facilities that let you find things -quickly. You can search either the manual text or its indices. - -@kindex s @r{(Info mode)} -@findex Info-search - The @kbd{s} command allows you to search a whole Info file for a string. -It switches to the next node if and when that is necessary. You -type @kbd{s} followed by the string to search for, terminated by -@key{RET}. To search for the same string again, just @kbd{s} followed -by @key{RET} will do. The file's nodes are scanned in the order -they are in the file, which has no necessary relationship to the -order that they may be in the tree structure of menus and @samp{next} -pointers. But normally the two orders are not very different. In any -case, you can always look at the mode line to find out what node you have -reached, if the header is not visible (this can happen, because @kbd{s} -puts your cursor at the occurrence of the string, not at the beginning -of the node). - -@kindex M-s @r{(Info mode)} - In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for -compatibility with other GNU packages that use @kbd{M-s} for a similar -kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the -command @code{Info-search}. - -@kindex C-s @r{(Info mode)} -@kindex C-r @r{(Info mode)} -@findex isearch - Instead of using @kbd{s} in Emacs Info and in the stand-alone Info, -you can use an incremental search started with @kbd{C-s} or @kbd{C-r}. -It can search through multiple Info nodes. @xref{Incremental Search,,, -emacs, The GNU Emacs Manual}. In Emacs, you can disable this behavior -by setting the variable @code{Info-isearch-search} to @code{nil} -(@pxref{Emacs Info Variables}). - -@node Search Index, Go to node, Search Text, Advanced -@comment node-name, next, previous, up -@section @kbd{i} searches the indices for specific subjects - -@cindex searching Info indices -@kindex i @r{(Info mode)} -@findex Info-index - Since most topics in the manual should be indexed, you should try -the index search first before the text search. The @kbd{i} command -prompts you for a subject and then looks up that subject in the -indices. If it finds an index entry with the subject you typed, it -goes to the node to which that index entry points. You should browse -through that node to see whether the issue you are looking for is -described there. If it isn't, type @kbd{,} one or more times to go -through additional index entries which match your subject. - - The @kbd{i} command and subsequent @kbd{,} commands find all index -entries which include the string you typed @emph{as a substring}. -For each match, Info shows in the echo area the full index entry it -found. Often, the text of the full index entry already gives you -enough information to decide whether it is relevant to what you are -looking for, so we recommend that you read what Info shows in the echo -area before looking at the node it displays. - - Since @kbd{i} looks for a substring, you can search for subjects even -if you are not sure how they are spelled in the index. For example, -suppose you want to find something that is pertinent to commands which -complete partial input (e.g., when you type @key{TAB}). If you want -to catch index entries that refer to ``complete,'' ``completion,'' and -``completing,'' you could type @kbd{icomplet@key{RET}}. - - Info documents which describe programs should index the commands, -options, and key sequences that the program provides. If you are -looking for a description of a command, an option, or a key, just type -their names when @kbd{i} prompts you for a topic. For example, if you -want to read the description of what the @kbd{C-l} key does, type -@kbd{iC-l@key{RET}} literally. - -@findex info-apropos -@findex index-apropos -If you aren't sure which manual documents the topic you are looking -for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x -index-apropos} command in the stand-alone reader. It prompts for -a string and then looks up that string in all the indices of all the -Info documents installed on your system. - -@node Go to node, Choose menu subtopic, Search Index, Advanced -@comment node-name, next, previous, up -@section @kbd{g} goes to a node by name - -@kindex g @r{(Info mode)} -@findex Info-goto-node -@cindex go to a node by name - If you know a node's name, you can go there by typing @kbd{g}, the -name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node -called @samp{Top} in this file. (This is equivalent to @kbd{t}, see -@ref{Help-Int}.) @kbd{gGo to node@key{RET}} would come back here. - - Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. -But it does allow completion, so you can type @key{TAB} to complete a -partial node name. - -@cindex go to another Info file - To go to a node in another file, you can include the file name in the -node name by putting it at the front, in parentheses. Thus, -@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is -the node @samp{Top} in the Info file @file{dir}. Likewise, -@kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual. - - The node name @samp{*} specifies the whole file. So you can look at -all of the current file by typing @kbd{g*@key{RET}} or all of any -other file with @kbd{g(@var{filename})*@key{RET}}. - -@node Choose menu subtopic, Create Info buffer, Go to node, Advanced -@comment node-name, next, previous, up -@section @kbd{1}--@kbd{9} choose a menu subtopic by its number - -@kindex 1 @r{through} 9 @r{(Info mode)} -@findex Info-nth-menu-item -@cindex select @var{n}'th menu item - If you begrudge each character of type-in which your system requires, -you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, -@dots{}, @kbd{9}. They are short for the @kbd{m} command together -with a name of a menu subtopic. @kbd{1} goes through the first item -in the current node's menu; @kbd{2} goes through the second item, etc. -In the stand-alone reader, @kbd{0} goes through the last menu item; -this is so you need not count how many entries are there. - - If your display supports multiple fonts, colors or underlining, and -you are using Emacs' Info mode to read Info files, the third, sixth -and ninth menu items have a @samp{*} that stands out, either in color -or in some other attribute, such as underline; this makes it easy to -see at a glance which number to use for an item. - - Some terminals don't support either multiple fonts, colors or -underlining. If you need to actually count items, it is better to use -@kbd{m} instead, and specify the name, or use @key{TAB} to quickly -move between menu items. - -@node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced -@comment node-name, next, previous, up -@section @kbd{M-n} creates a new independent Info buffer in Emacs - -@kindex M-n @r{(Info mode)} -@findex clone-buffer -@cindex multiple Info buffers - If you are reading Info in Emacs, you can select a new independent -Info buffer in a new Emacs window by typing @kbd{M-n}. The new buffer -starts out as an exact copy of the old one, but you will be able to -move independently between nodes in the two buffers. (In Info mode, -@kbd{M-n} runs the Emacs command @code{clone-buffer}.) - - In Emacs Info, you can also produce new Info buffers by giving a -numeric prefix argument to the @kbd{m} and @kbd{g} commands. @kbd{C-u -m} and @kbd{C-u g} go to a new node in exactly the same way that -@kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they -select in another window. - - Another way to produce new Info buffers in Emacs is to use a numeric -prefix argument for the @kbd{C-h i} command (@code{info}) which -switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} -switches to the buffer @samp{*info*<2>}, creating it if necessary. - -@node Emacs Info Variables, , Create Info buffer, Advanced -@comment node-name, next, previous, up -@section Emacs Info-mode Variables - -The following variables may modify the behavior of Info-mode in Emacs; -you may wish to set one or several of these variables interactively, -or in your init file. @xref{Examining, Examining and Setting -Variables, Examining and Setting Variables, emacs, The GNU Emacs -Manual}. The stand-alone Info reader program has its own set of -variables, described in @ref{Variables,, Manipulating Variables, -info-stnd, GNU Info}. - -@vtable @code -@item Info-directory-list -The list of directories to search for Info files. Each element is a -string (directory name) or @code{nil} (try default directory). If not -initialized Info uses the environment variable @env{INFOPATH} to -initialize it, or @code{Info-default-directory-list} if there is no -@env{INFOPATH} variable in the environment. - -If you wish to customize the Info directory search list for both Emacs -Info and stand-alone Info, it is best to set the @env{INFOPATH} -environment variable, since that applies to both programs. - -@item Info-additional-directory-list -A list of additional directories to search for Info documentation files. -These directories are not searched for merging the @file{dir} file. - -@item Info-mode-hook -Hooks run when @code{Info-mode} is called. By default, it contains -the hook @code{turn-on-font-lock} which enables highlighting of Info -files. You can change how the highlighting looks by customizing the -faces @code{info-node}, @code{info-xref}, @code{info-xref-visited}, -@code{info-header-xref}, @code{info-header-node}, @code{info-menu-header}, -@code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n} -is the level of the section, a number between 1 and 4). To customize -a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}}, -where @var{face} is one of the face names listed here. - -@item Info-fontify-maximum-menu-size -Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}. - -@item Info-fontify-visited-nodes -If non-@code{nil}, menu items and cross-references pointing to visited -nodes are displayed in the @code{info-xref-visited} face. - -@item Info-use-header-line -If non-@code{nil}, Emacs puts in the Info buffer a header line showing -the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does -not scroll with the rest of the buffer, making these links always -visible. - -@item Info-hide-note-references -As explained in earlier nodes, the Emacs version of Info normally -hides some text in menus and cross-references. You can completely -disable this feature, by setting this option to @code{nil}. Setting -it to a value that is neither @code{nil} nor @code{t} produces an -intermediate behavior, hiding a limited amount of text, but showing -all text that could potentially be useful. - -@item Info-scroll-prefer-subnodes -If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or -@key{DEL}) keys in a menu visit subnodes of the current node before -scrolling to its end or beginning, respectively. For example, if the -node's menu appears on the screen, the next @key{SPC} moves to a -subnode indicated by the following menu item. Setting this option to -@code{nil} results in behavior similar to the stand-alone Info reader -program, which visits the first subnode from the menu only when you -hit the end of the current node. The default is @code{nil}. - -@item Info-isearch-search -If non-@code{nil}, isearch in Info searches through multiple nodes. - -@item Info-enable-active-nodes -When set to a non-@code{nil} value, allows Info to execute Lisp code -associated with nodes. The Lisp code is executed when the node is -selected. The Lisp code to be executed should follow the node -delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like -this: - -@example -^_execute: (message "This is an active node!") -@end example -@end vtable - - -@node Expert Info -@chapter Info for Experts - - This chapter explains how to write an Info file by hand. However, -in most cases, writing a Texinfo file is better, since you can use it -to make a printed manual or produce other formats, such as HTML and -DocBook, as well as for generating Info files. - -The @code{makeinfo} command 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. - -@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU -Documentation Format}, for how to write a Texinfo file. - -@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation -Format}, for how to create an Info file from a Texinfo file. - -@xref{Installing an Info File,,, texinfo, Texinfo: The GNU -Documentation Format}, for how to install an Info file after you -have created one. - -However, if you want to edit an Info file manually and install it manually, -here is how. - -@menu -* Add:: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -* Menus:: How to add to or create menus in Info nodes. -* Cross-refs:: How to add cross-references to Info nodes. -* Tags:: How to make tags tables for Info files. -* Checking:: Checking an Info File. -@end menu - -@node Add, Menus, , Expert Info -@comment node-name, next, previous, up -@section Adding a new node to Info - -To add a new topic to the list in the Info directory, you must: - -@enumerate -@item -Create some nodes, in some file, to document that topic. -@item -Put that topic in the menu in the directory. @xref{Menus, Menu}. -@end enumerate - -@cindex node delimiters - The new node can live in an existing documentation file, or in a new -one. It must have a @samp{^_} character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If -you put in a @samp{^L} to end a new node, be sure that there is a -@samp{^_} after it to start the next one, since @samp{^L} cannot -@emph{start} a node. Also, a nicer way to make a node boundary be a -page boundary as well is to put a @samp{^L} @emph{right after} the -@samp{^_}.} - - The @samp{^_} starting a node must be followed by a newline or a -@samp{^L} newline, after which comes the node's header line. The -header line must give the node's name (by which Info finds it), and -state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} -nodes (if there are any). As you can see, this node's @samp{Up} node -is the node @samp{Expert Info}. The @samp{Next} node is @samp{Menus}. - -@cindex node header line format -@cindex format of node headers - The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up} -may appear in any order, anywhere in the header line, but the -recommended order is the one in this sentence. Each keyword must be -followed by a colon, spaces and tabs, and then the appropriate name. -The name may be terminated with a tab, a comma, or a newline. A space -does not end it; node names may contain spaces. The case of letters -in the names is insignificant. - -@cindex node name format -@cindex Directory node - A node name has two forms. A node in the current file is named by -what appears after the @samp{Node: } in that node's first line. For -example, this node's name is @samp{Add}. A node in another file is -named by @samp{(@var{filename})@var{node-within-file}}, as in -@samp{(info)Add} for this node. If the file name starts with @samp{./}, -then it is relative to the current directory; otherwise, it is -relative starting from the standard directory for Info files of your -site. The name @samp{(@var{filename})Top} can be abbreviated to just -@samp{(@var{filename})}. By convention, the name @samp{Top} is used -for the ``highest'' node in any single file---the node whose @samp{Up} -points out of the file. The @samp{Directory} node is @file{(dir)}, it -points to a file @file{dir} which holds a large menu listing all the -Info documents installed on your site. The @samp{Top} node of a -document file listed in the @samp{Directory} should have an @samp{Up: -(dir)} in it. - -@cindex unstructured documents - The node name @kbd{*} is special: it refers to the entire file. -Thus, @kbd{g*} shows you the whole current file. The use of the -node @kbd{*} is to make it possible to make old-fashioned, -unstructured files into nodes of the tree. - - The @samp{Node:} name, in which a node states its own name, must not -contain a file name, since when Info searches for a node, it does not -expect a file name to be there. The @samp{Next}, @samp{Previous} and -@samp{Up} names may contain them. In this node, since the @samp{Up} -node is in the same file, it was not necessary to use one. - - Note that the nodes in this file have a file name in the header -line. The file names are ignored by Info, but they serve as comments -to help identify the node for the user. - -@node Menus, Cross-refs, Add, Expert Info -@comment node-name, next, previous, up -@section How to Create Menus - - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. -The @kbd{m} command searches the current node's menu for the topic which it -reads from the terminal. - -@cindex menu and menu entry format - A menu begins with a line starting with @w{@samp{* Menu:}}. The -rest of the line is a comment. After the starting line, every line -that begins with a @samp{* } lists a single topic. The name of the -topic---what the user must type at the @kbd{m}'s command prompt to -select this topic---comes right after the star and space, and is -followed by a colon, spaces and tabs, and the name of the node which -discusses that topic. The node name, like node names following -@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a -tab, comma, or newline; it may also be terminated with a period. - - If the node name and topic name are the same, then rather than -giving the name twice, the abbreviation @samp{* @var{name}::} may be -used (and should be used, whenever possible, as it reduces the visual -clutter in the menu). - - It is considerate to choose the topic names so that they differ -from each other very near the beginning---this allows the user to type -short abbreviations. In a long menu, it is a good idea to capitalize -the beginning of each item name which is the minimum acceptable -abbreviation for it (a long menu is more than 5 or so entries). - - The nodes listed in a node's menu are called its ``subnodes,'' and it -is their ``superior''. They should each have an @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the subnodes -in a sequence of @samp{Next} and @samp{Previous} pointers so that -someone who wants to see them all need not keep revisiting the Menu. - - The Info Directory is simply the menu of the node @samp{(dir)Top}---that -is, node @samp{Top} in file @file{.../info/dir}. You can put new entries -in that menu just like any other menu. The Info Directory is @emph{not} the -same as the file directory called @file{info}. It happens that many of -Info's files live in that file directory, but they do not have to; and -files in that directory are not automatically listed in the Info -Directory node. - - Also, although the Info node graph is claimed to be a ``hierarchy,'' -in fact it can be @emph{any} directed graph. Shared structures and -pointer cycles are perfectly possible, and can be used if they are -appropriate to the meaning to be expressed. There is no need for all -the nodes in a file to form a connected structure. In fact, this file -has two connected components. You are in one of them, which is under -the node @samp{Top}; the other contains the node @samp{Help} which the -@kbd{h} command goes to. In fact, since there is no garbage -collector on the node graph, nothing terrible happens if a substructure -is not pointed to, but such a substructure is rather useless since nobody -can ever find out that it exists. - -@node Cross-refs, Tags, Menus, Expert Info -@comment node-name, next, previous, up -@section Creating Cross References - -@cindex cross reference format - A cross reference can be placed anywhere in the text, unlike a menu -item which must go at the front of a line. A cross reference looks -like a menu item except that it has @samp{*note} instead of @samp{*}. -It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are -so often part of node names. If you wish to enclose a cross reference -in parentheses, terminate it with a period first. Here are two -examples of cross references pointers: - -@example -*Note details: commands. (See *note 3: Full Proof.) -@end example - -@noindent -@emph{These are just examples.} The places they ``lead to'' do not -really exist! - -@menu -* Help-Cross:: Target of a cross-reference. -@end menu - - -@node Help-Cross, , , Cross-refs -@subsection The node reached by the cross reference in Info - - This is the node reached by the cross reference named @samp{Cross}. - - While this node is specifically intended to be reached by a cross -reference, most cross references lead to nodes that ``belong'' -someplace else far away in the structure of an Info document. So you -cannot expect this node to have a @samp{Next}, @samp{Previous} or -@samp{Up} links pointing back to where you came from. In general, the -@kbd{l} (el) command is the only way to get back there. - -@format ->> Type @kbd{l} to return to the node where the cross reference was. -@end format - -@node Tags, Checking, Cross-refs, Expert Info -@comment node-name, next, previous, up -@section Tags Tables for Info Files - -@cindex tags tables in Info files - You can speed up the access to nodes of a large Info file by giving -it a tags table. Unlike the tags table for a program, the tags table for -an Info file lives inside the file itself and is used -automatically whenever Info reads in the file. - -@findex Info-tagify - To make a tags table, go to a node in the file using Emacs Info mode and type -@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the -file. Info files produced by the @code{makeinfo} command that is part -of the Texinfo package always have tags tables to begin with. - -@cindex stale tags tables -@cindex update Info tags table - Once the Info file has a tags table, you must make certain it is up -to date. If you edit an Info file directly (as opposed to editing its -Texinfo source), and, as a result of deletion of text, any node moves back -more than a thousand characters in the file from the position -recorded in the tags table, Info will no longer be able to find that -node. To update the tags table, use the @code{Info-tagify} command -again. - - An Info file tags table appears at the end of the file and looks like -this: - -@example -^_^L -Tag Table: -File: info, Node: Cross-refs^?21419 -File: info, Node: Tags^?22145 -^_ -End Tag Table -@end example - -@noindent -Note that it contains one line per node, and this line contains -the beginning of the node's header (ending just after the node name), -a @samp{DEL} character, and the character position in the file of the -beginning of the node. - -@node Checking, , Tags, Expert Info -@section Checking an Info File - -When creating an Info file, it is easy to forget the name of a node when -you are making a pointer to it from another node. If you put in the -wrong name for a node, this is not detected until someone tries to go -through the pointer using Info. Verification of the Info file is an -automatic process which checks all pointers to nodes and reports any -pointers which are invalid. Every @samp{Next}, @samp{Previous}, and -@samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{Previous} pointing -back is reported. Only pointers within the file are checked, because -checking pointers to other files would be terribly slow. But those are -usually few. - -@findex Info-validate -To check an Info file, do @kbd{M-x Info-validate} while looking at any -node of the file with Emacs Info mode. - -@node Index -@unnumbered Index - -This is an alphabetical listing of all the commands, variables, and -topics discussed in this document. - -@printindex cp - -@bye - -@ignore - arch-tag: 965c1638-01d6-4156-9227-b10418b9d8e8 -@end ignore diff --git a/Build/source/utils/texinfo/doc/infokey.1 b/Build/source/utils/texinfo/doc/infokey.1 deleted file mode 100644 index f18df20d548..00000000000 --- a/Build/source/utils/texinfo/doc/infokey.1 +++ /dev/null @@ -1,42 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH INFOKEY "1" "April 2008" "infokey 4.12" "User Commands" -.SH NAME -infokey \- compile customizations for Info -.SH SYNOPSIS -.B infokey -[\fIOPTION\fR]... [\fIINPUT-FILE\fR] -.SH DESCRIPTION -Compile infokey source file to infokey file. Reads INPUT\-FILE (default -$HOME/.infokey) and writes compiled key file to (by default) $HOME/.info. -.SH OPTIONS -.TP -\fB\-\-output\fR FILE -output to FILE instead of $HOME/.info -.TP -\fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-version\fR -display version information and exit. -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B infokey -is maintained as a Texinfo manual. If the -.B info -and -.B infokey -programs are properly installed at your site, the command -.IP -.B info infokey -.PP -should give you access to the complete manual. diff --git a/Build/source/utils/texinfo/doc/install-info.1 b/Build/source/utils/texinfo/doc/install-info.1 deleted file mode 100644 index c0592b183d0..00000000000 --- a/Build/source/utils/texinfo/doc/install-info.1 +++ /dev/null @@ -1,129 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH INSTALL-INFO "1" "April 2008" "install-info 4.12" "User Commands" -.SH NAME -install-info \- update info/dir entries -.SH SYNOPSIS -.B install-info -[\fIOPTION\fR]... [\fIINFO-FILE \fR[\fIDIR-FILE\fR]] -.SH DESCRIPTION -Add or remove entries in INFO\-FILE from the Info directory DIR\-FILE. -.SH OPTIONS -.TP -\fB\-\-debug\fR -report what is being done. -.TP -\fB\-\-delete\fR -delete existing entries for INFO\-FILE from DIR\-FILE; -don't insert any new entries. -.TP -\fB\-\-description\fR=\fITEXT\fR -the description of the entry is TEXT; used with -the \fB\-\-name\fR option to become synonymous with the -\fB\-\-entry\fR option. -.TP -\fB\-\-dir\-file\fR=\fINAME\fR -specify file name of Info directory file; -equivalent to using the DIR\-FILE argument. -.TP -\fB\-\-dry\-run\fR -same as \fB\-\-test\fR. -.TP -\fB\-\-entry\fR=\fITEXT\fR -insert TEXT as an Info directory entry. -TEXT is written as an Info menu item line followed -.IP -by zero or more extra lines starting with whitespace. -.IP -If you specify more than one entry, all are added. -If you don't specify any entries, they are determined -.IP -from information in the Info file itself. -.IP -When removing, TEXT specifies the entry to remove. -TEXT is only removed as a last resort, if the -entry as determined from the Info file is not present, -and the basename of the Info file isn't found either. -.TP -\fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-info\-dir\fR=\fIDIR\fR -same as \fB\-\-dir\-file\fR=\fIDIR\fR/dir. -.TP -\fB\-\-info\-file\fR=\fIFILE\fR -specify Info file to install in the directory; -equivalent to using the INFO\-FILE argument. -.TP -\fB\-\-item\fR=\fITEXT\fR -same as \fB\-\-entry\fR=\fITEXT\fR. -.TP -\fB\-\-keep\-old\fR -do not replace entries, or remove empty sections. -.TP -\fB\-\-menuentry\fR=\fITEXT\fR -same as \fB\-\-name\fR=\fITEXT\fR. -.TP -\fB\-\-name\fR=\fITEXT\fR -the name of the entry is TEXT; used with \fB\-\-description\fR -to become synonymous with the \fB\-\-entry\fR option. -.TP -\fB\-\-no\-indent\fR -do not format new entries in the DIR file. -.TP -\fB\-\-quiet\fR -suppress warnings. -.TP -\fB\-\-regex\fR=\fIR\fR -put this file's entries in all sections that match the -regular expression R (ignoring case). -.TP -\fB\-\-remove\fR -same as \fB\-\-delete\fR. -.TP -\fB\-\-remove\-exactly\fR -only remove if the info file name matches exactly; -suffixes such as .info and .gz are not ignored. -.TP -\fB\-\-section\fR=\fISEC\fR -put entries in section SEC of the directory. -If you specify more than one section, all the entries -.IP -are added in each of the sections. -.IP -If you don't specify any sections, they are determined -.IP -from information in the Info file itself. -.TP -\fB\-\-section\fR R SEC -equivalent to \fB\-\-regex\fR=\fIR\fR \fB\-\-section\fR=\fISEC\fR \fB\-\-add\-once\fR. -.TP -\fB\-\-silent\fR -suppress warnings. -.TP -\fB\-\-test\fR -suppress updating of DIR\-FILE. -.TP -\fB\-\-version\fR -display version information and exit. -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B install-info -is maintained as a Texinfo manual. If the -.B info -and -.B install-info -programs are properly installed at your site, the command -.IP -.B info install-info -.PP -should give you access to the complete manual. diff --git a/Build/source/utils/texinfo/doc/makeinfo.1 b/Build/source/utils/texinfo/doc/makeinfo.1 deleted file mode 100644 index 0850e5f1b99..00000000000 --- a/Build/source/utils/texinfo/doc/makeinfo.1 +++ /dev/null @@ -1,219 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH MAKEINFO "1" "April 2008" "makeinfo 4.12" "User Commands" -.SH NAME -makeinfo \- translate Texinfo documents -.SH SYNOPSIS -.B makeinfo -[\fIOPTION\fR]... \fITEXINFO-FILE\fR... -.SH DESCRIPTION -Translate Texinfo source documentation to various other formats, by default -Info files suitable for reading online with Emacs or standalone GNU Info. -.SS "General options:" -.TP -\fB\-\-error\-limit\fR=\fINUM\fR -quit after NUM errors (default 100). -.TP -\fB\-\-document\-language\fR=\fISTR\fR locale to use in translating Texinfo keywords -for the output document (default C). -.TP -\fB\-\-force\fR -preserve output even if errors. -.TP -\fB\-\-help\fR -display this help and exit. -.TP -\fB\-\-no\-validate\fR -suppress node cross\-reference validation. -.TP -\fB\-\-no\-warn\fR -suppress warnings (but not errors). -.TP -\fB\-v\fR, \fB\-\-verbose\fR -explain what is being done. -.TP -\fB\-\-version\fR -display version information and exit. -.SS "Output format selection (default is to produce Info):" -.TP -\fB\-\-docbook\fR -output Docbook XML rather than Info. -.TP -\fB\-\-html\fR -output HTML rather than Info. -.TP -\fB\-\-xml\fR -output Texinfo XML rather than Info. -.TP -\fB\-\-plaintext\fR -output plain text rather than Info. -.SS "General output options:" -.TP -\fB\-E\fR, \fB\-\-macro\-expand\fR=\fIFILE\fR -output macro\-expanded source to FILE, -ignoring any @setfilename. -.TP -\fB\-\-no\-headers\fR -suppress node separators, Node: lines, and menus -from Info output (thus producing plain text) -or from HTML (thus producing shorter output); -also, write to standard output by default. -.TP -\fB\-\-no\-split\fR -suppress the splitting of Info or HTML output, -generate only one output file. -.TP -\fB\-\-number\-sections\fR -output chapter and sectioning numbers. -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIFILE\fR -output to FILE (or directory if split HTML). -.SS "Options for Info and plain text:" -.TP -\fB\-\-disable\-encoding\fR -do not output accented and special characters -in Info output based on @documentencoding. -.TP -\fB\-\-enable\-encoding\fR -override \fB\-\-disable\-encoding\fR (default). -.TP -\fB\-\-fill\-column\fR=\fINUM\fR -break Info lines at NUM characters (default 72). -.TP -\fB\-\-footnote\-style\fR=\fISTYLE\fR -output footnotes in Info according to STYLE: -`separate' to put them in their own node; -`end' to put them at the end of the node, in -which they are defined (this is the default). -.TP -\fB\-\-paragraph\-indent\fR=\fIVAL\fR -indent Info paragraphs by VAL spaces (default 3). -If VAL is `none', do not indent; if VAL is -`asis', preserve existing indentation. -.TP -\fB\-\-split\-size\fR=\fINUM\fR -split Info files at size NUM (default 300000). -.SS "Options for HTML:" -.TP -\fB\-\-css\-include\fR=\fIFILE\fR -include FILE in HTML <style> output; -read stdin if FILE is \-. -.TP -\fB\-\-css\-ref\fR=\fIURL\fR -generate reference to a CSS file. -.TP -\fB\-\-transliterate\-file\-names\fR -produce file names in ASCII transliteration. -.SS "Options for XML and Docbook:" -.TP -\fB\-\-output\-indent\fR=\fIVAL\fR -indent XML elements by VAL spaces (default 2). -If VAL is 0, ignorable whitespace is dropped. -.SS "Input file options:" -.TP -\fB\-\-commands\-in\-node\-names\fR -allow @ commands in node names. -.TP -\fB\-D\fR VAR -define the variable VAR, as with @set. -.TP -\fB\-I\fR DIR -append DIR to the @include search path. -.TP -\fB\-P\fR DIR -prepend DIR to the @include search path. -.TP -\fB\-U\fR VAR -undefine the variable VAR, as with @clear. -.SS "Conditional processing in input:" -.TP -\fB\-\-ifdocbook\fR -process @ifdocbook and @docbook even if -not generating Docbook. -.TP -\fB\-\-ifhtml\fR -process @ifhtml and @html even if not generating HTML. -.TP -\fB\-\-ifinfo\fR -process @ifinfo even if not generating Info. -.TP -\fB\-\-ifplaintext\fR -process @ifplaintext even if not generating plain text. -.TP -\fB\-\-iftex\fR -process @iftex and @tex; implies \fB\-\-no\-split\fR. -.TP -\fB\-\-ifxml\fR -process @ifxml and @xml. -.TP -\fB\-\-no\-ifdocbook\fR -do not process @ifdocbook and @docbook text. -.TP -\fB\-\-no\-ifhtml\fR -do not process @ifhtml and @html text. -.TP -\fB\-\-no\-ifinfo\fR -do not process @ifinfo text. -.TP -\fB\-\-no\-ifplaintext\fR -do not process @ifplaintext text. -.TP -\fB\-\-no\-iftex\fR -do not process @iftex and @tex text. -.TP -\fB\-\-no\-ifxml\fR -do not process @ifxml and @xml text. -.P -Also, for the \fB\-\-no\-ifFORMAT\fR options, do process @ifnotFORMAT text. -.P -The defaults for the @if... conditionals depend on the output format: -if generating HTML, \fB\-\-ifhtml\fR is on and the others are off; -if generating Info, \fB\-\-ifinfo\fR is on and the others are off; -if generating plain text, \fB\-\-ifplaintext\fR is on and the others are off; -if generating XML, \fB\-\-ifxml\fR is on and the others are off. -.SH EXAMPLES -.TP -makeinfo foo.texi -write Info to foo's @setfilename -.TP -makeinfo \fB\-\-html\fR foo.texi -write HTML to @setfilename -.TP -makeinfo \fB\-\-xml\fR foo.texi -write Texinfo XML to @setfilename -.TP -makeinfo \fB\-\-docbook\fR foo.texi -write DocBook XML to @setfilename -.TP -makeinfo \fB\-\-no\-headers\fR foo.texi -write plain text to standard output -.TP -makeinfo \fB\-\-html\fR \fB\-\-no\-headers\fR foo.texi -write html without node lines, menus -.TP -makeinfo \fB\-\-number\-sections\fR foo.texi -write Info with numbered sections -.TP -makeinfo \fB\-\-no\-split\fR foo.texi -write one Info file however big -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B makeinfo -is maintained as a Texinfo manual. If the -.B info -and -.B makeinfo -programs are properly installed at your site, the command -.IP -.B info makeinfo -.PP -should give you access to the complete manual. diff --git a/Build/source/utils/texinfo/doc/mdate-sh b/Build/source/utils/texinfo/doc/mdate-sh deleted file mode 100755 index 881782eb55e..00000000000 --- a/Build/source/utils/texinfo/doc/mdate-sh +++ /dev/null @@ -1,170 +0,0 @@ -#!/bin/sh -# Get modification time of a file or directory and pretty-print it. - -scriptversion=2004-12-08.12 - -# Copyright (C) 1995, 1996, 1997, 2003, 2004 Free Software Foundation, Inc. -# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995 -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software Foundation, -# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - -# As a special exception to the GNU General Public License, if you -# distribute this file as part of a program that contains a -# configuration script generated by Autoconf, you may include it under -# the same distribution terms that you use for the rest of that program. - -# This file is maintained in Automake, please report -# bugs to <bug-automake@gnu.org> or send patches to -# <automake-patches@gnu.org>. - -case $1 in - '') - echo "$0: No file. Try \`$0 --help' for more information." 1>&2 - exit 1; - ;; - -h | --h*) - cat <<\EOF -Usage: mdate-sh [--help] [--version] FILE - -Pretty-print the modification time of FILE. - -Report bugs to <bug-automake@gnu.org>. -EOF - exit 0 - ;; - -v | --v*) - echo "mdate-sh $scriptversion" - exit 0 - ;; -esac - -# Prevent date giving response in another language. -LANG=C -export LANG -LC_ALL=C -export LC_ALL -LC_TIME=C -export LC_TIME - -save_arg1="$1" - -# Find out how to get the extended ls output of a file or directory. -if ls -L /dev/null 1>/dev/null 2>&1; then - ls_command='ls -L -l -d' -else - ls_command='ls -l -d' -fi - -# A `ls -l' line looks as follows on OS/2. -# drwxrwx--- 0 Aug 11 2001 foo -# This differs from Unix, which adds ownership information. -# drwxrwx--- 2 root root 4096 Aug 11 2001 foo -# -# To find the date, we split the line on spaces and iterate on words -# until we find a month. This cannot work with files whose owner is a -# user named `Jan', or `Feb', etc. However, it's unlikely that `/' -# will be owned by a user whose name is a month. So we first look at -# the extended ls output of the root directory to decide how many -# words should be skipped to get the date. - -# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. -set x`ls -l -d /` - -# Find which argument is the month. -month= -command= -until test $month -do - shift - # Add another shift to the command. - command="$command shift;" - case $1 in - Jan) month=January; nummonth=1;; - Feb) month=February; nummonth=2;; - Mar) month=March; nummonth=3;; - Apr) month=April; nummonth=4;; - May) month=May; nummonth=5;; - Jun) month=June; nummonth=6;; - Jul) month=July; nummonth=7;; - Aug) month=August; nummonth=8;; - Sep) month=September; nummonth=9;; - Oct) month=October; nummonth=10;; - Nov) month=November; nummonth=11;; - Dec) month=December; nummonth=12;; - esac -done - -# Get the extended ls output of the file or directory. -set x`eval "$ls_command \"\$save_arg1\""` - -# Remove all preceding arguments -eval $command - -# Get the month. Next argument is day, followed by the year or time. -case $1 in - Jan) month=January; nummonth=1;; - Feb) month=February; nummonth=2;; - Mar) month=March; nummonth=3;; - Apr) month=April; nummonth=4;; - May) month=May; nummonth=5;; - Jun) month=June; nummonth=6;; - Jul) month=July; nummonth=7;; - Aug) month=August; nummonth=8;; - Sep) month=September; nummonth=9;; - Oct) month=October; nummonth=10;; - Nov) month=November; nummonth=11;; - Dec) month=December; nummonth=12;; -esac - -day=$2 - -# Here we have to deal with the problem that the ls output gives either -# the time of day or the year. -case $3 in - *:*) set `date`; eval year=\$$# - case $2 in - Jan) nummonthtod=1;; - Feb) nummonthtod=2;; - Mar) nummonthtod=3;; - Apr) nummonthtod=4;; - May) nummonthtod=5;; - Jun) nummonthtod=6;; - Jul) nummonthtod=7;; - Aug) nummonthtod=8;; - Sep) nummonthtod=9;; - Oct) nummonthtod=10;; - Nov) nummonthtod=11;; - Dec) nummonthtod=12;; - esac - # For the first six month of the year the time notation can also - # be used for files modified in the last year. - if (expr $nummonth \> $nummonthtod) > /dev/null; - then - year=`expr $year - 1` - fi;; - *) year=$3;; -esac - -# The result. -echo $day $month $year - -# Local Variables: -# mode: shell-script -# sh-indentation: 2 -# eval: (add-hook 'write-file-hooks 'time-stamp) -# time-stamp-start: "scriptversion=" -# time-stamp-format: "%:y-%02m-%02d.%02H" -# time-stamp-end: "$" -# End: diff --git a/Build/source/utils/texinfo/doc/pdfcolor.tex b/Build/source/utils/texinfo/doc/pdfcolor.tex deleted file mode 100644 index f09ecbcb750..00000000000 --- a/Build/source/utils/texinfo/doc/pdfcolor.tex +++ /dev/null @@ -1,158 +0,0 @@ -% Very simple macros to show how to use colors with pdftex - -\def\cmykGreenYellow{0.15 0 0.69 0} -\def\cmykYellow{0 0 1 0} -\def\cmykGoldenrod{0 0.10 0.84 0} -\def\cmykDandelion{0 0.29 0.84 0} -\def\cmykApricot{0 0.32 0.52 0} -\def\cmykPeach{0 0.50 0.70 0} -\def\cmykMelon{0 0.46 0.50 0} -\def\cmykYellowOrange{0 0.42 1 0} -\def\cmykOrange{0 0.61 0.87 0} -\def\cmykBurntOrange{0 0.51 1 0} -\def\cmykBittersweet{0 0.75 1 0.24} -\def\cmykRedOrange{0 0.77 0.87 0} -\def\cmykMahogany{0 0.85 0.87 0.35} -\def\cmykMaroon{0 0.87 0.68 0.32} -\def\cmykBrickRed{0 0.89 0.94 0.28} -\def\cmykRed{0 1 1 0} -\def\cmykOrangeRed{0 1 0.50 0} -\def\cmykRubineRed{0 1 0.13 0} -\def\cmykWildStrawberry{0 0.96 0.39 0} -\def\cmykSalmon{0 0.53 0.38 0} -\def\cmykCarnationPink{0 0.63 0 0} -\def\cmykMagenta{0 1 0 0} -\def\cmykVioletRed{0 0.81 0 0} -\def\cmykRhodamine{0 0.82 0 0} -\def\cmykMulberry{0.34 0.90 0 0.02} -\def\cmykRedViolet{0.07 0.90 0 0.34} -\def\cmykFuchsia{0.47 0.91 0 0.08} -\def\cmykLavender{0 0.48 0 0} -\def\cmykThistle{0.12 0.59 0 0} -\def\cmykOrchid{0.32 0.64 0 0} -\def\cmykDarkOrchid{0.40 0.80 0.20 0} -\def\cmykPurple{0.45 0.86 0 0} -\def\cmykPlum{0.50 1 0 0} -\def\cmykViolet{0.79 0.88 0 0} -\def\cmykRoyalPurple{0.75 0.90 0 0} -\def\cmykBlueViolet{0.86 0.91 0 0.04} -\def\cmykPeriwinkle{0.57 0.55 0 0} -\def\cmykCadetBlue{0.62 0.57 0.23 0} -\def\cmykCornflowerBlue{0.65 0.13 0 0} -\def\cmykMidnightBlue{0.98 0.13 0 0.43} -\def\cmykNavyBlue{0.94 0.54 0 0} -\def\cmykRoyalBlue{1 0.50 0 0} -\def\cmykBlue{1 1 0 0} -\def\cmykCerulean{0.94 0.11 0 0} -\def\cmykCyan{1 0 0 0} -\def\cmykProcessBlue{0.96 0 0 0} -\def\cmykSkyBlue{0.62 0 0.12 0} -\def\cmykTurquoise{0.85 0 0.20 0} -\def\cmykTealBlue{0.86 0 0.34 0.02} -\def\cmykAquamarine{0.82 0 0.30 0} -\def\cmykBlueGreen{0.85 0 0.33 0} -\def\cmykEmerald{1 0 0.50 0} -\def\cmykJungleGreen{0.99 0 0.52 0} -\def\cmykSeaGreen{0.69 0 0.50 0} -\def\cmykGreen{1 0 1 0} -\def\cmykForestGreen{0.91 0 0.88 0.12} -\def\cmykPineGreen{0.92 0 0.59 0.25} -\def\cmykLimeGreen{0.50 0 1 0} -\def\cmykYellowGreen{0.44 0 0.74 0} -\def\cmykSpringGreen{0.26 0 0.76 0} -\def\cmykOliveGreen{0.64 0 0.95 0.40} -\def\cmykRawSienna{0 0.72 1 0.45} -\def\cmykSepia{0 0.83 1 0.70} -\def\cmykBrown{0 0.81 1 0.60} -\def\cmykTan{0.14 0.42 0.56 0} -\def\cmykGray{0 0 0 0.50} -\def\cmykBlack{0 0 0 1} -\def\cmykWhite{0 0 0 0} - -\def\GreenYellow{\pdfsetcolor{\cmykGreenYellow}} -\def\Yellow{\pdfsetcolor{\cmykYellow}} -\def\Goldenrod{\pdfsetcolor{\cmykGoldenrod}} -\def\Dandelion{\pdfsetcolor{\cmykDandelion}} -\def\Apricot{\pdfsetcolor{\cmykApricot}} -\def\Peach{\pdfsetcolor{\cmykPeach}} -\def\Melon{\pdfsetcolor{\cmykMelon}} -\def\YellowOrange{\pdfsetcolor{\cmykYellowOrange}} -\def\Orange{\pdfsetcolor{\cmykOrange}} -\def\BurntOrange{\pdfsetcolor{\cmykBurntOrange}} -\def\Bittersweet{\pdfsetcolor{\cmykBittersweet}} -\def\RedOrange{\pdfsetcolor{\cmykRedOrange}} -\def\Mahogany{\pdfsetcolor{\cmykMahogany}} -\def\Maroon{\pdfsetcolor{\cmykMaroon}} -\def\BrickRed{\pdfsetcolor{\cmykBrickRed}} -\def\Red{\pdfsetcolor{\cmykRed}} -\def\OrangeRed{\pdfsetcolor{\cmykOrangeRed}} -\def\RubineRed{\pdfsetcolor{\cmykRubineRed}} -\def\WildStrawberry{\pdfsetcolor{\cmykWildStrawberry}} -\def\Salmon{\pdfsetcolor{\cmykSalmon}} -\def\CarnationPink{\pdfsetcolor{\cmykCarnationPink}} -\def\Magenta{\pdfsetcolor{\cmykMagenta}} -\def\VioletRed{\pdfsetcolor{\cmykVioletRed}} -\def\Rhodamine{\pdfsetcolor{\cmykRhodamine}} -\def\Mulberry{\pdfsetcolor{\cmykMulberry}} -\def\RedViolet{\pdfsetcolor{\cmykRedViolet}} -\def\Fuchsia{\pdfsetcolor{\cmykFuchsia}} -\def\Lavender{\pdfsetcolor{\cmykLavender}} -\def\Thistle{\pdfsetcolor{\cmykThistle}} -\def\Orchid{\pdfsetcolor{\cmykOrchid}} -\def\DarkOrchid{\pdfsetcolor{\cmykDarkOrchid}} -\def\Purple{\pdfsetcolor{\cmykPurple}} -\def\Plum{\pdfsetcolor{\cmykPlum}} -\def\Violet{\pdfsetcolor{\cmykViolet}} -\def\RoyalPurple{\pdfsetcolor{\cmykRoyalPurple}} -\def\BlueViolet{\pdfsetcolor{\cmykBlueViolet}} -\def\Periwinkle{\pdfsetcolor{\cmykPeriwinkle}} -\def\CadetBlue{\pdfsetcolor{\cmykCadetBlue}} -\def\CornflowerBlue{\pdfsetcolor{\cmykCornflowerBlue}} -\def\MidnightBlue{\pdfsetcolor{\cmykMidnightBlue}} -\def\NavyBlue{\pdfsetcolor{\cmykNavyBlue}} -\def\RoyalBlue{\pdfsetcolor{\cmykRoyalBlue}} -\def\Blue{\pdfsetcolor{\cmykBlue}} -\def\Cerulean{\pdfsetcolor{\cmykCerulean}} -\def\Cyan{\pdfsetcolor{\cmykCyan}} -\def\ProcessBlue{\pdfsetcolor{\cmykProcessBlue}} -\def\SkyBlue{\pdfsetcolor{\cmykSkyBlue}} -\def\Turquoise{\pdfsetcolor{\cmykTurquoise}} -\def\TealBlue{\pdfsetcolor{\cmykTealBlue}} -\def\Aquamarine{\pdfsetcolor{\cmykAquamarine}} -\def\BlueGreen{\pdfsetcolor{\cmykBlueGreen}} -\def\Emerald{\pdfsetcolor{\cmykEmerald}} -\def\JungleGreen{\pdfsetcolor{\cmykJungleGreen}} -\def\SeaGreen{\pdfsetcolor{\cmykSeaGreen}} -\def\Green{\pdfsetcolor{\cmykGreen}} -\def\ForestGreen{\pdfsetcolor{\cmykForestGreen}} -\def\PineGreen{\pdfsetcolor{\cmykPineGreen}} -\def\LimeGreen{\pdfsetcolor{\cmykLimeGreen}} -\def\YellowGreen{\pdfsetcolor{\cmykYellowGreen}} -\def\SpringGreen{\pdfsetcolor{\cmykSpringGreen}} -\def\OliveGreen{\pdfsetcolor{\cmykOliveGreen}} -\def\RawSienna{\pdfsetcolor{\cmykRawSienna}} -\def\Sepia{\pdfsetcolor{\cmykSepia}} -\def\Brown{\pdfsetcolor{\cmykBrown}} -\def\Tan{\pdfsetcolor{\cmykTan}} -\def\Gray{\pdfsetcolor{\cmykGray}} -\def\Black{\pdfsetcolor{\cmykBlack}} -\def\White{\pdfsetcolor{\cmykWhite}} - -\def\pdfsetcolor#1{\pdfliteral{#1 k}} -\def\setcolor#1{\mark{#1}\pdfsetcolor{#1}} - -\pdfoutput=1 -\def\maincolor{\cmykBlack} -\pdfsetcolor{\maincolor} - -\def\makefootline{ - \baselineskip24pt - \line{\pdfsetcolor{\maincolor}\the\footline}} - -\def\makeheadline{% - \edef\M{\topmark} - \ifx\M\empty\let\M=\maincolor\fi - \vbox to 0pt{\vskip-22.5pt - \line{\vbox to8.5pt{}% - \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\M}}\vss}% - \nointerlineskip} diff --git a/Build/source/utils/texinfo/doc/pdftexi2dvi.1 b/Build/source/utils/texinfo/doc/pdftexi2dvi.1 deleted file mode 100644 index e9b0f08c1a6..00000000000 --- a/Build/source/utils/texinfo/doc/pdftexi2dvi.1 +++ /dev/null @@ -1,185 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXI2DVI "1" "April 2008" "texi2dvi 1.122" "User Commands" -.SH NAME -texi2dvi \- convert Texinfo documents to PDF -.SH SYNOPSIS -.B texi2dvi -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Run each Texinfo or (La)TeX FILE through TeX in turn until all -cross\-references are resolved, building all indices. The directory -containing each FILE is searched for included files. The suffix of FILE -is used to determine its language ((La)TeX or Texinfo). To process -(e)plain TeX files, set the environment variable LATEX=tex. -.PP -In order to make texi2dvi a drop\-in replacement of TeX/LaTeX in AUC\-TeX, -the FILE may also be composed of the following simple TeX commands. -.TP -`\einput{FILE}' -the actual file to compile -.TP -`\enonstopmode' -same as \fB\-\-batch\fR -.PP -Makeinfo is used to perform Texinfo macro expansion before running TeX -when needed. -.SS "General options:" -.TP -\fB\-b\fR, \fB\-\-batch\fR -no interaction -.TP -\fB\-D\fR, \fB\-\-debug\fR -turn on shell debugging (set \fB\-x\fR) -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit successfully -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIOFILE\fR -leave output in OFILE (implies \fB\-\-clean\fR); -only one input FILE may be specified in this case -.TP -\fB\-q\fR, \fB\-\-quiet\fR -no output unless errors (implies \fB\-\-batch\fR) -.TP -\fB\-s\fR, \fB\-\-silent\fR -same as \fB\-\-quiet\fR -.TP -\fB\-v\fR, \fB\-\-version\fR -display version information and exit successfully -.TP -\fB\-V\fR, \fB\-\-verbose\fR -report on what is done -.SS "TeX tuning:" -.TP -\-@ -use @input instead of \einput for preloaded Texinfo -.TP -\fB\-\-dvi\fR -output a DVI file [default] -.TP -\fB\-e\fR, \fB\-E\fR, \fB\-\-expand\fR -force macro expansion using makeinfo -.TP -\fB\-I\fR DIR -search DIR for Texinfo files -.TP -\fB\-l\fR, \fB\-\-language\fR=\fILANG\fR -specify the LANG of FILE (LaTeX or Texinfo) -.TP -\fB\-\-no\-line\-error\fR -do not pass \fB\-\-file\-line\-error\fR to TeX -.TP -\fB\-p\fR, \fB\-\-pdf\fR -use pdftex or pdflatex for processing -.TP -\fB\-r\fR, \fB\-\-recode\fR -call recode before TeX to translate input -.TP -\fB\-\-recode\-from\fR=\fIENC\fR -recode from ENC to the @documentencoding -.TP -\fB\-\-src\-specials\fR -pass \fB\-\-src\-specials\fR to TeX -.TP -\fB\-t\fR, \fB\-\-command\fR=\fICMD\fR -insert CMD in copy of input file -.TP -or \fB\-\-texinfo\fR=\fICMD\fR -multiple values accumulate -.TP -\fB\-\-translate\-file\fR=\fIFILE\fR -use given charset translation file for TeX -.SS "Build modes:" -.TP -\fB\-\-build\fR=\fIMODE\fR -specify the treatment of auxiliary files [local] -.TP -\fB\-\-tidy\fR -same as \fB\-\-build\fR=\fItidy\fR -.TP -\fB\-c\fR, \fB\-\-clean\fR -same as \fB\-\-build\fR=\fIclean\fR -.TP -\fB\-\-build\-dir\fR=\fIDIR\fR -specify where the tidy compilation is performed; -implies \fB\-\-tidy\fR; -defaults to TEXI2DVI_BUILD_DIRECTORY [.] -.TP -\fB\-\-mostly\-clean\fR -remove the auxiliary files and directories -but not the output -.PP -The MODE specifies where the TeX compilation takes place, and, as a -consequence, how auxiliary files are treated. The build mode -can also be set using the environment variable TEXI2DVI_BUILD_MODE. -.SS "Valid MODEs are:" -.TP -`local' -compile in the current directory, leaving all the auxiliary -files around. This is the traditional TeX use. -.TP -`tidy' -compile in a local *.t2d directory, where the auxiliary files -are left. Output files are copied back to the original file. -.TP -`clean' -same as `tidy', but remove the auxiliary directory afterwards. -Every compilation therefore requires the full cycle. -.SS "Using the `tidy' mode brings several advantages:" -.TP -\- -the current directory is not cluttered with plethora of temporary files. -.TP -\- -clutter can be even reduced using \fB\-\-build\-dir\fR=\fIdir\fR: all the *.t2d -directories are stored there. -.TP -\- -clutter can be reduced to zero using, e.g., \fB\-\-build\-dir=\fR/tmp/$USER.t2d -or \fB\-\-build\-dir=\fR$HOME/.t2d. -.TP -\- -the output file is updated after every succesful TeX run, for -sake of concurrent visualization of the output. In a `local' build -the viewer stops during the whole TeX run. -.TP -\- -if the compilation fails, the previous state of the output file -is preserved. -.TP -\- -PDF and DVI compilation are kept in separate subdirectories -preventing any possibility of auxiliary file incompatibility. -.PP -On the other hand, because `tidy' compilation takes place in another -directory, occasionally TeX won't be able to find some files (e.g., when -using \egraphicspath): in that case use \fB\-I\fR to specify the additional -directories to consider. -.PP -The values of the BIBTEX, LATEX (or PDFLATEX), MAKEINDEX, MAKEINFO, -TEX (or PDFTEX), TEXINDEX, and THUMBPDF environment variables are used -to run those commands, if they are set. Any CMD strings are added -after @setfilename for Texinfo input, in the first line for LaTeX input. -.SH "REPORTING BUGS" -Email bug reports to <bug\-texinfo@gnu.org>, -general questions and discussion to <help\-texinfo@gnu.org>. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texi2dvi -is maintained as a Texinfo manual. If the -.B info -and -.B texi2dvi -programs are properly installed at your site, the command -.IP -.B info texi2dvi -.PP -should give you access to the complete manual. - diff --git a/Build/source/utils/texinfo/doc/stamp-1 b/Build/source/utils/texinfo/doc/stamp-1 deleted file mode 100644 index a1b0be3185b..00000000000 --- a/Build/source/utils/texinfo/doc/stamp-1 +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 5 March 2008 -@set UPDATED-MONTH March 2008 -@set EDITION 4.12 -@set VERSION 4.12 diff --git a/Build/source/utils/texinfo/doc/stamp-vti b/Build/source/utils/texinfo/doc/stamp-vti deleted file mode 100644 index da6f3285a4c..00000000000 --- a/Build/source/utils/texinfo/doc/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 9 April 2008 -@set UPDATED-MONTH April 2008 -@set EDITION 4.12 -@set VERSION 4.12 diff --git a/Build/source/utils/texinfo/doc/texi2dvi.1 b/Build/source/utils/texinfo/doc/texi2dvi.1 deleted file mode 100644 index 651812b7ccd..00000000000 --- a/Build/source/utils/texinfo/doc/texi2dvi.1 +++ /dev/null @@ -1,185 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXI2DVI "1" "April 2008" "texi2dvi 1.122" "User Commands" -.SH NAME -texi2dvi \- convert Texinfo documents to DVI -.SH SYNOPSIS -.B texi2dvi -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Run each Texinfo or (La)TeX FILE through TeX in turn until all -cross\-references are resolved, building all indices. The directory -containing each FILE is searched for included files. The suffix of FILE -is used to determine its language ((La)TeX or Texinfo). To process -(e)plain TeX files, set the environment variable LATEX=tex. -.PP -In order to make texi2dvi a drop\-in replacement of TeX/LaTeX in AUC\-TeX, -the FILE may also be composed of the following simple TeX commands. -.TP -`\einput{FILE}' -the actual file to compile -.TP -`\enonstopmode' -same as \fB\-\-batch\fR -.PP -Makeinfo is used to perform Texinfo macro expansion before running TeX -when needed. -.SS "General options:" -.TP -\fB\-b\fR, \fB\-\-batch\fR -no interaction -.TP -\fB\-D\fR, \fB\-\-debug\fR -turn on shell debugging (set \fB\-x\fR) -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit successfully -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIOFILE\fR -leave output in OFILE (implies \fB\-\-clean\fR); -only one input FILE may be specified in this case -.TP -\fB\-q\fR, \fB\-\-quiet\fR -no output unless errors (implies \fB\-\-batch\fR) -.TP -\fB\-s\fR, \fB\-\-silent\fR -same as \fB\-\-quiet\fR -.TP -\fB\-v\fR, \fB\-\-version\fR -display version information and exit successfully -.TP -\fB\-V\fR, \fB\-\-verbose\fR -report on what is done -.SS "TeX tuning:" -.TP -\-@ -use @input instead of \einput for preloaded Texinfo -.TP -\fB\-\-dvi\fR -output a DVI file [default] -.TP -\fB\-e\fR, \fB\-E\fR, \fB\-\-expand\fR -force macro expansion using makeinfo -.TP -\fB\-I\fR DIR -search DIR for Texinfo files -.TP -\fB\-l\fR, \fB\-\-language\fR=\fILANG\fR -specify the LANG of FILE (LaTeX or Texinfo) -.TP -\fB\-\-no\-line\-error\fR -do not pass \fB\-\-file\-line\-error\fR to TeX -.TP -\fB\-p\fR, \fB\-\-pdf\fR -use pdftex or pdflatex for processing -.TP -\fB\-r\fR, \fB\-\-recode\fR -call recode before TeX to translate input -.TP -\fB\-\-recode\-from\fR=\fIENC\fR -recode from ENC to the @documentencoding -.TP -\fB\-\-src\-specials\fR -pass \fB\-\-src\-specials\fR to TeX -.TP -\fB\-t\fR, \fB\-\-command\fR=\fICMD\fR -insert CMD in copy of input file -.TP -or \fB\-\-texinfo\fR=\fICMD\fR -multiple values accumulate -.TP -\fB\-\-translate\-file\fR=\fIFILE\fR -use given charset translation file for TeX -.SS "Build modes:" -.TP -\fB\-\-build\fR=\fIMODE\fR -specify the treatment of auxiliary files [local] -.TP -\fB\-\-tidy\fR -same as \fB\-\-build\fR=\fItidy\fR -.TP -\fB\-c\fR, \fB\-\-clean\fR -same as \fB\-\-build\fR=\fIclean\fR -.TP -\fB\-\-build\-dir\fR=\fIDIR\fR -specify where the tidy compilation is performed; -implies \fB\-\-tidy\fR; -defaults to TEXI2DVI_BUILD_DIRECTORY [.] -.TP -\fB\-\-mostly\-clean\fR -remove the auxiliary files and directories -but not the output -.PP -The MODE specifies where the TeX compilation takes place, and, as a -consequence, how auxiliary files are treated. The build mode -can also be set using the environment variable TEXI2DVI_BUILD_MODE. -.SS "Valid MODEs are:" -.TP -`local' -compile in the current directory, leaving all the auxiliary -files around. This is the traditional TeX use. -.TP -`tidy' -compile in a local *.t2d directory, where the auxiliary files -are left. Output files are copied back to the original file. -.TP -`clean' -same as `tidy', but remove the auxiliary directory afterwards. -Every compilation therefore requires the full cycle. -.SS "Using the `tidy' mode brings several advantages:" -.TP -\- -the current directory is not cluttered with plethora of temporary files. -.TP -\- -clutter can be even reduced using \fB\-\-build\-dir\fR=\fIdir\fR: all the *.t2d -directories are stored there. -.TP -\- -clutter can be reduced to zero using, e.g., \fB\-\-build\-dir=\fR/tmp/$USER.t2d -or \fB\-\-build\-dir=\fR$HOME/.t2d. -.TP -\- -the output file is updated after every succesful TeX run, for -sake of concurrent visualization of the output. In a `local' build -the viewer stops during the whole TeX run. -.TP -\- -if the compilation fails, the previous state of the output file -is preserved. -.TP -\- -PDF and DVI compilation are kept in separate subdirectories -preventing any possibility of auxiliary file incompatibility. -.PP -On the other hand, because `tidy' compilation takes place in another -directory, occasionally TeX won't be able to find some files (e.g., when -using \egraphicspath): in that case use \fB\-I\fR to specify the additional -directories to consider. -.PP -The values of the BIBTEX, LATEX (or PDFLATEX), MAKEINDEX, MAKEINFO, -TEX (or PDFTEX), TEXINDEX, and THUMBPDF environment variables are used -to run those commands, if they are set. Any CMD strings are added -after @setfilename for Texinfo input, in the first line for LaTeX input. -.SH "REPORTING BUGS" -Email bug reports to <bug\-texinfo@gnu.org>, -general questions and discussion to <help\-texinfo@gnu.org>. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texi2dvi -is maintained as a Texinfo manual. If the -.B info -and -.B texi2dvi -programs are properly installed at your site, the command -.IP -.B info texi2dvi -.PP -should give you access to the complete manual. - diff --git a/Build/source/utils/texinfo/doc/texi2pdf.1 b/Build/source/utils/texinfo/doc/texi2pdf.1 deleted file mode 100644 index e9b0f08c1a6..00000000000 --- a/Build/source/utils/texinfo/doc/texi2pdf.1 +++ /dev/null @@ -1,185 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXI2DVI "1" "April 2008" "texi2dvi 1.122" "User Commands" -.SH NAME -texi2dvi \- convert Texinfo documents to PDF -.SH SYNOPSIS -.B texi2dvi -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Run each Texinfo or (La)TeX FILE through TeX in turn until all -cross\-references are resolved, building all indices. The directory -containing each FILE is searched for included files. The suffix of FILE -is used to determine its language ((La)TeX or Texinfo). To process -(e)plain TeX files, set the environment variable LATEX=tex. -.PP -In order to make texi2dvi a drop\-in replacement of TeX/LaTeX in AUC\-TeX, -the FILE may also be composed of the following simple TeX commands. -.TP -`\einput{FILE}' -the actual file to compile -.TP -`\enonstopmode' -same as \fB\-\-batch\fR -.PP -Makeinfo is used to perform Texinfo macro expansion before running TeX -when needed. -.SS "General options:" -.TP -\fB\-b\fR, \fB\-\-batch\fR -no interaction -.TP -\fB\-D\fR, \fB\-\-debug\fR -turn on shell debugging (set \fB\-x\fR) -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit successfully -.TP -\fB\-o\fR, \fB\-\-output\fR=\fIOFILE\fR -leave output in OFILE (implies \fB\-\-clean\fR); -only one input FILE may be specified in this case -.TP -\fB\-q\fR, \fB\-\-quiet\fR -no output unless errors (implies \fB\-\-batch\fR) -.TP -\fB\-s\fR, \fB\-\-silent\fR -same as \fB\-\-quiet\fR -.TP -\fB\-v\fR, \fB\-\-version\fR -display version information and exit successfully -.TP -\fB\-V\fR, \fB\-\-verbose\fR -report on what is done -.SS "TeX tuning:" -.TP -\-@ -use @input instead of \einput for preloaded Texinfo -.TP -\fB\-\-dvi\fR -output a DVI file [default] -.TP -\fB\-e\fR, \fB\-E\fR, \fB\-\-expand\fR -force macro expansion using makeinfo -.TP -\fB\-I\fR DIR -search DIR for Texinfo files -.TP -\fB\-l\fR, \fB\-\-language\fR=\fILANG\fR -specify the LANG of FILE (LaTeX or Texinfo) -.TP -\fB\-\-no\-line\-error\fR -do not pass \fB\-\-file\-line\-error\fR to TeX -.TP -\fB\-p\fR, \fB\-\-pdf\fR -use pdftex or pdflatex for processing -.TP -\fB\-r\fR, \fB\-\-recode\fR -call recode before TeX to translate input -.TP -\fB\-\-recode\-from\fR=\fIENC\fR -recode from ENC to the @documentencoding -.TP -\fB\-\-src\-specials\fR -pass \fB\-\-src\-specials\fR to TeX -.TP -\fB\-t\fR, \fB\-\-command\fR=\fICMD\fR -insert CMD in copy of input file -.TP -or \fB\-\-texinfo\fR=\fICMD\fR -multiple values accumulate -.TP -\fB\-\-translate\-file\fR=\fIFILE\fR -use given charset translation file for TeX -.SS "Build modes:" -.TP -\fB\-\-build\fR=\fIMODE\fR -specify the treatment of auxiliary files [local] -.TP -\fB\-\-tidy\fR -same as \fB\-\-build\fR=\fItidy\fR -.TP -\fB\-c\fR, \fB\-\-clean\fR -same as \fB\-\-build\fR=\fIclean\fR -.TP -\fB\-\-build\-dir\fR=\fIDIR\fR -specify where the tidy compilation is performed; -implies \fB\-\-tidy\fR; -defaults to TEXI2DVI_BUILD_DIRECTORY [.] -.TP -\fB\-\-mostly\-clean\fR -remove the auxiliary files and directories -but not the output -.PP -The MODE specifies where the TeX compilation takes place, and, as a -consequence, how auxiliary files are treated. The build mode -can also be set using the environment variable TEXI2DVI_BUILD_MODE. -.SS "Valid MODEs are:" -.TP -`local' -compile in the current directory, leaving all the auxiliary -files around. This is the traditional TeX use. -.TP -`tidy' -compile in a local *.t2d directory, where the auxiliary files -are left. Output files are copied back to the original file. -.TP -`clean' -same as `tidy', but remove the auxiliary directory afterwards. -Every compilation therefore requires the full cycle. -.SS "Using the `tidy' mode brings several advantages:" -.TP -\- -the current directory is not cluttered with plethora of temporary files. -.TP -\- -clutter can be even reduced using \fB\-\-build\-dir\fR=\fIdir\fR: all the *.t2d -directories are stored there. -.TP -\- -clutter can be reduced to zero using, e.g., \fB\-\-build\-dir=\fR/tmp/$USER.t2d -or \fB\-\-build\-dir=\fR$HOME/.t2d. -.TP -\- -the output file is updated after every succesful TeX run, for -sake of concurrent visualization of the output. In a `local' build -the viewer stops during the whole TeX run. -.TP -\- -if the compilation fails, the previous state of the output file -is preserved. -.TP -\- -PDF and DVI compilation are kept in separate subdirectories -preventing any possibility of auxiliary file incompatibility. -.PP -On the other hand, because `tidy' compilation takes place in another -directory, occasionally TeX won't be able to find some files (e.g., when -using \egraphicspath): in that case use \fB\-I\fR to specify the additional -directories to consider. -.PP -The values of the BIBTEX, LATEX (or PDFLATEX), MAKEINDEX, MAKEINFO, -TEX (or PDFTEX), TEXINDEX, and THUMBPDF environment variables are used -to run those commands, if they are set. Any CMD strings are added -after @setfilename for Texinfo input, in the first line for LaTeX input. -.SH "REPORTING BUGS" -Email bug reports to <bug\-texinfo@gnu.org>, -general questions and discussion to <help\-texinfo@gnu.org>. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texi2dvi -is maintained as a Texinfo manual. If the -.B info -and -.B texi2dvi -programs are properly installed at your site, the command -.IP -.B info texi2dvi -.PP -should give you access to the complete manual. - diff --git a/Build/source/utils/texinfo/doc/texindex.1 b/Build/source/utils/texinfo/doc/texindex.1 deleted file mode 100644 index 12dfbe33dae..00000000000 --- a/Build/source/utils/texinfo/doc/texindex.1 +++ /dev/null @@ -1,42 +0,0 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. -.TH TEXINDEX "1" "April 2008" "texindex 4.12" "User Commands" -.SH NAME -texindex \- sort Texinfo index files -.SH SYNOPSIS -.B texindex -[\fIOPTION\fR]... \fIFILE\fR... -.SH DESCRIPTION -Generate a sorted index for each TeX output FILE. -Usually FILE... is specified as `foo.??' for a document `foo.texi'. -.SH OPTIONS -.TP -\fB\-h\fR, \fB\-\-help\fR -display this help and exit -.TP -\fB\-o\fR, \fB\-\-output\fR FILE -send output to FILE -.TP -\fB\-\-version\fR -display version information and exit -.SH "REPORTING BUGS" -Email bug reports to bug\-texinfo@gnu.org, -general questions and discussion to help\-texinfo@gnu.org. -Texinfo home page: http://www.gnu.org/software/texinfo/ -.SH COPYRIGHT -Copyright \(co 2008 Free Software Foundation, Inc. -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.SH "SEE ALSO" -The full documentation for -.B texindex -is maintained as a Texinfo manual. If the -.B info -and -.B texindex -programs are properly installed at your site, the command -.IP -.B info texindex -.PP -will give you access to the complete manual. diff --git a/Build/source/utils/texinfo/doc/texinfo.5 b/Build/source/utils/texinfo/doc/texinfo.5 deleted file mode 100644 index 3bdb08afed7..00000000000 --- a/Build/source/utils/texinfo/doc/texinfo.5 +++ /dev/null @@ -1,61 +0,0 @@ -.\" texinfo(5) -.\" $Id: texinfo.5,v 1.3 2005/01/20 22:38:32 karl Exp $ -.\" -.\" Copyright (C) 1998, 1999, 2002 Free Software Foundation, Inc. -.\" -.\" Permission is granted to make and distribute verbatim copies of this -.\" manual provided the copyright notice and this permission notice are -.\" preserved on all copies. -.\" -.\" Permission is granted to copy and distribute modified versions of -.\" this manual under the conditions for verbatim copying, provided that -.\" the entire resulting derived work is distributed under the terms of a -.\" permission notice identical to this one. -.\" -.\" Permission is granted to copy and distribute translations of this -.\" manual into another language, under the above conditions for modified -.\" versions, except that this permission notice may be stated in a -.\" translation approved by the Foundation. -.\" -.de EX -.nf -.ft CW -.in +5 -.. -.de EE -.in -5 -.ft R -.fi -.. -.TH TEXINFO 5 "GNU Texinfo" "FSF" -.SH NAME -texinfo \- software documentation system -.SH DESCRIPTION -Texinfo is a documentation system that uses a single source file to -produce both online information and printed output. It is primarily -designed for writing software manuals. -.PP -For a full description of the Texinfo language and associated tools, -please see the Texinfo manual (written in Texinfo itself). Most likely, -running this command from your shell: -.EX -info texinfo -.EE -or this key sequence from inside Emacs: -.EX -M-x info RET m texinfo RET -.EE -will get you there. -.SH AVAILABILITY -ftp://ftp.gnu.org/gnu/texinfo/ -.br -or any GNU mirror site. -.SH "REPORTING BUGS" -Please send bug reports to bug-texinfo@gnu.org, -general questions and discussion to help-texinfo@gnu.org. -.SH "SEE ALSO" -info(1), install-info(1), makeinfo(1), texi2dvi(1), texindex(1). -.br -emacs(1), tex(1). -.br -info(5). diff --git a/Build/source/utils/texinfo/doc/texinfo.tex b/Build/source/utils/texinfo/doc/texinfo.tex deleted file mode 100644 index bac0726023e..00000000000 --- a/Build/source/utils/texinfo/doc/texinfo.tex +++ /dev/null @@ -1,8997 +0,0 @@ -% texinfo.tex -- TeX macros to handle Texinfo files. -% -% Load plain if necessary, i.e., if running under initex. -\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi -% -\def\texinfoversion{2008-04-18.10} -% -% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, -% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008 Free Software Foundation, Inc. -% -% This texinfo.tex file is free software: you can redistribute it and/or -% modify it under the terms of the GNU General Public License as -% published by the Free Software Foundation, either version 3 of the -% License, or (at your option) any later version. -% -% This texinfo.tex file is distributed in the hope that it will be -% useful, but WITHOUT ANY WARRANTY; without even the implied warranty -% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -% General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% As a special exception, when this file is read by TeX when processing -% a Texinfo source document, you may use the result without -% restriction. (This has been our intent since Texinfo was invented.) -% -% Please try the latest version of texinfo.tex before submitting bug -% reports; you can get the latest version from: -% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or -% ftp://tug.org/tex/texinfo.tex -% (and all CTAN mirrors, see http://www.ctan.org). -% The texinfo.tex in any given distribution could well be out -% of date, so if that's what you're using, please check. -% -% Send bug reports to bug-texinfo@gnu.org. Please include including a -% complete document in each bug report with which we can reproduce the -% problem. Patches are, of course, greatly appreciated. -% -% To process a Texinfo manual with TeX, it's most reliable to use the -% texi2dvi shell script that comes with the distribution. For a simple -% manual foo.texi, however, you can get away with this: -% tex foo.texi -% texindex foo.?? -% tex foo.texi -% tex foo.texi -% dvips foo.dvi -o # or whatever; this makes foo.ps. -% The extra TeX runs get the cross-reference information correct. -% Sometimes one run after texindex suffices, and sometimes you need more -% than two; texi2dvi does it as many times as necessary. -% -% It is possible to adapt texinfo.tex for other languages, to some -% extent. You can get the existing language-specific files from the -% full Texinfo distribution. -% -% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. - - -\message{Loading texinfo [version \texinfoversion]:} - -% If in a .fmt file, print the version number -% and turn on active characters that we couldn't do earlier because -% they might have appeared in the input file name. -\everyjob{\message{[Texinfo version \texinfoversion]}% - \catcode`+=\active \catcode`\_=\active} - - -\chardef\other=12 - -% We never want plain's \outer definition of \+ in Texinfo. -% For @tex, we can use \tabalign. -\let\+ = \relax - -% Save some plain tex macros whose names we will redefine. -\let\ptexb=\b -\let\ptexbullet=\bullet -\let\ptexc=\c -\let\ptexcomma=\, -\let\ptexdot=\. -\let\ptexdots=\dots -\let\ptexend=\end -\let\ptexequiv=\equiv -\let\ptexexclam=\! -\let\ptexfootnote=\footnote -\let\ptexgtr=> -\let\ptexhat=^ -\let\ptexi=\i -\let\ptexindent=\indent -\let\ptexinsert=\insert -\let\ptexlbrace=\{ -\let\ptexless=< -\let\ptexnewwrite\newwrite -\let\ptexnoindent=\noindent -\let\ptexplus=+ -\let\ptexrbrace=\} -\let\ptexslash=\/ -\let\ptexstar=\* -\let\ptext=\t -\let\ptextop=\top - -% If this character appears in an error message or help string, it -% starts a new line in the output. -\newlinechar = `^^J - -% Use TeX 3.0's \inputlineno to get the line number, for better error -% messages, but if we're using an old version of TeX, don't do anything. -% -\ifx\inputlineno\thisisundefined - \let\linenumber = \empty % Pre-3.0. -\else - \def\linenumber{l.\the\inputlineno:\space} -\fi - -% Set up fixed words for English if not already set. -\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi -\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi -\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi -\ifx\putwordin\undefined \gdef\putwordin{in}\fi -\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi -\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi -\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi -\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi -\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi -\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi -\ifx\putwordof\undefined \gdef\putwordof{of}\fi -\ifx\putwordon\undefined \gdef\putwordon{on}\fi -\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi -\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi -\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi -\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi -\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi -\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi -\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi -% -\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi -\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi -\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi -\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi -\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi -\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi -\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi -\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi -\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi -\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi -\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi -\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi -% -\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi -\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi -\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi -\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi -\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi - -% Since the category of space is not known, we have to be careful. -\chardef\spacecat = 10 -\def\spaceisspace{\catcode`\ =\spacecat} - -% sometimes characters are active, so we need control sequences. -\chardef\colonChar = `\: -\chardef\commaChar = `\, -\chardef\dashChar = `\- -\chardef\dotChar = `\. -\chardef\exclamChar= `\! -\chardef\lquoteChar= `\` -\chardef\questChar = `\? -\chardef\rquoteChar= `\' -\chardef\semiChar = `\; -\chardef\underChar = `\_ - -% Ignore a token. -% -\def\gobble#1{} - -% The following is used inside several \edef's. -\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} - -% Hyphenation fixes. -\hyphenation{ - Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script - ap-pen-dix bit-map bit-maps - data-base data-bases eshell fall-ing half-way long-est man-u-script - man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm - par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces - spell-ing spell-ings - stand-alone strong-est time-stamp time-stamps which-ever white-space - wide-spread wrap-around -} - -% Margin to add to right of even pages, to left of odd pages. -\newdimen\bindingoffset -\newdimen\normaloffset -\newdimen\pagewidth \newdimen\pageheight - -% For a final copy, take out the rectangles -% that mark overfull boxes (in case you have decided -% that the text looks ok even though it passes the margin). -% -\def\finalout{\overfullrule=0pt} - -% @| inserts a changebar to the left of the current line. It should -% surround any changed text. This approach does *not* work if the -% change spans more than two lines of output. To handle that, we would -% have adopt a much more difficult approach (putting marks into the main -% vertical list for the beginning and end of each change). -% -\def\|{% - % \vadjust can only be used in horizontal mode. - \leavevmode - % - % Append this vertical mode material after the current line in the output. - \vadjust{% - % We want to insert a rule with the height and depth of the current - % leading; that is exactly what \strutbox is supposed to record. - \vskip-\baselineskip - % - % \vadjust-items are inserted at the left edge of the type. So - % the \llap here moves out into the left-hand margin. - \llap{% - % - % For a thicker or thinner bar, change the `1pt'. - \vrule height\baselineskip width1pt - % - % This is the space between the bar and the text. - \hskip 12pt - }% - }% -} - -% Sometimes it is convenient to have everything in the transcript file -% and nothing on the terminal. We don't just call \tracingall here, -% since that produces some useless output on the terminal. We also make -% some effort to order the tracing commands to reduce output in the log -% file; cf. trace.sty in LaTeX. -% -\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% -\def\loggingall{% - \tracingstats2 - \tracingpages1 - \tracinglostchars2 % 2 gives us more in etex - \tracingparagraphs1 - \tracingoutput1 - \tracingmacros2 - \tracingrestores1 - \showboxbreadth\maxdimen \showboxdepth\maxdimen - \ifx\eTeXversion\undefined\else % etex gives us more logging - \tracingscantokens1 - \tracingifs1 - \tracinggroups1 - \tracingnesting2 - \tracingassigns1 - \fi - \tracingcommands3 % 3 gives us more in etex - \errorcontextlines16 -}% - -% add check for \lastpenalty to plain's definitions. If the last thing -% we did was a \nobreak, we don't want to insert more space. -% -\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount - \removelastskip\penalty-50\smallskip\fi\fi} -\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount - \removelastskip\penalty-100\medskip\fi\fi} -\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount - \removelastskip\penalty-200\bigskip\fi\fi} - -% For @cropmarks command. -% Do @cropmarks to get crop marks. -% -\newif\ifcropmarks -\let\cropmarks = \cropmarkstrue -% -% Dimensions to add cropmarks at corners. -% Added by P. A. MacKay, 12 Nov. 1986 -% -\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines -\newdimen\cornerlong \cornerlong=1pc -\newdimen\cornerthick \cornerthick=.3pt -\newdimen\topandbottommargin \topandbottommargin=.75in - -% Output a mark which sets \thischapter, \thissection and \thiscolor. -% We dump everything together because we only have one kind of mark. -% This works because we only use \botmark / \topmark, not \firstmark. -% -% A mark contains a subexpression of the \ifcase ... \fi construct. -% \get*marks macros below extract the needed part using \ifcase. -% -% Another complication is to let the user choose whether \thischapter -% (\thissection) refers to the chapter (section) in effect at the top -% of a page, or that at the bottom of a page. The solution is -% described on page 260 of The TeXbook. It involves outputting two -% marks for the sectioning macros, one before the section break, and -% one after. I won't pretend I can describe this better than DEK... -\def\domark{% - \toks0=\expandafter{\lastchapterdefs}% - \toks2=\expandafter{\lastsectiondefs}% - \toks4=\expandafter{\prevchapterdefs}% - \toks6=\expandafter{\prevsectiondefs}% - \toks8=\expandafter{\lastcolordefs}% - \mark{% - \the\toks0 \the\toks2 - \noexpand\or \the\toks4 \the\toks6 - \noexpand\else \the\toks8 - }% -} -% \topmark doesn't work for the very first chapter (after the title -% page or the contents), so we use \firstmark there -- this gets us -% the mark with the chapter defs, unless the user sneaks in, e.g., -% @setcolor (or @url, or @link, etc.) between @contents and the very -% first @chapter. -\def\gettopheadingmarks{% - \ifcase0\topmark\fi - \ifx\thischapter\empty \ifcase0\firstmark\fi \fi -} -\def\getbottomheadingmarks{\ifcase1\botmark\fi} -\def\getcolormarks{\ifcase2\topmark\fi} - -% Avoid "undefined control sequence" errors. -\def\lastchapterdefs{} -\def\lastsectiondefs{} -\def\prevchapterdefs{} -\def\prevsectiondefs{} -\def\lastcolordefs{} - -% Main output routine. -\chardef\PAGE = 255 -\output = {\onepageout{\pagecontents\PAGE}} - -\newbox\headlinebox -\newbox\footlinebox - -% \onepageout takes a vbox as an argument. Note that \pagecontents -% does insertions, but you have to call it yourself. -\def\onepageout#1{% - \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi - % - \ifodd\pageno \advance\hoffset by \bindingoffset - \else \advance\hoffset by -\bindingoffset\fi - % - % Do this outside of the \shipout so @code etc. will be expanded in - % the headline as they should be, not taken literally (outputting ''code). - \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi - \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% - \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi - \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% - % - {% - % Have to do this stuff outside the \shipout because we want it to - % take effect in \write's, yet the group defined by the \vbox ends - % before the \shipout runs. - % - \indexdummies % don't expand commands in the output. - \normalturnoffactive % \ in index entries must not stay \, e.g., if - % the page break happens to be in the middle of an example. - % We don't want .vr (or whatever) entries like this: - % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} - % "\acronym" won't work when it's read back in; - % it needs to be - % {\code {{\tt \backslashcurfont }acronym} - \shipout\vbox{% - % Do this early so pdf references go to the beginning of the page. - \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi - % - \ifcropmarks \vbox to \outervsize\bgroup - \hsize = \outerhsize - \vskip-\topandbottommargin - \vtop to0pt{% - \line{\ewtop\hfil\ewtop}% - \nointerlineskip - \line{% - \vbox{\moveleft\cornerthick\nstop}% - \hfill - \vbox{\moveright\cornerthick\nstop}% - }% - \vss}% - \vskip\topandbottommargin - \line\bgroup - \hfil % center the page within the outer (page) hsize. - \ifodd\pageno\hskip\bindingoffset\fi - \vbox\bgroup - \fi - % - \unvbox\headlinebox - \pagebody{#1}% - \ifdim\ht\footlinebox > 0pt - % Only leave this space if the footline is nonempty. - % (We lessened \vsize for it in \oddfootingyyy.) - % The \baselineskip=24pt in plain's \makefootline has no effect. - \vskip 24pt - \unvbox\footlinebox - \fi - % - \ifcropmarks - \egroup % end of \vbox\bgroup - \hfil\egroup % end of (centering) \line\bgroup - \vskip\topandbottommargin plus1fill minus1fill - \boxmaxdepth = \cornerthick - \vbox to0pt{\vss - \line{% - \vbox{\moveleft\cornerthick\nsbot}% - \hfill - \vbox{\moveright\cornerthick\nsbot}% - }% - \nointerlineskip - \line{\ewbot\hfil\ewbot}% - }% - \egroup % \vbox from first cropmarks clause - \fi - }% end of \shipout\vbox - }% end of group with \indexdummies - \advancepageno - \ifnum\outputpenalty>-20000 \else\dosupereject\fi -} - -\newinsert\margin \dimen\margin=\maxdimen - -\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} -{\catcode`\@ =11 -\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi -% marginal hacks, juha@viisa.uucp (Juha Takala) -\ifvoid\margin\else % marginal info is present - \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi -\dimen@=\dp#1\relax \unvbox#1\relax -\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi -\ifr@ggedbottom \kern-\dimen@ \vfil \fi} -} - -% Here are the rules for the cropmarks. Note that they are -% offset so that the space between them is truly \outerhsize or \outervsize -% (P. A. MacKay, 12 November, 1986) -% -\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} -\def\nstop{\vbox - {\hrule height\cornerthick depth\cornerlong width\cornerthick}} -\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} -\def\nsbot{\vbox - {\hrule height\cornerlong depth\cornerthick width\cornerthick}} - -% Parse an argument, then pass it to #1. The argument is the rest of -% the input line (except we remove a trailing comment). #1 should be a -% macro which expects an ordinary undelimited TeX argument. -% -\def\parsearg{\parseargusing{}} -\def\parseargusing#1#2{% - \def\argtorun{#2}% - \begingroup - \obeylines - \spaceisspace - #1% - \parseargline\empty% Insert the \empty token, see \finishparsearg below. -} - -{\obeylines % - \gdef\parseargline#1^^M{% - \endgroup % End of the group started in \parsearg. - \argremovecomment #1\comment\ArgTerm% - }% -} - -% First remove any @comment, then any @c comment. -\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} -\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} - -% Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space. -% -% \argremovec might leave us with trailing space, e.g., -% @end itemize @c foo -% This space token undergoes the same procedure and is eventually removed -% by \finishparsearg. -% -\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} -\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} -\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% - \def\temp{#3}% - \ifx\temp\empty - % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: - \let\temp\finishparsearg - \else - \let\temp\argcheckspaces - \fi - % Put the space token in: - \temp#1 #3\ArgTerm -} - -% If a _delimited_ argument is enclosed in braces, they get stripped; so -% to get _exactly_ the rest of the line, we had to prevent such situation. -% We prepended an \empty token at the very beginning and we expand it now, -% just before passing the control to \argtorun. -% (Similarly, we have to think about #3 of \argcheckspacesY above: it is -% either the null string, or it ends with \^^M---thus there is no danger -% that a pair of braces would be stripped. -% -% But first, we have to remove the trailing space token. -% -\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} - -% \parseargdef\foo{...} -% is roughly equivalent to -% \def\foo{\parsearg\Xfoo} -% \def\Xfoo#1{...} -% -% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my -% favourite TeX trick. --kasal, 16nov03 - -\def\parseargdef#1{% - \expandafter \doparseargdef \csname\string#1\endcsname #1% -} -\def\doparseargdef#1#2{% - \def#2{\parsearg#1}% - \def#1##1% -} - -% Several utility definitions with active space: -{ - \obeyspaces - \gdef\obeyedspace{ } - - % Make each space character in the input produce a normal interword - % space in the output. Don't allow a line break at this space, as this - % is used only in environments like @example, where each line of input - % should produce a line of output anyway. - % - \gdef\sepspaces{\obeyspaces\let =\tie} - - % If an index command is used in an @example environment, any spaces - % therein should become regular spaces in the raw index file, not the - % expansion of \tie (\leavevmode \penalty \@M \ ). - \gdef\unsepspaces{\let =\space} -} - - -\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} - -% Define the framework for environments in texinfo.tex. It's used like this: -% -% \envdef\foo{...} -% \def\Efoo{...} -% -% It's the responsibility of \envdef to insert \begingroup before the -% actual body; @end closes the group after calling \Efoo. \envdef also -% defines \thisenv, so the current environment is known; @end checks -% whether the environment name matches. The \checkenv macro can also be -% used to check whether the current environment is the one expected. -% -% Non-false conditionals (@iftex, @ifset) don't fit into this, so they -% are not treated as environments; they don't open a group. (The -% implementation of @end takes care not to call \endgroup in this -% special case.) - - -% At run-time, environments start with this: -\def\startenvironment#1{\begingroup\def\thisenv{#1}} -% initialize -\let\thisenv\empty - -% ... but they get defined via ``\envdef\foo{...}'': -\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} -\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} - -% Check whether we're in the right environment: -\def\checkenv#1{% - \def\temp{#1}% - \ifx\thisenv\temp - \else - \badenverr - \fi -} - -% Environment mismatch, #1 expected: -\def\badenverr{% - \errhelp = \EMsimple - \errmessage{This command can appear only \inenvironment\temp, - not \inenvironment\thisenv}% -} -\def\inenvironment#1{% - \ifx#1\empty - out of any environment% - \else - in environment \expandafter\string#1% - \fi -} - -% @end foo executes the definition of \Efoo. -% But first, it executes a specialized version of \checkenv -% -\parseargdef\end{% - \if 1\csname iscond.#1\endcsname - \else - % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 - \expandafter\checkenv\csname#1\endcsname - \csname E#1\endcsname - \endgroup - \fi -} - -\newhelp\EMsimple{Press RETURN to continue.} - - -%% Simple single-character @ commands - -% @@ prints an @ -% Kludge this until the fonts are right (grr). -\def\@{{\tt\char64}} - -% This is turned off because it was never documented -% and you can use @w{...} around a quote to suppress ligatures. -%% Define @` and @' to be the same as ` and ' -%% but suppressing ligatures. -%\def\`{{`}} -%\def\'{{'}} - -% Used to generate quoted braces. -\def\mylbrace {{\tt\char123}} -\def\myrbrace {{\tt\char125}} -\let\{=\mylbrace -\let\}=\myrbrace -\begingroup - % Definitions to produce \{ and \} commands for indices, - % and @{ and @} for the aux/toc files. - \catcode`\{ = \other \catcode`\} = \other - \catcode`\[ = 1 \catcode`\] = 2 - \catcode`\! = 0 \catcode`\\ = \other - !gdef!lbracecmd[\{]% - !gdef!rbracecmd[\}]% - !gdef!lbraceatcmd[@{]% - !gdef!rbraceatcmd[@}]% -!endgroup - -% @comma{} to avoid , parsing problems. -\let\comma = , - -% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent -% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. -\let\, = \c -\let\dotaccent = \. -\def\ringaccent#1{{\accent23 #1}} -\let\tieaccent = \t -\let\ubaraccent = \b -\let\udotaccent = \d - -% Other special characters: @questiondown @exclamdown @ordf @ordm -% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. -\def\questiondown{?`} -\def\exclamdown{!`} -\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} -\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} - -% Dotless i and dotless j, used for accents. -\def\imacro{i} -\def\jmacro{j} -\def\dotless#1{% - \def\temp{#1}% - \ifx\temp\imacro \ifmmode\imath \else\ptexi \fi - \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi - \else \errmessage{@dotless can be used only with i or j}% - \fi\fi -} - -% The \TeX{} logo, as in plain, but resetting the spacing so that a -% period following counts as ending a sentence. (Idea found in latex.) -% -\edef\TeX{\TeX \spacefactor=1000 } - -% @LaTeX{} logo. Not quite the same results as the definition in -% latex.ltx, since we use a different font for the raised A; it's most -% convenient for us to use an explicitly smaller font, rather than using -% the \scriptstyle font (since we don't reset \scriptstyle and -% \scriptscriptstyle). -% -\def\LaTeX{% - L\kern-.36em - {\setbox0=\hbox{T}% - \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}% - \kern-.15em - \TeX -} - -% Be sure we're in horizontal mode when doing a tie, since we make space -% equivalent to this in @example-like environments. Otherwise, a space -% at the beginning of a line will start with \penalty -- and -% since \penalty is valid in vertical mode, we'd end up putting the -% penalty on the vertical list instead of in the new paragraph. -{\catcode`@ = 11 - % Avoid using \@M directly, because that causes trouble - % if the definition is written into an index file. - \global\let\tiepenalty = \@M - \gdef\tie{\leavevmode\penalty\tiepenalty\ } -} - -% @: forces normal size whitespace following. -\def\:{\spacefactor=1000 } - -% @* forces a line break. -\def\*{\hfil\break\hbox{}\ignorespaces} - -% @/ allows a line break. -\let\/=\allowbreak - -% @. is an end-of-sentence period. -\def\.{.\spacefactor=\endofsentencespacefactor\space} - -% @! is an end-of-sentence bang. -\def\!{!\spacefactor=\endofsentencespacefactor\space} - -% @? is an end-of-sentence query. -\def\?{?\spacefactor=\endofsentencespacefactor\space} - -% @frenchspacing on|off says whether to put extra space after punctuation. -% -\def\onword{on} -\def\offword{off} -% -\parseargdef\frenchspacing{% - \def\temp{#1}% - \ifx\temp\onword \plainfrenchspacing - \else\ifx\temp\offword \plainnonfrenchspacing - \else - \errhelp = \EMsimple - \errmessage{Unknown @frenchspacing option `\temp', must be on/off}% - \fi\fi -} - -% @w prevents a word break. Without the \leavevmode, @w at the -% beginning of a paragraph, when TeX is still in vertical mode, would -% produce a whole line of output instead of starting the paragraph. -\def\w#1{\leavevmode\hbox{#1}} - -% @group ... @end group forces ... to be all on one page, by enclosing -% it in a TeX vbox. We use \vtop instead of \vbox to construct the box -% to keep its height that of a normal line. According to the rules for -% \topskip (p.114 of the TeXbook), the glue inserted is -% max (\topskip - \ht (first item), 0). If that height is large, -% therefore, no glue is inserted, and the space between the headline and -% the text is small, which looks bad. -% -% Another complication is that the group might be very large. This can -% cause the glue on the previous page to be unduly stretched, because it -% does not have much material. In this case, it's better to add an -% explicit \vfill so that the extra space is at the bottom. The -% threshold for doing this is if the group is more than \vfilllimit -% percent of a page (\vfilllimit can be changed inside of @tex). -% -\newbox\groupbox -\def\vfilllimit{0.7} -% -\envdef\group{% - \ifnum\catcode`\^^M=\active \else - \errhelp = \groupinvalidhelp - \errmessage{@group invalid in context where filling is enabled}% - \fi - \startsavinginserts - % - \setbox\groupbox = \vtop\bgroup - % Do @comment since we are called inside an environment such as - % @example, where each end-of-line in the input causes an - % end-of-line in the output. We don't want the end-of-line after - % the `@group' to put extra space in the output. Since @group - % should appear on a line by itself (according to the Texinfo - % manual), we don't worry about eating any user text. - \comment -} -% -% The \vtop produces a box with normal height and large depth; thus, TeX puts -% \baselineskip glue before it, and (when the next line of text is done) -% \lineskip glue after it. Thus, space below is not quite equal to space -% above. But it's pretty close. -\def\Egroup{% - % To get correct interline space between the last line of the group - % and the first line afterwards, we have to propagate \prevdepth. - \endgraf % Not \par, as it may have been set to \lisppar. - \global\dimen1 = \prevdepth - \egroup % End the \vtop. - % \dimen0 is the vertical size of the group's box. - \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox - % \dimen2 is how much space is left on the page (more or less). - \dimen2 = \pageheight \advance\dimen2 by -\pagetotal - % if the group doesn't fit on the current page, and it's a big big - % group, force a page break. - \ifdim \dimen0 > \dimen2 - \ifdim \pagetotal < \vfilllimit\pageheight - \page - \fi - \fi - \box\groupbox - \prevdepth = \dimen1 - \checkinserts -} -% -% TeX puts in an \escapechar (i.e., `@') at the beginning of the help -% message, so this ends up printing `@group can only ...'. -% -\newhelp\groupinvalidhelp{% -group can only be used in environments such as @example,^^J% -where each line of input produces a line of output.} - -% @need space-in-mils -% forces a page break if there is not space-in-mils remaining. - -\newdimen\mil \mil=0.001in - -% Old definition--didn't work. -%\parseargdef\need{\par % -%% This method tries to make TeX break the page naturally -%% if the depth of the box does not fit. -%{\baselineskip=0pt% -%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak -%\prevdepth=-1000pt -%}} - -\parseargdef\need{% - % Ensure vertical mode, so we don't make a big box in the middle of a - % paragraph. - \par - % - % If the @need value is less than one line space, it's useless. - \dimen0 = #1\mil - \dimen2 = \ht\strutbox - \advance\dimen2 by \dp\strutbox - \ifdim\dimen0 > \dimen2 - % - % Do a \strut just to make the height of this box be normal, so the - % normal leading is inserted relative to the preceding line. - % And a page break here is fine. - \vtop to #1\mil{\strut\vfil}% - % - % TeX does not even consider page breaks if a penalty added to the - % main vertical list is 10000 or more. But in order to see if the - % empty box we just added fits on the page, we must make it consider - % page breaks. On the other hand, we don't want to actually break the - % page after the empty box. So we use a penalty of 9999. - % - % There is an extremely small chance that TeX will actually break the - % page at this \penalty, if there are no other feasible breakpoints in - % sight. (If the user is using lots of big @group commands, which - % almost-but-not-quite fill up a page, TeX will have a hard time doing - % good page breaking, for example.) However, I could not construct an - % example where a page broke at this \penalty; if it happens in a real - % document, then we can reconsider our strategy. - \penalty9999 - % - % Back up by the size of the box, whether we did a page break or not. - \kern -#1\mil - % - % Do not allow a page break right after this kern. - \nobreak - \fi -} - -% @br forces paragraph break (and is undocumented). - -\let\br = \par - -% @page forces the start of a new page. -% -\def\page{\par\vfill\supereject} - -% @exdent text.... -% outputs text on separate line in roman font, starting at standard page margin - -% This records the amount of indent in the innermost environment. -% That's how much \exdent should take out. -\newskip\exdentamount - -% This defn is used inside fill environments such as @defun. -\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} - -% This defn is used inside nofill environments such as @example. -\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount - \leftline{\hskip\leftskip{\rm#1}}}} - -% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current -% paragraph. For more general purposes, use the \margin insertion -% class. WHICH is `l' or `r'. -% -\newskip\inmarginspacing \inmarginspacing=1cm -\def\strutdepth{\dp\strutbox} -% -\def\doinmargin#1#2{\strut\vadjust{% - \nobreak - \kern-\strutdepth - \vtop to \strutdepth{% - \baselineskip=\strutdepth - \vss - % if you have multiple lines of stuff to put here, you'll need to - % make the vbox yourself of the appropriate size. - \ifx#1l% - \llap{\ignorespaces #2\hskip\inmarginspacing}% - \else - \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% - \fi - \null - }% -}} -\def\inleftmargin{\doinmargin l} -\def\inrightmargin{\doinmargin r} -% -% @inmargin{TEXT [, RIGHT-TEXT]} -% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; -% else use TEXT for both). -% -\def\inmargin#1{\parseinmargin #1,,\finish} -\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \def\lefttext{#1}% have both texts - \def\righttext{#2}% - \else - \def\lefttext{#1}% have only one text - \def\righttext{#1}% - \fi - % - \ifodd\pageno - \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin - \else - \def\temp{\inleftmargin\lefttext}% - \fi - \temp -} - -% @include FILE -- \input text of FILE. -% -\def\include{\parseargusing\filenamecatcodes\includezzz} -\def\includezzz#1{% - \pushthisfilestack - \def\thisfile{#1}% - {% - \makevalueexpandable % we want to expand any @value in FILE. - \turnoffactive % and allow special characters in the expansion - \edef\temp{\noexpand\input #1 }% - % - % This trickery is to read FILE outside of a group, in case it makes - % definitions, etc. - \expandafter - }\temp - \popthisfilestack -} -\def\filenamecatcodes{% - \catcode`\\=\other - \catcode`~=\other - \catcode`^=\other - \catcode`_=\other - \catcode`|=\other - \catcode`<=\other - \catcode`>=\other - \catcode`+=\other - \catcode`-=\other -} - -\def\pushthisfilestack{% - \expandafter\pushthisfilestackX\popthisfilestack\StackTerm -} -\def\pushthisfilestackX{% - \expandafter\pushthisfilestackY\thisfile\StackTerm -} -\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% - \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% -} - -\def\popthisfilestack{\errthisfilestackempty} -\def\errthisfilestackempty{\errmessage{Internal error: - the stack of filenames is empty.}} - -\def\thisfile{} - -% @center line -% outputs that line, centered. -% -\parseargdef\center{% - \ifhmode - \let\next\centerH - \else - \let\next\centerV - \fi - \next{\hfil \ignorespaces#1\unskip \hfil}% -} -\def\centerH#1{% - {% - \hfil\break - \advance\hsize by -\leftskip - \advance\hsize by -\rightskip - \line{#1}% - \break - }% -} -\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} - -% @sp n outputs n lines of vertical space - -\parseargdef\sp{\vskip #1\baselineskip} - -% @comment ...line which is ignored... -% @c is the same as @comment -% @ignore ... @end ignore is another way to write a comment - -\def\comment{\begingroup \catcode`\^^M=\other% -\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% -\commentxxx} -{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} - -\let\c=\comment - -% @paragraphindent NCHARS -% We'll use ems for NCHARS, close enough. -% NCHARS can also be the word `asis' or `none'. -% We cannot feasibly implement @paragraphindent asis, though. -% -\def\asisword{asis} % no translation, these are keywords -\def\noneword{none} -% -\parseargdef\paragraphindent{% - \def\temp{#1}% - \ifx\temp\asisword - \else - \ifx\temp\noneword - \defaultparindent = 0pt - \else - \defaultparindent = #1em - \fi - \fi - \parindent = \defaultparindent -} - -% @exampleindent NCHARS -% We'll use ems for NCHARS like @paragraphindent. -% It seems @exampleindent asis isn't necessary, but -% I preserve it to make it similar to @paragraphindent. -\parseargdef\exampleindent{% - \def\temp{#1}% - \ifx\temp\asisword - \else - \ifx\temp\noneword - \lispnarrowing = 0pt - \else - \lispnarrowing = #1em - \fi - \fi -} - -% @firstparagraphindent WORD -% If WORD is `none', then suppress indentation of the first paragraph -% after a section heading. If WORD is `insert', then do indent at such -% paragraphs. -% -% The paragraph indentation is suppressed or not by calling -% \suppressfirstparagraphindent, which the sectioning commands do. -% We switch the definition of this back and forth according to WORD. -% By default, we suppress indentation. -% -\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} -\def\insertword{insert} -% -\parseargdef\firstparagraphindent{% - \def\temp{#1}% - \ifx\temp\noneword - \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent - \else\ifx\temp\insertword - \let\suppressfirstparagraphindent = \relax - \else - \errhelp = \EMsimple - \errmessage{Unknown @firstparagraphindent option `\temp'}% - \fi\fi -} - -% Here is how we actually suppress indentation. Redefine \everypar to -% \kern backwards by \parindent, and then reset itself to empty. -% -% We also make \indent itself not actually do anything until the next -% paragraph. -% -\gdef\dosuppressfirstparagraphindent{% - \gdef\indent{% - \restorefirstparagraphindent - \indent - }% - \gdef\noindent{% - \restorefirstparagraphindent - \noindent - }% - \global\everypar = {% - \kern -\parindent - \restorefirstparagraphindent - }% -} - -\gdef\restorefirstparagraphindent{% - \global \let \indent = \ptexindent - \global \let \noindent = \ptexnoindent - \global \everypar = {}% -} - - -% @asis just yields its argument. Used with @table, for example. -% -\def\asis#1{#1} - -% @math outputs its argument in math mode. -% -% One complication: _ usually means subscripts, but it could also mean -% an actual _ character, as in @math{@var{some_variable} + 1}. So make -% _ active, and distinguish by seeing if the current family is \slfam, -% which is what @var uses. -{ - \catcode`\_ = \active - \gdef\mathunderscore{% - \catcode`\_=\active - \def_{\ifnum\fam=\slfam \_\else\sb\fi}% - } -} -% Another complication: we want \\ (and @\) to output a \ character. -% FYI, plain.tex uses \\ as a temporary control sequence (why?), but -% this is not advertised and we don't care. Texinfo does not -% otherwise define @\. -% -% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. -\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} -% -\def\math{% - \tex - \mathunderscore - \let\\ = \mathbackslash - \mathactive - % make the texinfo accent commands work in math mode - \let\"=\ddot - \let\'=\acute - \let\==\bar - \let\^=\hat - \let\`=\grave - \let\u=\breve - \let\v=\check - \let\~=\tilde - \let\dotaccent=\dot - $\finishmath -} -\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. - -% Some active characters (such as <) are spaced differently in math. -% We have to reset their definitions in case the @math was an argument -% to a command which sets the catcodes (such as @item or @section). -% -{ - \catcode`^ = \active - \catcode`< = \active - \catcode`> = \active - \catcode`+ = \active - \gdef\mathactive{% - \let^ = \ptexhat - \let< = \ptexless - \let> = \ptexgtr - \let+ = \ptexplus - } -} - -% Some math mode symbols. -\def\bullet{$\ptexbullet$} -\def\geq{\ifmmode \ge\else $\ge$\fi} -\def\leq{\ifmmode \le\else $\le$\fi} -\def\minus{\ifmmode -\else $-$\fi} - -% @dots{} outputs an ellipsis using the current font. -% We do .5em per period so that it has the same spacing in the cm -% typewriter fonts as three actual period characters; on the other hand, -% in other typewriter fonts three periods are wider than 1.5em. So do -% whichever is larger. -% -\def\dots{% - \leavevmode - \setbox0=\hbox{...}% get width of three periods - \ifdim\wd0 > 1.5em - \dimen0 = \wd0 - \else - \dimen0 = 1.5em - \fi - \hbox to \dimen0{% - \hskip 0pt plus.25fil - .\hskip 0pt plus1fil - .\hskip 0pt plus1fil - .\hskip 0pt plus.5fil - }% -} - -% @enddots{} is an end-of-sentence ellipsis. -% -\def\enddots{% - \dots - \spacefactor=\endofsentencespacefactor -} - -% @comma{} is so commas can be inserted into text without messing up -% Texinfo's parsing. -% -\let\comma = , - -% @refill is a no-op. -\let\refill=\relax - -% If working on a large document in chapters, it is convenient to -% be able to disable indexing, cross-referencing, and contents, for test runs. -% This is done with @novalidate (before @setfilename). -% -\newif\iflinks \linkstrue % by default we want the aux files. -\let\novalidate = \linksfalse - -% @setfilename is done at the beginning of every texinfo file. -% So open here the files we need to have open while reading the input. -% This makes it possible to make a .fmt file for texinfo. -\def\setfilename{% - \fixbackslash % Turn off hack to swallow `\input texinfo'. - \iflinks - \tryauxfile - % Open the new aux file. TeX will close it automatically at exit. - \immediate\openout\auxfile=\jobname.aux - \fi % \openindices needs to do some work in any case. - \openindices - \let\setfilename=\comment % Ignore extra @setfilename cmds. - % - % If texinfo.cnf is present on the system, read it. - % Useful for site-wide @afourpaper, etc. - \openin 1 texinfo.cnf - \ifeof 1 \else \input texinfo.cnf \fi - \closein 1 - % - \comment % Ignore the actual filename. -} - -% Called from \setfilename. -% -\def\openindices{% - \newindex{cp}% - \newcodeindex{fn}% - \newcodeindex{vr}% - \newcodeindex{tp}% - \newcodeindex{ky}% - \newcodeindex{pg}% -} - -% @bye. -\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} - - -\message{pdf,} -% adobe `portable' document format -\newcount\tempnum -\newcount\lnkcount -\newtoks\filename -\newcount\filenamelength -\newcount\pgn -\newtoks\toksA -\newtoks\toksB -\newtoks\toksC -\newtoks\toksD -\newbox\boxA -\newcount\countA -\newif\ifpdf -\newif\ifpdfmakepagedest - -% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1 -% can be set). So we test for \relax and 0 as well as \undefined, -% borrowed from ifpdf.sty. -\ifx\pdfoutput\undefined -\else - \ifx\pdfoutput\relax - \else - \ifcase\pdfoutput - \else - \pdftrue - \fi - \fi -\fi - -% PDF uses PostScript string constants for the names of xref targets, -% for display in the outlines, and in other places. Thus, we have to -% double any backslashes. Otherwise, a name like "\node" will be -% interpreted as a newline (\n), followed by o, d, e. Not good. -% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html -% (and related messages, the final outcome is that it is up to the TeX -% user to double the backslashes and otherwise make the string valid, so -% that's what we do). - -% double active backslashes. -% -{\catcode`\@=0 \catcode`\\=\active - @gdef@activebackslashdouble{% - @catcode`@\=@active - @let\=@doublebackslash} -} - -% To handle parens, we must adopt a different approach, since parens are -% not active characters. hyperref.dtx (which has the same problem as -% us) handles it with this amazing macro to replace tokens, with minor -% changes for Texinfo. It is included here under the GPL by permission -% from the author, Heiko Oberdiek. -% -% #1 is the tokens to replace. -% #2 is the replacement. -% #3 is the control sequence with the string. -% -\def\HyPsdSubst#1#2#3{% - \def\HyPsdReplace##1#1##2\END{% - ##1% - \ifx\\##2\\% - \else - #2% - \HyReturnAfterFi{% - \HyPsdReplace##2\END - }% - \fi - }% - \xdef#3{\expandafter\HyPsdReplace#3#1\END}% -} -\long\def\HyReturnAfterFi#1\fi{\fi#1} - -% #1 is a control sequence in which to do the replacements. -\def\backslashparens#1{% - \xdef#1{#1}% redefine it as its expansion; the definition is simply - % \lastnode when called from \setref -> \pdfmkdest. - \HyPsdSubst{(}{\realbackslash(}{#1}% - \HyPsdSubst{)}{\realbackslash)}{#1}% -} - -\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images -with PDF output, and none of those formats could be found. (.eps cannot -be supported due to the design of the PDF format; use regular TeX (DVI -output) for that.)} - -\ifpdf - % - % Color manipulation macros based on pdfcolor.tex. - \def\cmykDarkRed{0.28 1 1 0.35} - \def\cmykBlack{0 0 0 1} - % - \def\pdfsetcolor#1{\pdfliteral{#1 k}} - % Set color, and create a mark which defines \thiscolor accordingly, - % so that \makeheadline knows which color to restore. - \def\setcolor#1{% - \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}% - \domark - \pdfsetcolor{#1}% - } - % - \def\maincolor{\cmykBlack} - \pdfsetcolor{\maincolor} - \edef\thiscolor{\maincolor} - \def\lastcolordefs{} - % - \def\makefootline{% - \baselineskip24pt - \line{\pdfsetcolor{\maincolor}\the\footline}% - } - % - \def\makeheadline{% - \vbox to 0pt{% - \vskip-22.5pt - \line{% - \vbox to8.5pt{}% - % Extract \thiscolor definition from the marks. - \getcolormarks - % Typeset the headline with \maincolor, then restore the color. - \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}% - }% - \vss - }% - \nointerlineskip - } - % - % - \pdfcatalog{/PageMode /UseOutlines} - % - % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). - \def\dopdfimage#1#2#3{% - \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% - \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% - % - % pdftex (and the PDF format) support .png, .jpg, .pdf (among - % others). Let's try in that order. - \let\pdfimgext=\empty - \begingroup - \openin 1 #1.png \ifeof 1 - \openin 1 #1.jpg \ifeof 1 - \openin 1 #1.jpeg \ifeof 1 - \openin 1 #1.JPG \ifeof 1 - \openin 1 #1.pdf \ifeof 1 - \openin 1 #1.PDF \ifeof 1 - \errhelp = \nopdfimagehelp - \errmessage{Could not find image file #1 for pdf}% - \else \gdef\pdfimgext{PDF}% - \fi - \else \gdef\pdfimgext{pdf}% - \fi - \else \gdef\pdfimgext{JPG}% - \fi - \else \gdef\pdfimgext{jpeg}% - \fi - \else \gdef\pdfimgext{jpg}% - \fi - \else \gdef\pdfimgext{png}% - \fi - \closein 1 - \endgroup - % - % without \immediate, ancient pdftex seg faults when the same image is - % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) - \ifnum\pdftexversion < 14 - \immediate\pdfimage - \else - \immediate\pdfximage - \fi - \ifdim \wd0 >0pt width \imagewidth \fi - \ifdim \wd2 >0pt height \imageheight \fi - \ifnum\pdftexversion<13 - #1.\pdfimgext - \else - {#1.\pdfimgext}% - \fi - \ifnum\pdftexversion < 14 \else - \pdfrefximage \pdflastximage - \fi} - % - \def\pdfmkdest#1{{% - % We have to set dummies so commands such as @code, and characters - % such as \, aren't expanded when present in a section title. - \indexnofonts - \turnoffactive - \activebackslashdouble - \makevalueexpandable - \def\pdfdestname{#1}% - \backslashparens\pdfdestname - \safewhatsit{\pdfdest name{\pdfdestname} xyz}% - }} - % - % used to mark target names; must be expandable. - \def\pdfmkpgn#1{#1} - % - % by default, use a color that is dark enough to print on paper as - % nearly black, but still distinguishable for online viewing. - \def\urlcolor{\cmykDarkRed} - \def\linkcolor{\cmykDarkRed} - \def\endlink{\setcolor{\maincolor}\pdfendlink} - % - % Adding outlines to PDF; macros for calculating structure of outlines - % come from Petr Olsak - \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% - \else \csname#1\endcsname \fi} - \def\advancenumber#1{\tempnum=\expnumber{#1}\relax - \advance\tempnum by 1 - \expandafter\xdef\csname#1\endcsname{\the\tempnum}} - % - % #1 is the section text, which is what will be displayed in the - % outline by the pdf viewer. #2 is the pdf expression for the number - % of subentries (or empty, for subsubsections). #3 is the node text, - % which might be empty if this toc entry had no corresponding node. - % #4 is the page number - % - \def\dopdfoutline#1#2#3#4{% - % Generate a link to the node text if that exists; else, use the - % page number. We could generate a destination for the section - % text in the case where a section has no node, but it doesn't - % seem worth the trouble, since most documents are normally structured. - \def\pdfoutlinedest{#3}% - \ifx\pdfoutlinedest\empty - \def\pdfoutlinedest{#4}% - \else - % Doubled backslashes in the name. - {\activebackslashdouble \xdef\pdfoutlinedest{#3}% - \backslashparens\pdfoutlinedest}% - \fi - % - % Also double the backslashes in the display string. - {\activebackslashdouble \xdef\pdfoutlinetext{#1}% - \backslashparens\pdfoutlinetext}% - % - \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% - } - % - \def\pdfmakeoutlines{% - \begingroup - % Thanh's hack / proper braces in bookmarks - \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace - \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace - % - % Read toc silently, to get counts of subentries for \pdfoutline. - \def\numchapentry##1##2##3##4{% - \def\thischapnum{##2}% - \def\thissecnum{0}% - \def\thissubsecnum{0}% - }% - \def\numsecentry##1##2##3##4{% - \advancenumber{chap\thischapnum}% - \def\thissecnum{##2}% - \def\thissubsecnum{0}% - }% - \def\numsubsecentry##1##2##3##4{% - \advancenumber{sec\thissecnum}% - \def\thissubsecnum{##2}% - }% - \def\numsubsubsecentry##1##2##3##4{% - \advancenumber{subsec\thissubsecnum}% - }% - \def\thischapnum{0}% - \def\thissecnum{0}% - \def\thissubsecnum{0}% - % - % use \def rather than \let here because we redefine \chapentry et - % al. a second time, below. - \def\appentry{\numchapentry}% - \def\appsecentry{\numsecentry}% - \def\appsubsecentry{\numsubsecentry}% - \def\appsubsubsecentry{\numsubsubsecentry}% - \def\unnchapentry{\numchapentry}% - \def\unnsecentry{\numsecentry}% - \def\unnsubsecentry{\numsubsecentry}% - \def\unnsubsubsecentry{\numsubsubsecentry}% - \readdatafile{toc}% - % - % Read toc second time, this time actually producing the outlines. - % The `-' means take the \expnumber as the absolute number of - % subentries, which we calculated on our first read of the .toc above. - % - % We use the node names as the destinations. - \def\numchapentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% - \def\numsecentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% - \def\numsubsecentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% - \def\numsubsubsecentry##1##2##3##4{% count is always zero - \dopdfoutline{##1}{}{##3}{##4}}% - % - % PDF outlines are displayed using system fonts, instead of - % document fonts. Therefore we cannot use special characters, - % since the encoding is unknown. For example, the eogonek from - % Latin 2 (0xea) gets translated to a | character. Info from - % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100. - % - % xx to do this right, we have to translate 8-bit characters to - % their "best" equivalent, based on the @documentencoding. Right - % now, I guess we'll just let the pdf reader have its way. - \indexnofonts - \setupdatafile - \catcode`\\=\active \otherbackslash - \input \tocreadfilename - \endgroup - } - % - \def\skipspaces#1{\def\PP{#1}\def\D{|}% - \ifx\PP\D\let\nextsp\relax - \else\let\nextsp\skipspaces - \ifx\p\space\else\addtokens{\filename}{\PP}% - \advance\filenamelength by 1 - \fi - \fi - \nextsp} - \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} - \ifnum\pdftexversion < 14 - \let \startlink \pdfannotlink - \else - \let \startlink \pdfstartlink - \fi - % make a live url in pdf output. - \def\pdfurl#1{% - \begingroup - % it seems we really need yet another set of dummies; have not - % tried to figure out what each command should do in the context - % of @url. for now, just make @/ a no-op, that's the only one - % people have actually reported a problem with. - % - \normalturnoffactive - \def\@{@}% - \let\/=\empty - \makevalueexpandable - \leavevmode\setcolor{\urlcolor}% - \startlink attr{/Border [0 0 0]}% - user{/Subtype /Link /A << /S /URI /URI (#1) >>}% - \endgroup} - \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} - \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} - \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} - \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} - \def\maketoks{% - \expandafter\poptoks\the\toksA|ENDTOKS|\relax - \ifx\first0\adn0 - \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 - \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 - \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 - \else - \ifnum0=\countA\else\makelink\fi - \ifx\first.\let\next=\done\else - \let\next=\maketoks - \addtokens{\toksB}{\the\toksD} - \ifx\first,\addtokens{\toksB}{\space}\fi - \fi - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi - \next} - \def\makelink{\addtokens{\toksB}% - {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} - \def\pdflink#1{% - \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} - \setcolor{\linkcolor}#1\endlink} - \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} -\else - \let\pdfmkdest = \gobble - \let\pdfurl = \gobble - \let\endlink = \relax - \let\setcolor = \gobble - \let\pdfsetcolor = \gobble - \let\pdfmakeoutlines = \relax -\fi % \ifx\pdfoutput - - -\message{fonts,} - -% Change the current font style to #1, remembering it in \curfontstyle. -% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in -% italics, not bold italics. -% -\def\setfontstyle#1{% - \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. - \csname ten#1\endcsname % change the current font -} - -% Select #1 fonts with the current style. -% -\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} - -\def\rm{\fam=0 \setfontstyle{rm}} -\def\it{\fam=\itfam \setfontstyle{it}} -\def\sl{\fam=\slfam \setfontstyle{sl}} -\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} -\def\tt{\fam=\ttfam \setfontstyle{tt}} - -% Texinfo sort of supports the sans serif font style, which plain TeX does not. -% So we set up a \sf. -\newfam\sffam -\def\sf{\fam=\sffam \setfontstyle{sf}} -\let\li = \sf % Sometimes we call it \li, not \sf. - -% We don't need math for this font style. -\def\ttsl{\setfontstyle{ttsl}} - - -% Default leading. -\newdimen\textleading \textleading = 13.2pt - -% Set the baselineskip to #1, and the lineskip and strut size -% correspondingly. There is no deep meaning behind these magic numbers -% used as factors; they just match (closely enough) what Knuth defined. -% -\def\lineskipfactor{.08333} -\def\strutheightpercent{.70833} -\def\strutdepthpercent {.29167} -% -% can get a sort of poor man's double spacing by redefining this. -\def\baselinefactor{1} -% -\def\setleading#1{% - \dimen0 = #1\relax - \normalbaselineskip = \baselinefactor\dimen0 - \normallineskip = \lineskipfactor\normalbaselineskip - \normalbaselines - \setbox\strutbox =\hbox{% - \vrule width0pt height\strutheightpercent\baselineskip - depth \strutdepthpercent \baselineskip - }% -} - -% PDF CMaps. See also LaTeX's t1.cmap. -% -% do nothing with this by default. -\expandafter\let\csname cmapOT1\endcsname\gobble -\expandafter\let\csname cmapOT1IT\endcsname\gobble -\expandafter\let\csname cmapOT1TT\endcsname\gobble - -% if we are producing pdf, and we have \pdffontattr, then define cmaps. -% (\pdffontattr was introduced many years ago, but people still run -% older pdftex's; it's easy to conditionalize, so we do.) -\ifpdf \ifx\pdffontattr\undefined \else - \begingroup - \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. - \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap -%%DocumentNeededResources: ProcSet (CIDInit) -%%IncludeResource: ProcSet (CIDInit) -%%BeginResource: CMap (TeX-OT1-0) -%%Title: (TeX-OT1-0 TeX OT1 0) -%%Version: 1.000 -%%EndComments -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (TeX) -/Ordering (OT1) -/Supplement 0 ->> def -/CMapName /TeX-OT1-0 def -/CMapType 2 def -1 begincodespacerange -<00> <7F> -endcodespacerange -8 beginbfrange -<00> <01> <0393> -<09> <0A> <03A8> -<23> <26> <0023> -<28> <3B> <0028> -<3F> <5B> <003F> -<5D> <5E> <005D> -<61> <7A> <0061> -<7B> <7C> <2013> -endbfrange -40 beginbfchar -<02> <0398> -<03> <039B> -<04> <039E> -<05> <03A0> -<06> <03A3> -<07> <03D2> -<08> <03A6> -<0B> <00660066> -<0C> <00660069> -<0D> <0066006C> -<0E> <006600660069> -<0F> <00660066006C> -<10> <0131> -<11> <0237> -<12> <0060> -<13> <00B4> -<14> <02C7> -<15> <02D8> -<16> <00AF> -<17> <02DA> -<18> <00B8> -<19> <00DF> -<1A> <00E6> -<1B> <0153> -<1C> <00F8> -<1D> <00C6> -<1E> <0152> -<1F> <00D8> -<21> <0021> -<22> <201D> -<27> <2019> -<3C> <00A1> -<3D> <003D> -<3E> <00BF> -<5C> <201C> -<5F> <02D9> -<60> <2018> -<7D> <02DD> -<7E> <007E> -<7F> <00A8> -endbfchar -endcmap -CMapName currentdict /CMap defineresource pop -end -end -%%EndResource -%%EOF - }\endgroup - \expandafter\edef\csname cmapOT1\endcsname#1{% - \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% - }% -% -% \cmapOT1IT - \begingroup - \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. - \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap -%%DocumentNeededResources: ProcSet (CIDInit) -%%IncludeResource: ProcSet (CIDInit) -%%BeginResource: CMap (TeX-OT1IT-0) -%%Title: (TeX-OT1IT-0 TeX OT1IT 0) -%%Version: 1.000 -%%EndComments -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (TeX) -/Ordering (OT1IT) -/Supplement 0 ->> def -/CMapName /TeX-OT1IT-0 def -/CMapType 2 def -1 begincodespacerange -<00> <7F> -endcodespacerange -8 beginbfrange -<00> <01> <0393> -<09> <0A> <03A8> -<25> <26> <0025> -<28> <3B> <0028> -<3F> <5B> <003F> -<5D> <5E> <005D> -<61> <7A> <0061> -<7B> <7C> <2013> -endbfrange -42 beginbfchar -<02> <0398> -<03> <039B> -<04> <039E> -<05> <03A0> -<06> <03A3> -<07> <03D2> -<08> <03A6> -<0B> <00660066> -<0C> <00660069> -<0D> <0066006C> -<0E> <006600660069> -<0F> <00660066006C> -<10> <0131> -<11> <0237> -<12> <0060> -<13> <00B4> -<14> <02C7> -<15> <02D8> -<16> <00AF> -<17> <02DA> -<18> <00B8> -<19> <00DF> -<1A> <00E6> -<1B> <0153> -<1C> <00F8> -<1D> <00C6> -<1E> <0152> -<1F> <00D8> -<21> <0021> -<22> <201D> -<23> <0023> -<24> <00A3> -<27> <2019> -<3C> <00A1> -<3D> <003D> -<3E> <00BF> -<5C> <201C> -<5F> <02D9> -<60> <2018> -<7D> <02DD> -<7E> <007E> -<7F> <00A8> -endbfchar -endcmap -CMapName currentdict /CMap defineresource pop -end -end -%%EndResource -%%EOF - }\endgroup - \expandafter\edef\csname cmapOT1IT\endcsname#1{% - \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% - }% -% -% \cmapOT1TT - \begingroup - \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. - \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap -%%DocumentNeededResources: ProcSet (CIDInit) -%%IncludeResource: ProcSet (CIDInit) -%%BeginResource: CMap (TeX-OT1TT-0) -%%Title: (TeX-OT1TT-0 TeX OT1TT 0) -%%Version: 1.000 -%%EndComments -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (TeX) -/Ordering (OT1TT) -/Supplement 0 ->> def -/CMapName /TeX-OT1TT-0 def -/CMapType 2 def -1 begincodespacerange -<00> <7F> -endcodespacerange -5 beginbfrange -<00> <01> <0393> -<09> <0A> <03A8> -<21> <26> <0021> -<28> <5F> <0028> -<61> <7E> <0061> -endbfrange -32 beginbfchar -<02> <0398> -<03> <039B> -<04> <039E> -<05> <03A0> -<06> <03A3> -<07> <03D2> -<08> <03A6> -<0B> <2191> -<0C> <2193> -<0D> <0027> -<0E> <00A1> -<0F> <00BF> -<10> <0131> -<11> <0237> -<12> <0060> -<13> <00B4> -<14> <02C7> -<15> <02D8> -<16> <00AF> -<17> <02DA> -<18> <00B8> -<19> <00DF> -<1A> <00E6> -<1B> <0153> -<1C> <00F8> -<1D> <00C6> -<1E> <0152> -<1F> <00D8> -<20> <2423> -<27> <2019> -<60> <2018> -<7F> <00A8> -endbfchar -endcmap -CMapName currentdict /CMap defineresource pop -end -end -%%EndResource -%%EOF - }\endgroup - \expandafter\edef\csname cmapOT1TT\endcsname#1{% - \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% - }% -\fi\fi - - -% Set the font macro #1 to the font named #2, adding on the -% specified font prefix (normally `cm'). -% #3 is the font's design size, #4 is a scale factor, #5 is the CMap -% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass -% empty to omit). -\def\setfont#1#2#3#4#5{% - \font#1=\fontprefix#2#3 scaled #4 - \csname cmap#5\endcsname#1% -} -% This is what gets called when #5 of \setfont is empty. -\let\cmap\gobble -% emacs-page end of cmaps - -% Use cm as the default font prefix. -% To specify the font prefix, you must define \fontprefix -% before you read in texinfo.tex. -\ifx\fontprefix\undefined -\def\fontprefix{cm} -\fi -% Support font families that don't use the same naming scheme as CM. -\def\rmshape{r} -\def\rmbshape{bx} %where the normal face is bold -\def\bfshape{b} -\def\bxshape{bx} -\def\ttshape{tt} -\def\ttbshape{tt} -\def\ttslshape{sltt} -\def\itshape{ti} -\def\itbshape{bxti} -\def\slshape{sl} -\def\slbshape{bxsl} -\def\sfshape{ss} -\def\sfbshape{ss} -\def\scshape{csc} -\def\scbshape{csc} - -% Definitions for a main text size of 11pt. This is the default in -% Texinfo. -% -\def\definetextfontsizexi{% -% Text fonts (11.2pt, magstep1). -\def\textnominalsize{11pt} -\edef\mainmagstep{\magstephalf} -\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} -\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} -\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} -\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} -\setfont\textsl\slshape{10}{\mainmagstep}{OT1} -\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} -\setfont\textsc\scshape{10}{\mainmagstep}{OT1} -\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep -\def\textecsize{1095} - -% A few fonts for @defun names and args. -\setfont\defbf\bfshape{10}{\magstep1}{OT1} -\setfont\deftt\ttshape{10}{\magstep1}{OT1TT} -\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} - -% Fonts for indices, footnotes, small examples (9pt). -\def\smallnominalsize{9pt} -\setfont\smallrm\rmshape{9}{1000}{OT1} -\setfont\smalltt\ttshape{9}{1000}{OT1TT} -\setfont\smallbf\bfshape{10}{900}{OT1} -\setfont\smallit\itshape{9}{1000}{OT1IT} -\setfont\smallsl\slshape{9}{1000}{OT1} -\setfont\smallsf\sfshape{9}{1000}{OT1} -\setfont\smallsc\scshape{10}{900}{OT1} -\setfont\smallttsl\ttslshape{10}{900}{OT1TT} -\font\smalli=cmmi9 -\font\smallsy=cmsy9 -\def\smallecsize{0900} - -% Fonts for small examples (8pt). -\def\smallernominalsize{8pt} -\setfont\smallerrm\rmshape{8}{1000}{OT1} -\setfont\smallertt\ttshape{8}{1000}{OT1TT} -\setfont\smallerbf\bfshape{10}{800}{OT1} -\setfont\smallerit\itshape{8}{1000}{OT1IT} -\setfont\smallersl\slshape{8}{1000}{OT1} -\setfont\smallersf\sfshape{8}{1000}{OT1} -\setfont\smallersc\scshape{10}{800}{OT1} -\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} -\font\smalleri=cmmi8 -\font\smallersy=cmsy8 -\def\smallerecsize{0800} - -% Fonts for title page (20.4pt): -\def\titlenominalsize{20pt} -\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} -\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} -\setfont\titlesl\slbshape{10}{\magstep4}{OT1} -\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} -\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} -\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} -\let\titlebf=\titlerm -\setfont\titlesc\scbshape{10}{\magstep4}{OT1} -\font\titlei=cmmi12 scaled \magstep3 -\font\titlesy=cmsy10 scaled \magstep4 -\def\authorrm{\secrm} -\def\authortt{\sectt} -\def\titleecsize{2074} - -% Chapter (and unnumbered) fonts (17.28pt). -\def\chapnominalsize{17pt} -\setfont\chaprm\rmbshape{12}{\magstep2}{OT1} -\setfont\chapit\itbshape{10}{\magstep3}{OT1IT} -\setfont\chapsl\slbshape{10}{\magstep3}{OT1} -\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT} -\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT} -\setfont\chapsf\sfbshape{17}{1000}{OT1} -\let\chapbf=\chaprm -\setfont\chapsc\scbshape{10}{\magstep3}{OT1} -\font\chapi=cmmi12 scaled \magstep2 -\font\chapsy=cmsy10 scaled \magstep3 -\def\chapecsize{1728} - -% Section fonts (14.4pt). -\def\secnominalsize{14pt} -\setfont\secrm\rmbshape{12}{\magstep1}{OT1} -\setfont\secit\itbshape{10}{\magstep2}{OT1IT} -\setfont\secsl\slbshape{10}{\magstep2}{OT1} -\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT} -\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT} -\setfont\secsf\sfbshape{12}{\magstep1}{OT1} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep2}{OT1} -\font\seci=cmmi12 scaled \magstep1 -\font\secsy=cmsy10 scaled \magstep2 -\def\sececsize{1440} - -% Subsection fonts (13.15pt). -\def\ssecnominalsize{13pt} -\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1} -\setfont\ssecit\itbshape{10}{1315}{OT1IT} -\setfont\ssecsl\slbshape{10}{1315}{OT1} -\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT} -\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT} -\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{1315}{OT1} -\font\sseci=cmmi12 scaled \magstephalf -\font\ssecsy=cmsy10 scaled 1315 -\def\ssececsize{1200} - -% Reduced fonts for @acro in text (10pt). -\def\reducednominalsize{10pt} -\setfont\reducedrm\rmshape{10}{1000}{OT1} -\setfont\reducedtt\ttshape{10}{1000}{OT1TT} -\setfont\reducedbf\bfshape{10}{1000}{OT1} -\setfont\reducedit\itshape{10}{1000}{OT1IT} -\setfont\reducedsl\slshape{10}{1000}{OT1} -\setfont\reducedsf\sfshape{10}{1000}{OT1} -\setfont\reducedsc\scshape{10}{1000}{OT1} -\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT} -\font\reducedi=cmmi10 -\font\reducedsy=cmsy10 -\def\reducedecsize{1000} - -% reset the current fonts -\textfonts -\rm -} % end of 11pt text font size definitions - - -% Definitions to make the main text be 10pt Computer Modern, with -% section, chapter, etc., sizes following suit. This is for the GNU -% Press printing of the Emacs 22 manual. Maybe other manuals in the -% future. Used with @smallbook, which sets the leading to 12pt. -% -\def\definetextfontsizex{% -% Text fonts (10pt). -\def\textnominalsize{10pt} -\edef\mainmagstep{1000} -\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} -\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} -\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} -\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} -\setfont\textsl\slshape{10}{\mainmagstep}{OT1} -\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} -\setfont\textsc\scshape{10}{\mainmagstep}{OT1} -\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep -\def\textecsize{1000} - -% A few fonts for @defun names and args. -\setfont\defbf\bfshape{10}{\magstephalf}{OT1} -\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} -\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} - -% Fonts for indices, footnotes, small examples (9pt). -\def\smallnominalsize{9pt} -\setfont\smallrm\rmshape{9}{1000}{OT1} -\setfont\smalltt\ttshape{9}{1000}{OT1TT} -\setfont\smallbf\bfshape{10}{900}{OT1} -\setfont\smallit\itshape{9}{1000}{OT1IT} -\setfont\smallsl\slshape{9}{1000}{OT1} -\setfont\smallsf\sfshape{9}{1000}{OT1} -\setfont\smallsc\scshape{10}{900}{OT1} -\setfont\smallttsl\ttslshape{10}{900}{OT1TT} -\font\smalli=cmmi9 -\font\smallsy=cmsy9 -\def\smallecsize{0900} - -% Fonts for small examples (8pt). -\def\smallernominalsize{8pt} -\setfont\smallerrm\rmshape{8}{1000}{OT1} -\setfont\smallertt\ttshape{8}{1000}{OT1TT} -\setfont\smallerbf\bfshape{10}{800}{OT1} -\setfont\smallerit\itshape{8}{1000}{OT1IT} -\setfont\smallersl\slshape{8}{1000}{OT1} -\setfont\smallersf\sfshape{8}{1000}{OT1} -\setfont\smallersc\scshape{10}{800}{OT1} -\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} -\font\smalleri=cmmi8 -\font\smallersy=cmsy8 -\def\smallerecsize{0800} - -% Fonts for title page (20.4pt): -\def\titlenominalsize{20pt} -\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} -\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} -\setfont\titlesl\slbshape{10}{\magstep4}{OT1} -\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} -\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} -\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} -\let\titlebf=\titlerm -\setfont\titlesc\scbshape{10}{\magstep4}{OT1} -\font\titlei=cmmi12 scaled \magstep3 -\font\titlesy=cmsy10 scaled \magstep4 -\def\authorrm{\secrm} -\def\authortt{\sectt} -\def\titleecsize{2074} - -% Chapter fonts (14.4pt). -\def\chapnominalsize{14pt} -\setfont\chaprm\rmbshape{12}{\magstep1}{OT1} -\setfont\chapit\itbshape{10}{\magstep2}{OT1IT} -\setfont\chapsl\slbshape{10}{\magstep2}{OT1} -\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT} -\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT} -\setfont\chapsf\sfbshape{12}{\magstep1}{OT1} -\let\chapbf\chaprm -\setfont\chapsc\scbshape{10}{\magstep2}{OT1} -\font\chapi=cmmi12 scaled \magstep1 -\font\chapsy=cmsy10 scaled \magstep2 -\def\chapecsize{1440} - -% Section fonts (12pt). -\def\secnominalsize{12pt} -\setfont\secrm\rmbshape{12}{1000}{OT1} -\setfont\secit\itbshape{10}{\magstep1}{OT1IT} -\setfont\secsl\slbshape{10}{\magstep1}{OT1} -\setfont\sectt\ttbshape{12}{1000}{OT1TT} -\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT} -\setfont\secsf\sfbshape{12}{1000}{OT1} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep1}{OT1} -\font\seci=cmmi12 -\font\secsy=cmsy10 scaled \magstep1 -\def\sececsize{1200} - -% Subsection fonts (10pt). -\def\ssecnominalsize{10pt} -\setfont\ssecrm\rmbshape{10}{1000}{OT1} -\setfont\ssecit\itbshape{10}{1000}{OT1IT} -\setfont\ssecsl\slbshape{10}{1000}{OT1} -\setfont\ssectt\ttbshape{10}{1000}{OT1TT} -\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT} -\setfont\ssecsf\sfbshape{10}{1000}{OT1} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{1000}{OT1} -\font\sseci=cmmi10 -\font\ssecsy=cmsy10 -\def\ssececsize{1000} - -% Reduced fonts for @acro in text (9pt). -\def\reducednominalsize{9pt} -\setfont\reducedrm\rmshape{9}{1000}{OT1} -\setfont\reducedtt\ttshape{9}{1000}{OT1TT} -\setfont\reducedbf\bfshape{10}{900}{OT1} -\setfont\reducedit\itshape{9}{1000}{OT1IT} -\setfont\reducedsl\slshape{9}{1000}{OT1} -\setfont\reducedsf\sfshape{9}{1000}{OT1} -\setfont\reducedsc\scshape{10}{900}{OT1} -\setfont\reducedttsl\ttslshape{10}{900}{OT1TT} -\font\reducedi=cmmi9 -\font\reducedsy=cmsy9 -\def\reducedecsize{0900} - -% reduce space between paragraphs -\divide\parskip by 2 - -% reset the current fonts -\textfonts -\rm -} % end of 10pt text font size definitions - - -% We provide the user-level command -% @fonttextsize 10 -% (or 11) to redefine the text font size. pt is assumed. -% -\def\xword{10} -\def\xiword{11} -% -\parseargdef\fonttextsize{% - \def\textsizearg{#1}% - \wlog{doing @fonttextsize \textsizearg}% - % - % Set \globaldefs so that documents can use this inside @tex, since - % makeinfo 4.8 does not support it, but we need it nonetheless. - % - \begingroup \globaldefs=1 - \ifx\textsizearg\xword \definetextfontsizex - \else \ifx\textsizearg\xiword \definetextfontsizexi - \else - \errhelp=\EMsimple - \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'} - \fi\fi - \endgroup -} - - -% In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. Since -% texinfo doesn't allow for producing subscripts and superscripts except -% in the main text, we don't bother to reset \scriptfont and -% \scriptscriptfont (which would also require loading a lot more fonts). -% -\def\resetmathfonts{% - \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy - \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf - \textfont\ttfam=\tentt \textfont\sffam=\tensf -} - -% The font-changing commands redefine the meanings of \tenSTYLE, instead -% of just \STYLE. We do this because \STYLE needs to also set the -% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire -% \tenSTYLE to set the current font. -% -% Each font-changing command also sets the names \lsize (one size lower) -% and \lllsize (three sizes lower). These relative commands are used in -% the LaTeX logo and acronyms. -% -% This all needs generalizing, badly. -% -\def\textfonts{% - \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl - \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy - \let\tenttsl=\textttsl - \def\curfontsize{text}% - \def\lsize{reduced}\def\lllsize{smaller}% - \resetmathfonts \setleading{\textleading}} -\def\titlefonts{% - \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl - \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc - \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy - \let\tenttsl=\titlettsl - \def\curfontsize{title}% - \def\lsize{chap}\def\lllsize{subsec}% - \resetmathfonts \setleading{25pt}} -\def\titlefont#1{{\titlefonts\rm #1}} -\def\chapfonts{% - \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl - \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy - \let\tenttsl=\chapttsl - \def\curfontsize{chap}% - \def\lsize{sec}\def\lllsize{text}% - \resetmathfonts \setleading{19pt}} -\def\secfonts{% - \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl - \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy - \let\tenttsl=\secttsl - \def\curfontsize{sec}% - \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} -\def\subsecfonts{% - \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl - \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy - \let\tenttsl=\ssecttsl - \def\curfontsize{ssec}% - \def\lsize{text}\def\lllsize{small}% - \resetmathfonts \setleading{15pt}} -\let\subsubsecfonts = \subsecfonts -\def\reducedfonts{% - \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl - \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc - \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy - \let\tenttsl=\reducedttsl - \def\curfontsize{reduced}% - \def\lsize{small}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallfonts{% - \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl - \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc - \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy - \let\tenttsl=\smallttsl - \def\curfontsize{small}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallerfonts{% - \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl - \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc - \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy - \let\tenttsl=\smallerttsl - \def\curfontsize{smaller}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{9.5pt}} - -% Set the fonts to use with the @small... environments. -\let\smallexamplefonts = \smallfonts - -% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample -% can fit this many characters: -% 8.5x11=86 smallbook=72 a4=90 a5=69 -% If we use \scriptfonts (8pt), then we can fit this many characters: -% 8.5x11=90+ smallbook=80 a4=90+ a5=77 -% For me, subjectively, the few extra characters that fit aren't worth -% the additional smallness of 8pt. So I'm making the default 9pt. -% -% By the way, for comparison, here's what fits with @example (10pt): -% 8.5x11=71 smallbook=60 a4=75 a5=58 -% -% I wish the USA used A4 paper. -% --karl, 24jan03. - - -% Set up the default fonts, so we can use them for creating boxes. -% -\definetextfontsizexi - -% Define these so they can be easily changed for other fonts. -\def\angleleft{$\langle$} -\def\angleright{$\rangle$} - -% Count depth in font-changes, for error checks -\newcount\fontdepth \fontdepth=0 - -% Fonts for short table of contents. -\setfont\shortcontrm\rmshape{12}{1000}{OT1} -\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 -\setfont\shortcontsl\slshape{12}{1000}{OT1} -\setfont\shortconttt\ttshape{12}{1000}{OT1TT} - -%% Add scribe-like font environments, plus @l for inline lisp (usually sans -%% serif) and @ii for TeX italic - -% \smartitalic{ARG} outputs arg in italics, followed by an italic correction -% unless the following character is such as not to need one. -\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else - \ptexslash\fi\fi\fi} -\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} -\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} - -% like \smartslanted except unconditionally uses \ttsl. -% @var is set to this for defun arguments. -\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} - -% like \smartslanted except unconditionally use \sl. We never want -% ttsl for book titles, do we? -\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} - -\let\i=\smartitalic -\let\slanted=\smartslanted -\let\var=\smartslanted -\let\dfn=\smartslanted -\let\emph=\smartitalic - -% @b, explicit bold. -\def\b#1{{\bf #1}} -\let\strong=\b - -% @sansserif, explicit sans. -\def\sansserif#1{{\sf #1}} - -% We can't just use \exhyphenpenalty, because that only has effect at -% the end of a paragraph. Restore normal hyphenation at the end of the -% group within which \nohyphenation is presumably called. -% -\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} -\def\restorehyphenation{\hyphenchar\font = `- } - -% Set sfcode to normal for the chars that usually have another value. -% Can't use plain's \frenchspacing because it uses the `\x notation, and -% sometimes \x has an active definition that messes things up. -% -\catcode`@=11 - \def\plainfrenchspacing{% - \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m - \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m - \def\endofsentencespacefactor{1000}% for @. and friends - } - \def\plainnonfrenchspacing{% - \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000 - \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 - \def\endofsentencespacefactor{3000}% for @. and friends - } -\catcode`@=\other -\def\endofsentencespacefactor{3000}% default - -\def\t#1{% - {\tt \rawbackslash \plainfrenchspacing #1}% - \null -} -\def\samp#1{`\tclose{#1}'\null} -\setfont\keyrm\rmshape{8}{1000}{OT1} -\font\keysy=cmsy9 -\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% - \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% - \vbox{\hrule\kern-0.4pt - \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% - \kern-0.4pt\hrule}% - \kern-.06em\raise0.4pt\hbox{\angleright}}}} -\def\key #1{{\nohyphenation \uppercase{#1}}\null} -% The old definition, with no lozenge: -%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} -\def\ctrl #1{{\tt \rawbackslash \hat}#1} - -% @file, @option are the same as @samp. -\let\file=\samp -\let\option=\samp - -% @code is a modification of @t, -% which makes spaces the same size as normal in the surrounding text. -\def\tclose#1{% - {% - % Change normal interword space to be same as for the current font. - \spaceskip = \fontdimen2\font - % - % Switch to typewriter. - \tt - % - % But `\ ' produces the large typewriter interword space. - \def\ {{\spaceskip = 0pt{} }}% - % - % Turn off hyphenation. - \nohyphenation - % - \rawbackslash - \plainfrenchspacing - #1% - }% - \null -} - -% We *must* turn on hyphenation at `-' and `_' in @code. -% Otherwise, it is too hard to avoid overfull hboxes -% in the Emacs manual, the Library manual, etc. - -% Unfortunately, TeX uses one parameter (\hyphenchar) to control -% both hyphenation at - and hyphenation within words. -% We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate at a dash. -% -- rms. -{ - \catcode`\-=\active \catcode`\_=\active - \catcode`\'=\active \catcode`\`=\active - % - \global\def\code{\begingroup - \catcode\rquoteChar=\active \catcode\lquoteChar=\active - \let'\codequoteright \let`\codequoteleft - % - \catcode\dashChar=\active \catcode\underChar=\active - \ifallowcodebreaks - \let-\codedash - \let_\codeunder - \else - \let-\realdash - \let_\realunder - \fi - \codex - } -} - -\def\realdash{-} -\def\codedash{-\discretionary{}{}{}} -\def\codeunder{% - % this is all so @math{@code{var_name}+1} can work. In math mode, _ - % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) - % will therefore expand the active definition of _, which is us - % (inside @code that is), therefore an endless loop. - \ifusingtt{\ifmmode - \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. - \else\normalunderscore \fi - \discretionary{}{}{}}% - {\_}% -} -\def\codex #1{\tclose{#1}\endgroup} - -% An additional complication: the above will allow breaks after, e.g., -% each of the four underscores in __typeof__. This is undesirable in -% some manuals, especially if they don't have long identifiers in -% general. @allowcodebreaks provides a way to control this. -% -\newif\ifallowcodebreaks \allowcodebreakstrue - -\def\keywordtrue{true} -\def\keywordfalse{false} - -\parseargdef\allowcodebreaks{% - \def\txiarg{#1}% - \ifx\txiarg\keywordtrue - \allowcodebreakstrue - \else\ifx\txiarg\keywordfalse - \allowcodebreaksfalse - \else - \errhelp = \EMsimple - \errmessage{Unknown @allowcodebreaks option `\txiarg'}% - \fi\fi -} - -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. - -% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), -% `example' (@kbd uses ttsl only inside of @example and friends), -% or `code' (@kbd uses normal tty font always). -\parseargdef\kbdinputstyle{% - \def\txiarg{#1}% - \ifx\txiarg\worddistinct - \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% - \else\ifx\txiarg\wordexample - \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% - \else\ifx\txiarg\wordcode - \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% - \else - \errhelp = \EMsimple - \errmessage{Unknown @kbdinputstyle option `\txiarg'}% - \fi\fi\fi -} -\def\worddistinct{distinct} -\def\wordexample{example} -\def\wordcode{code} - -% Default is `distinct.' -\kbdinputstyle distinct - -\def\xkey{\key} -\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% -\ifx\one\xkey\ifx\threex\three \key{#2}% -\else{\tclose{\kbdfont\look}}\fi -\else{\tclose{\kbdfont\look}}\fi} - -% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. -\let\indicateurl=\code -\let\env=\code -\let\command=\code - -% @clicksequence{File @click{} Open ...} -\def\clicksequence#1{\begingroup #1\endgroup} - -% @clickstyle @arrow (by default) -\parseargdef\clickstyle{\def\click{#1}} -\def\click{\arrow} - -% @uref (abbreviation for `urlref') takes an optional (comma-separated) -% second argument specifying the text to display and an optional third -% arg as text to display instead of (rather than in addition to) the url -% itself. First (mandatory) arg is the url. Perhaps eventually put in -% a hypertex \special here. -% -\def\uref#1{\douref #1,,,\finish} -\def\douref#1,#2,#3,#4\finish{\begingroup - \unsepspaces - \pdfurl{#1}% - \setbox0 = \hbox{\ignorespaces #3}% - \ifdim\wd0 > 0pt - \unhbox0 % third arg given, show only that - \else - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it - \else - \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url - \fi - \else - \code{#1}% only url given, so show it - \fi - \fi - \endlink -\endgroup} - -% @url synonym for @uref, since that's how everyone uses it. -% -\let\url=\uref - -% rms does not like angle brackets --karl, 17may97. -% So now @email is just like @uref, unless we are pdf. -% -%\def\email#1{\angleleft{\tt #1}\angleright} -\ifpdf - \def\email#1{\doemail#1,,\finish} - \def\doemail#1,#2,#3\finish{\begingroup - \unsepspaces - \pdfurl{mailto:#1}% - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi - \endlink - \endgroup} -\else - \let\email=\uref -\fi - -% Check if we are currently using a typewriter font. Since all the -% Computer Modern typewriter fonts have zero interword stretch (and -% shrink), and it is reasonable to expect all typewriter fonts to have -% this property, we can check that font parameter. -% -\def\ifmonospace{\ifdim\fontdimen3\font=0pt } - -% Typeset a dimension, e.g., `in' or `pt'. The only reason for the -% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. -% -\def\dmn#1{\thinspace #1} - -\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} - -% @l was never documented to mean ``switch to the Lisp font'', -% and it is not used as such in any manual I can find. We need it for -% Polish suppressed-l. --karl, 22sep96. -%\def\l#1{{\li #1}\null} - -% Explicit font changes: @r, @sc, undocumented @ii. -\def\r#1{{\rm #1}} % roman font -\def\sc#1{{\smallcaps#1}} % smallcaps font -\def\ii#1{{\it #1}} % italic font - -% @acronym for "FBI", "NATO", and the like. -% We print this one point size smaller, since it's intended for -% all-uppercase. -% -\def\acronym#1{\doacronym #1,,\finish} -\def\doacronym#1,#2,#3\finish{% - {\selectfonts\lsize #1}% - \def\temp{#2}% - \ifx\temp\empty \else - \space ({\unsepspaces \ignorespaces \temp \unskip})% - \fi -} - -% @abbr for "Comput. J." and the like. -% No font change, but don't do end-of-sentence spacing. -% -\def\abbr#1{\doabbr #1,,\finish} -\def\doabbr#1,#2,#3\finish{% - {\plainfrenchspacing #1}% - \def\temp{#2}% - \ifx\temp\empty \else - \space ({\unsepspaces \ignorespaces \temp \unskip})% - \fi -} - -% @pounds{} is a sterling sign, which Knuth put in the CM italic font. -% -\def\pounds{{\it\$}} - -% @euro{} comes from a separate font, depending on the current style. -% We use the free feym* fonts from the eurosym package by Henrik -% Theiling, which support regular, slanted, bold and bold slanted (and -% "outlined" (blackboard board, sort of) versions, which we don't need). -% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. -% -% Although only regular is the truly official Euro symbol, we ignore -% that. The Euro is designed to be slightly taller than the regular -% font height. -% -% feymr - regular -% feymo - slanted -% feybr - bold -% feybo - bold slanted -% -% There is no good (free) typewriter version, to my knowledge. -% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. -% Hmm. -% -% Also doesn't work in math. Do we need to do math with euro symbols? -% Hope not. -% -% -\def\euro{{\eurofont e}} -\def\eurofont{% - % We set the font at each command, rather than predefining it in - % \textfonts and the other font-switching commands, so that - % installations which never need the symbol don't have to have the - % font installed. - % - % There is only one designed size (nominal 10pt), so we always scale - % that to the current nominal size. - % - % By the way, simply using "at 1em" works for cmr10 and the like, but - % does not work for cmbx10 and other extended/shrunken fonts. - % - \def\eurosize{\csname\curfontsize nominalsize\endcsname}% - % - \ifx\curfontstyle\bfstylename - % bold: - \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize - \else - % regular: - \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize - \fi - \thiseurofont -} - -% Hacks for glyphs from the EC fonts similar to \euro. We don't -% use \let for the aliases, because sometimes we redefine the original -% macro, and the alias should reflect the redefinition. -\def\guillemetleft{{\ecfont \char"13}} -\def\guillemotleft{\guillemetleft} -\def\guillemetright{{\ecfont \char"14}} -\def\guillemotright{\guillemetright} -\def\guilsinglleft{{\ecfont \char"0E}} -\def\guilsinglright{{\ecfont \char"0F}} -\def\quotedblbase{{\ecfont \char"12}} -\def\quotesinglbase{{\ecfont \char"0D}} -% -\def\ecfont{% - % We can't distinguish serif/sanserif and italic/slanted, but this - % is used for crude hacks anyway (like adding French and German - % quotes to documents typeset with CM, where we lose kerning), so - % hopefully nobody will notice/care. - \edef\ecsize{\csname\curfontsize ecsize\endcsname}% - \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}% - \ifx\curfontstyle\bfstylename - % bold: - \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize - \else - % regular: - \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize - \fi - \thisecfont -} - -% @registeredsymbol - R in a circle. The font for the R should really -% be smaller yet, but lllsize is the best we can do for now. -% Adapted from the plain.tex definition of \copyright. -% -\def\registeredsymbol{% - $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% - \hfil\crcr\Orb}}% - }$% -} - -% @textdegree - the normal degrees sign. -% -\def\textdegree{$^\circ$} - -% Laurent Siebenmann reports \Orb undefined with: -% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 -% so we'll define it if necessary. -% -\ifx\Orb\undefined -\def\Orb{\mathhexbox20D} -\fi - -% Quotes. -\chardef\quotedblleft="5C -\chardef\quotedblright=`\" -\chardef\quoteleft=`\` -\chardef\quoteright=`\' - - -\message{page headings,} - -\newskip\titlepagetopglue \titlepagetopglue = 1.5in -\newskip\titlepagebottomglue \titlepagebottomglue = 2pc - -% First the title page. Must do @settitle before @titlepage. -\newif\ifseenauthor -\newif\iffinishedtitlepage - -% Do an implicit @contents or @shortcontents after @end titlepage if the -% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. -% -\newif\ifsetcontentsaftertitlepage - \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue -\newif\ifsetshortcontentsaftertitlepage - \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue - -\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% - \endgroup\page\hbox{}\page} - -\envdef\titlepage{% - % Open one extra group, as we want to close it in the middle of \Etitlepage. - \begingroup - \parindent=0pt \textfonts - % Leave some space at the very top of the page. - \vglue\titlepagetopglue - % No rule at page bottom unless we print one at the top with @title. - \finishedtitlepagetrue - % - % Most title ``pages'' are actually two pages long, with space - % at the top of the second. We don't want the ragged left on the second. - \let\oldpage = \page - \def\page{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - \let\page = \oldpage - \page - \null - }% -} - -\def\Etitlepage{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - % It is important to do the page break before ending the group, - % because the headline and footline are only empty inside the group. - % If we use the new definition of \page, we always get a blank page - % after the title page, which we certainly don't want. - \oldpage - \endgroup - % - % Need this before the \...aftertitlepage checks so that if they are - % in effect the toc pages will come out with page numbers. - \HEADINGSon - % - % If they want short, they certainly want long too. - \ifsetshortcontentsaftertitlepage - \shortcontents - \contents - \global\let\shortcontents = \relax - \global\let\contents = \relax - \fi - % - \ifsetcontentsaftertitlepage - \contents - \global\let\contents = \relax - \global\let\shortcontents = \relax - \fi -} - -\def\finishtitlepage{% - \vskip4pt \hrule height 2pt width \hsize - \vskip\titlepagebottomglue - \finishedtitlepagetrue -} - -%%% Macros to be used within @titlepage: - -\let\subtitlerm=\tenrm -\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} - -\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines - \let\tt=\authortt} - -\parseargdef\title{% - \checkenv\titlepage - \leftline{\titlefonts\rm #1} - % print a rule at the page bottom also. - \finishedtitlepagefalse - \vskip4pt \hrule height 4pt width \hsize \vskip4pt -} - -\parseargdef\subtitle{% - \checkenv\titlepage - {\subtitlefont \rightline{#1}}% -} - -% @author should come last, but may come many times. -% It can also be used inside @quotation. -% -\parseargdef\author{% - \def\temp{\quotation}% - \ifx\thisenv\temp - \def\quotationauthor{#1}% printed in \Equotation. - \else - \checkenv\titlepage - \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi - {\authorfont \leftline{#1}}% - \fi -} - - -%%% Set up page headings and footings. - -\let\thispage=\folio - -\newtoks\evenheadline % headline on even pages -\newtoks\oddheadline % headline on odd pages -\newtoks\evenfootline % footline on even pages -\newtoks\oddfootline % footline on odd pages - -% Now make TeX use those variables -\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline - \else \the\evenheadline \fi}} -\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline - \else \the\evenfootline \fi}\HEADINGShook} -\let\HEADINGShook=\relax - -% Commands to set those variables. -% For example, this is what @headings on does -% @evenheading @thistitle|@thispage|@thischapter -% @oddheading @thischapter|@thispage|@thistitle -% @evenfooting @thisfile|| -% @oddfooting ||@thisfile - - -\def\evenheading{\parsearg\evenheadingxxx} -\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} -\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\def\oddheading{\parsearg\oddheadingxxx} -\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} -\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% - -\def\evenfooting{\parsearg\evenfootingxxx} -\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} -\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% -\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\def\oddfooting{\parsearg\oddfootingxxx} -\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} -\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% - \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% - % - % Leave some space for the footline. Hopefully ok to assume - % @evenfooting will not be used by itself. - \global\advance\pageheight by -12pt - \global\advance\vsize by -12pt -} - -\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} - -% @evenheadingmarks top \thischapter <- chapter at the top of a page -% @evenheadingmarks bottom \thischapter <- chapter at the bottom of a page -% -% The same set of arguments for: -% -% @oddheadingmarks -% @evenfootingmarks -% @oddfootingmarks -% @everyheadingmarks -% @everyfootingmarks - -\def\evenheadingmarks{\headingmarks{even}{heading}} -\def\oddheadingmarks{\headingmarks{odd}{heading}} -\def\evenfootingmarks{\headingmarks{even}{footing}} -\def\oddfootingmarks{\headingmarks{odd}{footing}} -\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1} - \headingmarks{odd}{heading}{#1} } -\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1} - \headingmarks{odd}{footing}{#1} } -% #1 = even/odd, #2 = heading/footing, #3 = top/bottom. -\def\headingmarks#1#2#3 {% - \expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname - \global\expandafter\let\csname get#1#2marks\endcsname \temp -} - -\everyheadingmarks bottom -\everyfootingmarks bottom - -% @headings double turns headings on for double-sided printing. -% @headings single turns headings on for single-sided printing. -% @headings off turns them off. -% @headings on same as @headings double, retained for compatibility. -% @headings after turns on double-sided headings after this page. -% @headings doubleafter turns on double-sided headings after this page. -% @headings singleafter turns on single-sided headings after this page. -% By default, they are off at the start of a document, -% and turned `on' after @end titlepage. - -\def\headings #1 {\csname HEADINGS#1\endcsname} - -\def\HEADINGSoff{% -\global\evenheadline={\hfil} \global\evenfootline={\hfil} -\global\oddheadline={\hfil} \global\oddfootline={\hfil}} -\HEADINGSoff -% When we turn headings on, set the page number to 1. -% For double-sided printing, put current file name in lower left corner, -% chapter name on inside top of right hand pages, document -% title on inside top of left hand pages, and page numbers on outside top -% edge of all pages. -\def\HEADINGSdouble{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} -\let\contentsalignmacro = \chappager - -% For single-sided printing, chapter title goes across top left of page, -% page number on top right. -\def\HEADINGSsingle{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} -\def\HEADINGSon{\HEADINGSdouble} - -\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} -\let\HEADINGSdoubleafter=\HEADINGSafter -\def\HEADINGSdoublex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} - -\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} -\def\HEADINGSsinglex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} - -% Subroutines used in generating headings -% This produces Day Month Year style of output. -% Only define if not already defined, in case a txi-??.tex file has set -% up a different format (e.g., txi-cs.tex does this). -\ifx\today\undefined -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} -\fi - -% @settitle line... specifies the title of the document, for headings. -% It generates no output of its own. -\def\thistitle{\putwordNoTitle} -\def\settitle{\parsearg{\gdef\thistitle}} - - -\message{tables,} -% Tables -- @table, @ftable, @vtable, @item(x). - -% default indentation of table text -\newdimen\tableindent \tableindent=.8in -% default indentation of @itemize and @enumerate text -\newdimen\itemindent \itemindent=.3in -% margin between end of table item and start of table text. -\newdimen\itemmargin \itemmargin=.1in - -% used internally for \itemindent minus \itemmargin -\newdimen\itemmax - -% Note @table, @ftable, and @vtable define @item, @itemx, etc., with -% these defs. -% They also define \itemindex -% to index the item name in whatever manner is desired (perhaps none). - -\newif\ifitemxneedsnegativevskip - -\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} - -\def\internalBitem{\smallbreak \parsearg\itemzzz} -\def\internalBitemx{\itemxpar \parsearg\itemzzz} - -\def\itemzzz #1{\begingroup % - \advance\hsize by -\rightskip - \advance\hsize by -\tableindent - \setbox0=\hbox{\itemindicate{#1}}% - \itemindex{#1}% - \nobreak % This prevents a break before @itemx. - % - % If the item text does not fit in the space we have, put it on a line - % by itself, and do not allow a page break either before or after that - % line. We do not start a paragraph here because then if the next - % command is, e.g., @kindex, the whatsit would get put into the - % horizontal list on a line by itself, resulting in extra blank space. - \ifdim \wd0>\itemmax - % - % Make this a paragraph so we get the \parskip glue and wrapping, - % but leave it ragged-right. - \begingroup - \advance\leftskip by-\tableindent - \advance\hsize by\tableindent - \advance\rightskip by0pt plus1fil - \leavevmode\unhbox0\par - \endgroup - % - % We're going to be starting a paragraph, but we don't want the - % \parskip glue -- logically it's part of the @item we just started. - \nobreak \vskip-\parskip - % - % Stop a page break at the \parskip glue coming up. However, if - % what follows is an environment such as @example, there will be no - % \parskip glue; then the negative vskip we just inserted would - % cause the example and the item to crash together. So we use this - % bizarre value of 10001 as a signal to \aboveenvbreak to insert - % \parskip glue after all. Section titles are handled this way also. - % - \penalty 10001 - \endgroup - \itemxneedsnegativevskipfalse - \else - % The item text fits into the space. Start a paragraph, so that the - % following text (if any) will end up on the same line. - \noindent - % Do this with kerns and \unhbox so that if there is a footnote in - % the item text, it can migrate to the main vertical list and - % eventually be printed. - \nobreak\kern-\tableindent - \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 - \unhbox0 - \nobreak\kern\dimen0 - \endgroup - \itemxneedsnegativevskiptrue - \fi -} - -\def\item{\errmessage{@item while not in a list environment}} -\def\itemx{\errmessage{@itemx while not in a list environment}} - -% @table, @ftable, @vtable. -\envdef\table{% - \let\itemindex\gobble - \tablecheck{table}% -} -\envdef\ftable{% - \def\itemindex ##1{\doind {fn}{\code{##1}}}% - \tablecheck{ftable}% -} -\envdef\vtable{% - \def\itemindex ##1{\doind {vr}{\code{##1}}}% - \tablecheck{vtable}% -} -\def\tablecheck#1{% - \ifnum \the\catcode`\^^M=\active - \endgroup - \errmessage{This command won't work in this context; perhaps the problem is - that we are \inenvironment\thisenv}% - \def\next{\doignore{#1}}% - \else - \let\next\tablex - \fi - \next -} -\def\tablex#1{% - \def\itemindicate{#1}% - \parsearg\tabley -} -\def\tabley#1{% - {% - \makevalueexpandable - \edef\temp{\noexpand\tablez #1\space\space\space}% - \expandafter - }\temp \endtablez -} -\def\tablez #1 #2 #3 #4\endtablez{% - \aboveenvbreak - \ifnum 0#1>0 \advance \leftskip by #1\mil \fi - \ifnum 0#2>0 \tableindent=#2\mil \fi - \ifnum 0#3>0 \advance \rightskip by #3\mil \fi - \itemmax=\tableindent - \advance \itemmax by -\itemmargin - \advance \leftskip by \tableindent - \exdentamount=\tableindent - \parindent = 0pt - \parskip = \smallskipamount - \ifdim \parskip=0pt \parskip=2pt \fi - \let\item = \internalBitem - \let\itemx = \internalBitemx -} -\def\Etable{\endgraf\afterenvbreak} -\let\Eftable\Etable -\let\Evtable\Etable -\let\Eitemize\Etable -\let\Eenumerate\Etable - -% This is the counter used by @enumerate, which is really @itemize - -\newcount \itemno - -\envdef\itemize{\parsearg\doitemize} - -\def\doitemize#1{% - \aboveenvbreak - \itemmax=\itemindent - \advance\itemmax by -\itemmargin - \advance\leftskip by \itemindent - \exdentamount=\itemindent - \parindent=0pt - \parskip=\smallskipamount - \ifdim\parskip=0pt \parskip=2pt \fi - \def\itemcontents{#1}% - % @itemize with no arg is equivalent to @itemize @bullet. - \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi - \let\item=\itemizeitem -} - -% Definition of @item while inside @itemize and @enumerate. -% -\def\itemizeitem{% - \advance\itemno by 1 % for enumerations - {\let\par=\endgraf \smallbreak}% reasonable place to break - {% - % If the document has an @itemize directly after a section title, a - % \nobreak will be last on the list, and \sectionheading will have - % done a \vskip-\parskip. In that case, we don't want to zero - % parskip, or the item text will crash with the heading. On the - % other hand, when there is normal text preceding the item (as there - % usually is), we do want to zero parskip, or there would be too much - % space. In that case, we won't have a \nobreak before. At least - % that's the theory. - \ifnum\lastpenalty<10000 \parskip=0in \fi - \noindent - \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% - \vadjust{\penalty 1200}}% not good to break after first line of item. - \flushcr -} - -% \splitoff TOKENS\endmark defines \first to be the first token in -% TOKENS, and \rest to be the remainder. -% -\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% - -% Allow an optional argument of an uppercase letter, lowercase letter, -% or number, to specify the first label in the enumerated list. No -% argument is the same as `1'. -% -\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} -\def\enumeratey #1 #2\endenumeratey{% - % If we were given no argument, pretend we were given `1'. - \def\thearg{#1}% - \ifx\thearg\empty \def\thearg{1}\fi - % - % Detect if the argument is a single token. If so, it might be a - % letter. Otherwise, the only valid thing it can be is a number. - % (We will always have one token, because of the test we just made. - % This is a good thing, since \splitoff doesn't work given nothing at - % all -- the first parameter is undelimited.) - \expandafter\splitoff\thearg\endmark - \ifx\rest\empty - % Only one token in the argument. It could still be anything. - % A ``lowercase letter'' is one whose \lccode is nonzero. - % An ``uppercase letter'' is one whose \lccode is both nonzero, and - % not equal to itself. - % Otherwise, we assume it's a number. - % - % We need the \relax at the end of the \ifnum lines to stop TeX from - % continuing to look for a <number>. - % - \ifnum\lccode\expandafter`\thearg=0\relax - \numericenumerate % a number (we hope) - \else - % It's a letter. - \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax - \lowercaseenumerate % lowercase letter - \else - \uppercaseenumerate % uppercase letter - \fi - \fi - \else - % Multiple tokens in the argument. We hope it's a number. - \numericenumerate - \fi -} - -% An @enumerate whose labels are integers. The starting integer is -% given in \thearg. -% -\def\numericenumerate{% - \itemno = \thearg - \startenumeration{\the\itemno}% -} - -% The starting (lowercase) letter is in \thearg. -\def\lowercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more lowercase letters in @enumerate; get a bigger - alphabet}% - \fi - \char\lccode\itemno - }% -} - -% The starting (uppercase) letter is in \thearg. -\def\uppercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more uppercase letters in @enumerate; get a bigger - alphabet} - \fi - \char\uccode\itemno - }% -} - -% Call \doitemize, adding a period to the first argument and supplying the -% common last two arguments. Also subtract one from the initial value in -% \itemno, since @item increments \itemno. -% -\def\startenumeration#1{% - \advance\itemno by -1 - \doitemize{#1.}\flushcr -} - -% @alphaenumerate and @capsenumerate are abbreviations for giving an arg -% to @enumerate. -% -\def\alphaenumerate{\enumerate{a}} -\def\capsenumerate{\enumerate{A}} -\def\Ealphaenumerate{\Eenumerate} -\def\Ecapsenumerate{\Eenumerate} - - -% @multitable macros -% Amy Hendrickson, 8/18/94, 3/6/96 -% -% @multitable ... @end multitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width -% can be specified either with sample text given in a template line, -% or in percent of \hsize, the current width of text on page. - -% Table can continue over pages but will only break between lines. - -% To make preamble: -% -% Either define widths of columns in terms of percent of \hsize: -% @multitable @columnfractions .25 .3 .45 -% @item ... -% -% Numbers following @columnfractions are the percent of the total -% current hsize to be used for each column. You may use as many -% columns as desired. - - -% Or use a template: -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item ... -% using the widest term desired in each column. - -% Each new table line starts with @item, each subsequent new column -% starts with @tab. Empty columns may be produced by supplying @tab's -% with nothing between them for as many times as empty columns are needed, -% ie, @tab@tab@tab will produce two empty columns. - -% @item, @tab do not need to be on their own lines, but it will not hurt -% if they are. - -% Sample multitable: - -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff -% @tab Many paragraphs of text may be used in any column. -% -% They will wrap at the width determined by the template. -% @item@tab@tab This will be in third column. -% @end multitable - -% Default dimensions may be reset by user. -% @multitableparskip is vertical space between paragraphs in table. -% @multitableparindent is paragraph indent in table. -% @multitablecolmargin is horizontal space to be left between columns. -% @multitablelinespace is space to leave between table items, baseline -% to baseline. -% 0pt means it depends on current normal line spacing. -% -\newskip\multitableparskip -\newskip\multitableparindent -\newdimen\multitablecolspace -\newskip\multitablelinespace -\multitableparskip=0pt -\multitableparindent=6pt -\multitablecolspace=12pt -\multitablelinespace=0pt - -% Macros used to set up halign preamble: -% -\let\endsetuptable\relax -\def\xendsetuptable{\endsetuptable} -\let\columnfractions\relax -\def\xcolumnfractions{\columnfractions} -\newif\ifsetpercent - -% #1 is the @columnfraction, usually a decimal number like .5, but might -% be just 1. We just use it, whatever it is. -% -\def\pickupwholefraction#1 {% - \global\advance\colcount by 1 - \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% - \setuptable -} - -\newcount\colcount -\def\setuptable#1{% - \def\firstarg{#1}% - \ifx\firstarg\xendsetuptable - \let\go = \relax - \else - \ifx\firstarg\xcolumnfractions - \global\setpercenttrue - \else - \ifsetpercent - \let\go\pickupwholefraction - \else - \global\advance\colcount by 1 - \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a - % separator; typically that is always in the input, anyway. - \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% - \fi - \fi - \ifx\go\pickupwholefraction - % Put the argument back for the \pickupwholefraction call, so - % we'll always have a period there to be parsed. - \def\go{\pickupwholefraction#1}% - \else - \let\go = \setuptable - \fi% - \fi - \go -} - -% multitable-only commands. -% -% @headitem starts a heading row, which we typeset in bold. -% Assignments have to be global since we are inside the implicit group -% of an alignment entry. Note that \everycr resets \everytab. -\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}% -% -% A \tab used to include \hskip1sp. But then the space in a template -% line is not enough. That is bad. So let's go back to just `&' until -% we encounter the problem it was intended to solve again. -% --karl, nathan@acm.org, 20apr99. -\def\tab{\checkenv\multitable &\the\everytab}% - -% @multitable ... @end multitable definitions: -% -\newtoks\everytab % insert after every tab. -% -\envdef\multitable{% - \vskip\parskip - \startsavinginserts - % - % @item within a multitable starts a normal row. - % We use \def instead of \let so that if one of the multitable entries - % contains an @itemize, we don't choke on the \item (seen as \crcr aka - % \endtemplate) expanding \doitemize. - \def\item{\crcr}% - % - \tolerance=9500 - \hbadness=9500 - \setmultitablespacing - \parskip=\multitableparskip - \parindent=\multitableparindent - \overfullrule=0pt - \global\colcount=0 - % - \everycr = {% - \noalign{% - \global\everytab={}% - \global\colcount=0 % Reset the column counter. - % Check for saved footnotes, etc. - \checkinserts - % Keeps underfull box messages off when table breaks over pages. - %\filbreak - % Maybe so, but it also creates really weird page breaks when the - % table breaks over pages. Wouldn't \vfil be better? Wait until the - % problem manifests itself, so it can be fixed for real --karl. - }% - }% - % - \parsearg\domultitable -} -\def\domultitable#1{% - % To parse everything between @multitable and @item: - \setuptable#1 \endsetuptable - % - % This preamble sets up a generic column definition, which will - % be used as many times as user calls for columns. - % \vtop will set a single line and will also let text wrap and - % continue for many paragraphs if desired. - \halign\bgroup &% - \global\advance\colcount by 1 - \multistrut - \vtop{% - % Use the current \colcount to find the correct column width: - \hsize=\expandafter\csname col\the\colcount\endcsname - % - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % - % If the user has set preamble in terms of percent of \hsize we will - % use that dimension as the width of the column, and the \leftskip - % will keep entries from bumping into each other. Table will start at - % left margin and final column will justify at right margin. - % - % Make sure we don't inherit \rightskip from the outer environment. - \rightskip=0pt - \ifnum\colcount=1 - % The first column will be indented with the surrounding text. - \advance\hsize by\leftskip - \else - \ifsetpercent \else - % If user has not set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace. - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: - \leftskip=\multitablecolspace - \fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighting sequences respectively - % marking characters. - \noindent\ignorespaces##\unskip\multistrut - }\cr -} -\def\Emultitable{% - \crcr - \egroup % end the \halign - \global\setpercentfalse -} - -\def\setmultitablespacing{% - \def\multistrut{\strut}% just use the standard line spacing - % - % Compute \multitablelinespace (if not defined by user) for use in - % \multitableparskip calculation. We used define \multistrut based on - % this, but (ironically) that caused the spacing to be off. - % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. -\ifdim\multitablelinespace=0pt -\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip -\global\advance\multitablelinespace by-\ht0 -\fi -%% Test to see if parskip is larger than space between lines of -%% table. If not, do nothing. -%% If so, set to same dimension as multitablelinespace. -\ifdim\multitableparskip>\multitablelinespace -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi% -\ifdim\multitableparskip=0pt -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi} - - -\message{conditionals,} - -% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, -% @ifnotxml always succeed. They currently do nothing; we don't -% attempt to check whether the conditionals are properly nested. But we -% have to remember that they are conditionals, so that @end doesn't -% attempt to close an environment group. -% -\def\makecond#1{% - \expandafter\let\csname #1\endcsname = \relax - \expandafter\let\csname iscond.#1\endcsname = 1 -} -\makecond{iftex} -\makecond{ifnotdocbook} -\makecond{ifnothtml} -\makecond{ifnotinfo} -\makecond{ifnotplaintext} -\makecond{ifnotxml} - -% Ignore @ignore, @ifhtml, @ifinfo, and the like. -% -\def\direntry{\doignore{direntry}} -\def\documentdescription{\doignore{documentdescription}} -\def\docbook{\doignore{docbook}} -\def\html{\doignore{html}} -\def\ifdocbook{\doignore{ifdocbook}} -\def\ifhtml{\doignore{ifhtml}} -\def\ifinfo{\doignore{ifinfo}} -\def\ifnottex{\doignore{ifnottex}} -\def\ifplaintext{\doignore{ifplaintext}} -\def\ifxml{\doignore{ifxml}} -\def\ignore{\doignore{ignore}} -\def\menu{\doignore{menu}} -\def\xml{\doignore{xml}} - -% Ignore text until a line `@end #1', keeping track of nested conditionals. -% -% A count to remember the depth of nesting. -\newcount\doignorecount - -\def\doignore#1{\begingroup - % Scan in ``verbatim'' mode: - \obeylines - \catcode`\@ = \other - \catcode`\{ = \other - \catcode`\} = \other - % - % Make sure that spaces turn into tokens that match what \doignoretext wants. - \spaceisspace - % - % Count number of #1's that we've seen. - \doignorecount = 0 - % - % Swallow text until we reach the matching `@end #1'. - \dodoignore{#1}% -} - -{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. - \obeylines % - % - \gdef\dodoignore#1{% - % #1 contains the command name as a string, e.g., `ifinfo'. - % - % Define a command to find the next `@end #1'. - \long\def\doignoretext##1^^M@end #1{% - \doignoretextyyy##1^^M@#1\_STOP_}% - % - % And this command to find another #1 command, at the beginning of a - % line. (Otherwise, we would consider a line `@c @ifset', for - % example, to count as an @ifset for nesting.) - \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% - % - % And now expand that command. - \doignoretext ^^M% - }% -} - -\def\doignoreyyy#1{% - \def\temp{#1}% - \ifx\temp\empty % Nothing found. - \let\next\doignoretextzzz - \else % Found a nested condition, ... - \advance\doignorecount by 1 - \let\next\doignoretextyyy % ..., look for another. - % If we're here, #1 ends with ^^M\ifinfo (for example). - \fi - \next #1% the token \_STOP_ is present just after this macro. -} - -% We have to swallow the remaining "\_STOP_". -% -\def\doignoretextzzz#1{% - \ifnum\doignorecount = 0 % We have just found the outermost @end. - \let\next\enddoignore - \else % Still inside a nested condition. - \advance\doignorecount by -1 - \let\next\doignoretext % Look for the next @end. - \fi - \next -} - -% Finish off ignored text. -{ \obeylines% - % Ignore anything after the last `@end #1'; this matters in verbatim - % environments, where otherwise the newline after an ignored conditional - % would result in a blank line in the output. - \gdef\enddoignore#1^^M{\endgroup\ignorespaces}% -} - - -% @set VAR sets the variable VAR to an empty value. -% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. -% -% Since we want to separate VAR from REST-OF-LINE (which might be -% empty), we can't just use \parsearg; we have to insert a space of our -% own to delimit the rest of the line, and then take it out again if we -% didn't need it. -% We rely on the fact that \parsearg sets \catcode`\ =10. -% -\parseargdef\set{\setyyy#1 \endsetyyy} -\def\setyyy#1 #2\endsetyyy{% - {% - \makevalueexpandable - \def\temp{#2}% - \edef\next{\gdef\makecsname{SET#1}}% - \ifx\temp\empty - \next{}% - \else - \setzzz#2\endsetzzz - \fi - }% -} -% Remove the trailing space \setxxx inserted. -\def\setzzz#1 \endsetzzz{\next{#1}} - -% @clear VAR clears (i.e., unsets) the variable VAR. -% -\parseargdef\clear{% - {% - \makevalueexpandable - \global\expandafter\let\csname SET#1\endcsname=\relax - }% -} - -% @value{foo} gets the text saved in variable foo. -\def\value{\begingroup\makevalueexpandable\valuexxx} -\def\valuexxx#1{\expandablevalue{#1}\endgroup} -{ - \catcode`\- = \active \catcode`\_ = \active - % - \gdef\makevalueexpandable{% - \let\value = \expandablevalue - % We don't want these characters active, ... - \catcode`\-=\other \catcode`\_=\other - % ..., but we might end up with active ones in the argument if - % we're called from @code, as @code{@value{foo-bar_}}, though. - % So \let them to their normal equivalents. - \let-\realdash \let_\normalunderscore - } -} - -% We have this subroutine so that we can handle at least some @value's -% properly in indexes (we call \makevalueexpandable in \indexdummies). -% The command has to be fully expandable (if the variable is set), since -% the result winds up in the index file. This means that if the -% variable's value contains other Texinfo commands, it's almost certain -% it will fail (although perhaps we could fix that with sufficient work -% to do a one-level expansion on the result, instead of complete). -% -\def\expandablevalue#1{% - \expandafter\ifx\csname SET#1\endcsname\relax - {[No value for ``#1'']}% - \message{Variable `#1', used in @value, is not set.}% - \else - \csname SET#1\endcsname - \fi -} - -% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined -% with @set. -% -% To get special treatment of `@end ifset,' call \makeond and the redefine. -% -\makecond{ifset} -\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} -\def\doifset#1#2{% - {% - \makevalueexpandable - \let\next=\empty - \expandafter\ifx\csname SET#2\endcsname\relax - #1% If not set, redefine \next. - \fi - \expandafter - }\next -} -\def\ifsetfail{\doignore{ifset}} - -% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been -% defined with @set, or has been undefined with @clear. -% -% The `\else' inside the `\doifset' parameter is a trick to reuse the -% above code: if the variable is not set, do nothing, if it is set, -% then redefine \next to \ifclearfail. -% -\makecond{ifclear} -\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} -\def\ifclearfail{\doignore{ifclear}} - -% @dircategory CATEGORY -- specify a category of the dir file -% which this file should belong to. Ignore this in TeX. -\let\dircategory=\comment - -% @defininfoenclose. -\let\definfoenclose=\comment - - -\message{indexing,} -% Index generation facilities - -% Define \newwrite to be identical to plain tex's \newwrite -% except not \outer, so it can be used within macros and \if's. -\edef\newwrite{\makecsname{ptexnewwrite}} - -% \newindex {foo} defines an index named foo. -% It automatically defines \fooindex such that -% \fooindex ...rest of line... puts an entry in the index foo. -% It also defines \fooindfile to be the number of the output channel for -% the file that accumulates this index. The file's extension is foo. -% The name of an index should be no more than 2 characters long -% for the sake of vms. -% -\def\newindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 % Open the file - \fi - \expandafter\xdef\csname#1index\endcsname{% % Define @#1index - \noexpand\doindex{#1}} -} - -% @defindex foo == \newindex{foo} -% -\def\defindex{\parsearg\newindex} - -% Define @defcodeindex, like @defindex except put all entries in @code. -% -\def\defcodeindex{\parsearg\newcodeindex} -% -\def\newcodeindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 - \fi - \expandafter\xdef\csname#1index\endcsname{% - \noexpand\docodeindex{#1}}% -} - - -% @synindex foo bar makes index foo feed into index bar. -% Do this instead of @defindex foo if you don't want it as a separate index. -% -% @syncodeindex foo bar similar, but put all entries made for index foo -% inside @code. -% -\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} -\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} - -% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), -% #3 the target index (bar). -\def\dosynindex#1#2#3{% - % Only do \closeout if we haven't already done it, else we'll end up - % closing the target index. - \expandafter \ifx\csname donesynindex#2\endcsname \undefined - % The \closeout helps reduce unnecessary open files; the limit on the - % Acorn RISC OS is a mere 16 files. - \expandafter\closeout\csname#2indfile\endcsname - \expandafter\let\csname\donesynindex#2\endcsname = 1 - \fi - % redefine \fooindfile: - \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname - \expandafter\let\csname#2indfile\endcsname=\temp - % redefine \fooindex: - \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% -} - -% Define \doindex, the driver for all \fooindex macros. -% Argument #1 is generated by the calling \fooindex macro, -% and it is "foo", the name of the index. - -% \doindex just uses \parsearg; it calls \doind for the actual work. -% This is because \doind is more useful to call from other macros. - -% There is also \dosubind {index}{topic}{subtopic} -% which makes an entry in a two-level index such as the operation index. - -\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} -\def\singleindexer #1{\doind{\indexname}{#1}} - -% like the previous two, but they put @code around the argument. -\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} -\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} - -% Take care of Texinfo commands that can appear in an index entry. -% Since there are some commands we want to expand, and others we don't, -% we have to laboriously prevent expansion for those that we don't. -% -\def\indexdummies{% - \escapechar = `\\ % use backslash in output files. - \def\@{@}% change to @@ when we switch to @ as escape char in index files. - \def\ {\realbackslash\space }% - % - % Need these in case \tex is in effect and \{ is a \delimiter again. - % But can't use \lbracecmd and \rbracecmd because texindex assumes - % braces and backslashes are used only as delimiters. - \let\{ = \mylbrace - \let\} = \myrbrace - % - % I don't entirely understand this, but when an index entry is - % generated from a macro call, the \endinput which \scanmacro inserts - % causes processing to be prematurely terminated. This is, - % apparently, because \indexsorttmp is fully expanded, and \endinput - % is an expandable command. The redefinition below makes \endinput - % disappear altogether for that purpose -- although logging shows that - % processing continues to some further point. On the other hand, it - % seems \endinput does not hurt in the printed index arg, since that - % is still getting written without apparent harm. - % - % Sample source (mac-idx3.tex, reported by Graham Percival to - % help-texinfo, 22may06): - % @macro funindex {WORD} - % @findex xyz - % @end macro - % ... - % @funindex commtest - % - % The above is not enough to reproduce the bug, but it gives the flavor. - % - % Sample whatsit resulting: - % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} - % - % So: - \let\endinput = \empty - % - % Do the redefinitions. - \commondummies -} - -% For the aux and toc files, @ is the escape character. So we want to -% redefine everything using @ as the escape character (instead of -% \realbackslash, still used for index files). When everything uses @, -% this will be simpler. -% -\def\atdummies{% - \def\@{@@}% - \def\ {@ }% - \let\{ = \lbraceatcmd - \let\} = \rbraceatcmd - % - % Do the redefinitions. - \commondummies - \otherbackslash -} - -% Called from \indexdummies and \atdummies. -% -\def\commondummies{% - % - % \definedummyword defines \#1 as \string\#1\space, thus effectively - % preventing its expansion. This is used only for control% words, - % not control letters, because the \space would be incorrect for - % control characters, but is needed to separate the control word - % from whatever follows. - % - % For control letters, we have \definedummyletter, which omits the - % space. - % - % These can be used both for control words that take an argument and - % those that do not. If it is followed by {arg} in the input, then - % that will dutifully get written to the index (or wherever). - % - \def\definedummyword ##1{\def##1{\string##1\space}}% - \def\definedummyletter##1{\def##1{\string##1}}% - \let\definedummyaccent\definedummyletter - % - \commondummiesnofonts - % - \definedummyletter\_% - % - % Non-English letters. - \definedummyword\AA - \definedummyword\AE - \definedummyword\L - \definedummyword\OE - \definedummyword\O - \definedummyword\aa - \definedummyword\ae - \definedummyword\l - \definedummyword\oe - \definedummyword\o - \definedummyword\ss - \definedummyword\exclamdown - \definedummyword\questiondown - \definedummyword\ordf - \definedummyword\ordm - % - % Although these internal commands shouldn't show up, sometimes they do. - \definedummyword\bf - \definedummyword\gtr - \definedummyword\hat - \definedummyword\less - \definedummyword\sf - \definedummyword\sl - \definedummyword\tclose - \definedummyword\tt - % - \definedummyword\LaTeX - \definedummyword\TeX - % - % Assorted special characters. - \definedummyword\bullet - \definedummyword\comma - \definedummyword\copyright - \definedummyword\registeredsymbol - \definedummyword\dots - \definedummyword\enddots - \definedummyword\equiv - \definedummyword\error - \definedummyword\euro - \definedummyword\guillemetleft - \definedummyword\guillemetright - \definedummyword\guilsinglleft - \definedummyword\guilsinglright - \definedummyword\expansion - \definedummyword\minus - \definedummyword\pounds - \definedummyword\point - \definedummyword\print - \definedummyword\quotedblbase - \definedummyword\quotedblleft - \definedummyword\quotedblright - \definedummyword\quoteleft - \definedummyword\quoteright - \definedummyword\quotesinglbase - \definedummyword\result - \definedummyword\textdegree - % - % We want to disable all macros so that they are not expanded by \write. - \macrolist - % - \normalturnoffactive - % - % Handle some cases of @value -- where it does not contain any - % (non-fully-expandable) commands. - \makevalueexpandable -} - -% \commondummiesnofonts: common to \commondummies and \indexnofonts. -% -\def\commondummiesnofonts{% - % Control letters and accents. - \definedummyletter\!% - \definedummyaccent\"% - \definedummyaccent\'% - \definedummyletter\*% - \definedummyaccent\,% - \definedummyletter\.% - \definedummyletter\/% - \definedummyletter\:% - \definedummyaccent\=% - \definedummyletter\?% - \definedummyaccent\^% - \definedummyaccent\`% - \definedummyaccent\~% - \definedummyword\u - \definedummyword\v - \definedummyword\H - \definedummyword\dotaccent - \definedummyword\ringaccent - \definedummyword\tieaccent - \definedummyword\ubaraccent - \definedummyword\udotaccent - \definedummyword\dotless - % - % Texinfo font commands. - \definedummyword\b - \definedummyword\i - \definedummyword\r - \definedummyword\sc - \definedummyword\t - % - % Commands that take arguments. - \definedummyword\acronym - \definedummyword\cite - \definedummyword\code - \definedummyword\command - \definedummyword\dfn - \definedummyword\emph - \definedummyword\env - \definedummyword\file - \definedummyword\kbd - \definedummyword\key - \definedummyword\math - \definedummyword\option - \definedummyword\pxref - \definedummyword\ref - \definedummyword\samp - \definedummyword\strong - \definedummyword\tie - \definedummyword\uref - \definedummyword\url - \definedummyword\var - \definedummyword\verb - \definedummyword\w - \definedummyword\xref -} - -% \indexnofonts is used when outputting the strings to sort the index -% by, and when constructing control sequence names. It eliminates all -% control sequences and just writes whatever the best ASCII sort string -% would be for a given command (usually its argument). -% -\def\indexnofonts{% - % Accent commands should become @asis. - \def\definedummyaccent##1{\let##1\asis}% - % We can just ignore other control letters. - \def\definedummyletter##1{\let##1\empty}% - % Hopefully, all control words can become @asis. - \let\definedummyword\definedummyaccent - % - \commondummiesnofonts - % - % Don't no-op \tt, since it isn't a user-level command - % and is used in the definitions of the active chars like <, >, |, etc. - % Likewise with the other plain tex font commands. - %\let\tt=\asis - % - \def\ { }% - \def\@{@}% - % how to handle braces? - \def\_{\normalunderscore}% - % - % Non-English letters. - \def\AA{AA}% - \def\AE{AE}% - \def\L{L}% - \def\OE{OE}% - \def\O{O}% - \def\aa{aa}% - \def\ae{ae}% - \def\l{l}% - \def\oe{oe}% - \def\o{o}% - \def\ss{ss}% - \def\exclamdown{!}% - \def\questiondown{?}% - \def\ordf{a}% - \def\ordm{o}% - % - \def\LaTeX{LaTeX}% - \def\TeX{TeX}% - % - % Assorted special characters. - % (The following {} will end up in the sort string, but that's ok.) - \def\bullet{bullet}% - \def\comma{,}% - \def\copyright{copyright}% - \def\registeredsymbol{R}% - \def\dots{...}% - \def\enddots{...}% - \def\equiv{==}% - \def\error{error}% - \def\euro{euro}% - \def\guillemetleft{<<}% - \def\guillemetright{>>}% - \def\guilsinglleft{<}% - \def\guilsinglright{>}% - \def\expansion{==>}% - \def\minus{-}% - \def\pounds{pounds}% - \def\point{.}% - \def\print{-|}% - \def\quotedblbase{"}% - \def\quotedblleft{"}% - \def\quotedblright{"}% - \def\quoteleft{`}% - \def\quoteright{'}% - \def\quotesinglbase{,}% - \def\result{=>}% - \def\textdegree{degrees}% - % - % We need to get rid of all macros, leaving only the arguments (if present). - % Of course this is not nearly correct, but it is the best we can do for now. - % makeinfo does not expand macros in the argument to @deffn, which ends up - % writing an index entry, and texindex isn't prepared for an index sort entry - % that starts with \. - % - % Since macro invocations are followed by braces, we can just redefine them - % to take a single TeX argument. The case of a macro invocation that - % goes to end-of-line is not handled. - % - \macrolist -} - -\let\indexbackslash=0 %overridden during \printindex. -\let\SETmarginindex=\relax % put index entries in margin (undocumented)? - -% Most index entries go through here, but \dosubind is the general case. -% #1 is the index name, #2 is the entry text. -\def\doind#1#2{\dosubind{#1}{#2}{}} - -% Workhorse for all \fooindexes. -% #1 is name of index, #2 is stuff to put there, #3 is subentry -- -% empty if called from \doind, as we usually are (the main exception -% is with most defuns, which call us directly). -% -\def\dosubind#1#2#3{% - \iflinks - {% - % Store the main index entry text (including the third arg). - \toks0 = {#2}% - % If third arg is present, precede it with a space. - \def\thirdarg{#3}% - \ifx\thirdarg\empty \else - \toks0 = \expandafter{\the\toks0 \space #3}% - \fi - % - \edef\writeto{\csname#1indfile\endcsname}% - % - \safewhatsit\dosubindwrite - }% - \fi -} - -% Write the entry in \toks0 to the index file: -% -\def\dosubindwrite{% - % Put the index entry in the margin if desired. - \ifx\SETmarginindex\relax\else - \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% - \fi - % - % Remember, we are within a group. - \indexdummies % Must do this here, since \bf, etc expand at this stage - \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now - % so it will be output as is; and it will print as backslash. - % - % Process the index entry with all font commands turned off, to - % get the string to sort by. - {\indexnofonts - \edef\temp{\the\toks0}% need full expansion - \xdef\indexsorttmp{\temp}% - }% - % - % Set up the complete index entry, with both the sort key and - % the original text, including any font commands. We write - % three arguments to \entry to the .?? file (four in the - % subentry case), texindex reduces to two when writing the .??s - % sorted result. - \edef\temp{% - \write\writeto{% - \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% - }% - \temp -} - -% Take care of unwanted page breaks/skips around a whatsit: -% -% If a skip is the last thing on the list now, preserve it -% by backing up by \lastskip, doing the \write, then inserting -% the skip again. Otherwise, the whatsit generated by the -% \write or \pdfdest will make \lastskip zero. The result is that -% sequences like this: -% @end defun -% @tindex whatever -% @defun ... -% will have extra space inserted, because the \medbreak in the -% start of the @defun won't see the skip inserted by the @end of -% the previous defun. -% -% But don't do any of this if we're not in vertical mode. We -% don't want to do a \vskip and prematurely end a paragraph. -% -% Avoid page breaks due to these extra skips, too. -% -% But wait, there is a catch there: -% We'll have to check whether \lastskip is zero skip. \ifdim is not -% sufficient for this purpose, as it ignores stretch and shrink parts -% of the skip. The only way seems to be to check the textual -% representation of the skip. -% -% The following is almost like \def\zeroskipmacro{0.0pt} except that -% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). -% -\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} -% -\newskip\whatsitskip -\newcount\whatsitpenalty -% -% ..., ready, GO: -% -\def\safewhatsit#1{% -\ifhmode - #1% -\else - % \lastskip and \lastpenalty cannot both be nonzero simultaneously. - \whatsitskip = \lastskip - \edef\lastskipmacro{\the\lastskip}% - \whatsitpenalty = \lastpenalty - % - % If \lastskip is nonzero, that means the last item was a - % skip. And since a skip is discardable, that means this - % -\whatsitskip glue we're inserting is preceded by a - % non-discardable item, therefore it is not a potential - % breakpoint, therefore no \nobreak needed. - \ifx\lastskipmacro\zeroskipmacro - \else - \vskip-\whatsitskip - \fi - % - #1% - % - \ifx\lastskipmacro\zeroskipmacro - % If \lastskip was zero, perhaps the last item was a penalty, and - % perhaps it was >=10000, e.g., a \nobreak. In that case, we want - % to re-insert the same penalty (values >10000 are used for various - % signals); since we just inserted a non-discardable item, any - % following glue (such as a \parskip) would be a breakpoint. For example: - % - % @deffn deffn-whatever - % @vindex index-whatever - % Description. - % would allow a break between the index-whatever whatsit - % and the "Description." paragraph. - \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi - \else - % On the other hand, if we had a nonzero \lastskip, - % this make-up glue would be preceded by a non-discardable item - % (the whatsit from the \write), so we must insert a \nobreak. - \nobreak\vskip\whatsitskip - \fi -\fi -} - -% The index entry written in the file actually looks like -% \entry {sortstring}{page}{topic} -% or -% \entry {sortstring}{page}{topic}{subtopic} -% The texindex program reads in these files and writes files -% containing these kinds of lines: -% \initial {c} -% before the first topic whose initial is c -% \entry {topic}{pagelist} -% for a topic that is used without subtopics -% \primary {topic} -% for the beginning of a topic that is used with subtopics -% \secondary {subtopic}{pagelist} -% for each subtopic. - -% Define the user-accessible indexing commands -% @findex, @vindex, @kindex, @cindex. - -\def\findex {\fnindex} -\def\kindex {\kyindex} -\def\cindex {\cpindex} -\def\vindex {\vrindex} -\def\tindex {\tpindex} -\def\pindex {\pgindex} - -\def\cindexsub {\begingroup\obeylines\cindexsub} -{\obeylines % -\gdef\cindexsub "#1" #2^^M{\endgroup % -\dosubind{cp}{#2}{#1}}} - -% Define the macros used in formatting output of the sorted index material. - -% @printindex causes a particular index (the ??s file) to get printed. -% It does not print any chapter heading (usually an @unnumbered). -% -\parseargdef\printindex{\begingroup - \dobreak \chapheadingskip{10000}% - % - \smallfonts \rm - \tolerance = 9500 - \plainfrenchspacing - \everypar = {}% don't want the \kern\-parindent from indentation suppression. - % - % See if the index file exists and is nonempty. - % Change catcode of @ here so that if the index file contains - % \initial {@} - % as its first line, TeX doesn't complain about mismatched braces - % (because it thinks @} is a control sequence). - \catcode`\@ = 11 - \openin 1 \jobname.#1s - \ifeof 1 - % \enddoublecolumns gets confused if there is no text in the index, - % and it loses the chapter title and the aux file entries for the - % index. The easiest way to prevent this problem is to make sure - % there is some text. - \putwordIndexNonexistent - \else - % - % If the index file exists but is empty, then \openin leaves \ifeof - % false. We have to make TeX try to read something from the file, so - % it can discover if there is anything in it. - \read 1 to \temp - \ifeof 1 - \putwordIndexIsEmpty - \else - % Index files are almost Texinfo source, but we use \ as the escape - % character. It would be better to use @, but that's too big a change - % to make right now. - \def\indexbackslash{\backslashcurfont}% - \catcode`\\ = 0 - \escapechar = `\\ - \begindoublecolumns - \input \jobname.#1s - \enddoublecolumns - \fi - \fi - \closein 1 -\endgroup} - -% These macros are used by the sorted index file itself. -% Change them to control the appearance of the index. - -\def\initial#1{{% - % Some minor font changes for the special characters. - \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt - % - % Remove any glue we may have, we'll be inserting our own. - \removelastskip - % - % We like breaks before the index initials, so insert a bonus. - \nobreak - \vskip 0pt plus 3\baselineskip - \penalty 0 - \vskip 0pt plus -3\baselineskip - % - % Typeset the initial. Making this add up to a whole number of - % baselineskips increases the chance of the dots lining up from column - % to column. It still won't often be perfect, because of the stretch - % we need before each entry, but it's better. - % - % No shrink because it confuses \balancecolumns. - \vskip 1.67\baselineskip plus .5\baselineskip - \leftline{\secbf #1}% - % Do our best not to break after the initial. - \nobreak - \vskip .33\baselineskip plus .1\baselineskip -}} - -% \entry typesets a paragraph consisting of the text (#1), dot leaders, and -% then page number (#2) flushed to the right margin. It is used for index -% and table of contents entries. The paragraph is indented by \leftskip. -% -% A straightforward implementation would start like this: -% \def\entry#1#2{... -% But this freezes the catcodes in the argument, and can cause problems to -% @code, which sets - active. This problem was fixed by a kludge--- -% ``-'' was active throughout whole index, but this isn't really right. -% -% The right solution is to prevent \entry from swallowing the whole text. -% --kasal, 21nov03 -\def\entry{% - \begingroup - % - % Start a new paragraph if necessary, so our assignments below can't - % affect previous text. - \par - % - % Do not fill out the last line with white space. - \parfillskip = 0in - % - % No extra space above this paragraph. - \parskip = 0in - % - % Do not prefer a separate line ending with a hyphen to fewer lines. - \finalhyphendemerits = 0 - % - % \hangindent is only relevant when the entry text and page number - % don't both fit on one line. In that case, bob suggests starting the - % dots pretty far over on the line. Unfortunately, a large - % indentation looks wrong when the entry text itself is broken across - % lines. So we use a small indentation and put up with long leaders. - % - % \hangafter is reset to 1 (which is the value we want) at the start - % of each paragraph, so we need not do anything with that. - \hangindent = 2em - % - % When the entry text needs to be broken, just fill out the first line - % with blank space. - \rightskip = 0pt plus1fil - % - % A bit of stretch before each entry for the benefit of balancing - % columns. - \vskip 0pt plus1pt - % - % Swallow the left brace of the text (first parameter): - \afterassignment\doentry - \let\temp = -} -\def\doentry{% - \bgroup % Instead of the swallowed brace. - \noindent - \aftergroup\finishentry - % And now comes the text of the entry. -} -\def\finishentry#1{% - % #1 is the page number. - % - % The following is kludged to not output a line of dots in the index if - % there are no page numbers. The next person who breaks this will be - % cursed by a Unix daemon. - \setbox\boxA = \hbox{#1}% - \ifdim\wd\boxA = 0pt - \ % - \else - % - % If we must, put the page number on a line of its own, and fill out - % this line with blank space. (The \hfil is overwhelmed with the - % fill leaders glue in \indexdotfill if the page number does fit.) - \hfil\penalty50 - \null\nobreak\indexdotfill % Have leaders before the page number. - % - % The `\ ' here is removed by the implicit \unskip that TeX does as - % part of (the primitive) \par. Without it, a spurious underfull - % \hbox ensues. - \ifpdf - \pdfgettoks#1.% - \ \the\toksA - \else - \ #1% - \fi - \fi - \par - \endgroup -} - -% Like plain.tex's \dotfill, except uses up at least 1 em. -\def\indexdotfill{\cleaders - \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} - -\def\primary #1{\line{#1\hfil}} - -\newskip\secondaryindent \secondaryindent=0.5cm -\def\secondary#1#2{{% - \parfillskip=0in - \parskip=0in - \hangindent=1in - \hangafter=1 - \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill - \ifpdf - \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. - \else - #2 - \fi - \par -}} - -% Define two-column mode, which we use to typeset indexes. -% Adapted from the TeXbook, page 416, which is to say, -% the manmac.tex format used to print the TeXbook itself. -\catcode`\@=11 - -\newbox\partialpage -\newdimen\doublecolumnhsize - -\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns - % Grab any single-column material above us. - \output = {% - % - % Here is a possibility not foreseen in manmac: if we accumulate a - % whole lot of material, we might end up calling this \output - % routine twice in a row (see the doublecol-lose test, which is - % essentially a couple of indexes with @setchapternewpage off). In - % that case we just ship out what is in \partialpage with the normal - % output routine. Generally, \partialpage will be empty when this - % runs and this will be a no-op. See the indexspread.tex test case. - \ifvoid\partialpage \else - \onepageout{\pagecontents\partialpage}% - \fi - % - \global\setbox\partialpage = \vbox{% - % Unvbox the main output page. - \unvbox\PAGE - \kern-\topskip \kern\baselineskip - }% - }% - \eject % run that output routine to set \partialpage - % - % Use the double-column output routine for subsequent pages. - \output = {\doublecolumnout}% - % - % Change the page size parameters. We could do this once outside this - % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 - % format, but then we repeat the same computation. Repeating a couple - % of assignments once per index is clearly meaningless for the - % execution time, so we may as well do it in one place. - % - % First we halve the line length, less a little for the gutter between - % the columns. We compute the gutter based on the line length, so it - % changes automatically with the paper format. The magic constant - % below is chosen so that the gutter has the same value (well, +-<1pt) - % as it did when we hard-coded it. - % - % We put the result in a separate register, \doublecolumhsize, so we - % can restore it in \pagesofar, after \hsize itself has (potentially) - % been clobbered. - % - \doublecolumnhsize = \hsize - \advance\doublecolumnhsize by -.04154\hsize - \divide\doublecolumnhsize by 2 - \hsize = \doublecolumnhsize - % - % Double the \vsize as well. (We don't need a separate register here, - % since nobody clobbers \vsize.) - \vsize = 2\vsize -} - -% The double-column output routine for all double-column pages except -% the last. -% -\def\doublecolumnout{% - \splittopskip=\topskip \splitmaxdepth=\maxdepth - % Get the available space for the double columns -- the normal - % (undoubled) page height minus any material left over from the - % previous page. - \dimen@ = \vsize - \divide\dimen@ by 2 - \advance\dimen@ by -\ht\partialpage - % - % box0 will be the left-hand column, box2 the right. - \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ - \onepageout\pagesofar - \unvbox255 - \penalty\outputpenalty -} -% -% Re-output the contents of the output page -- any previous material, -% followed by the two boxes we just split, in box0 and box2. -\def\pagesofar{% - \unvbox\partialpage - % - \hsize = \doublecolumnhsize - \wd0=\hsize \wd2=\hsize - \hbox to\pagewidth{\box0\hfil\box2}% -} -% -% All done with double columns. -\def\enddoublecolumns{% - % The following penalty ensures that the page builder is exercised - % _before_ we change the output routine. This is necessary in the - % following situation: - % - % The last section of the index consists only of a single entry. - % Before this section, \pagetotal is less than \pagegoal, so no - % break occurs before the last section starts. However, the last - % section, consisting of \initial and the single \entry, does not - % fit on the page and has to be broken off. Without the following - % penalty the page builder will not be exercised until \eject - % below, and by that time we'll already have changed the output - % routine to the \balancecolumns version, so the next-to-last - % double-column page will be processed with \balancecolumns, which - % is wrong: The two columns will go to the main vertical list, with - % the broken-off section in the recent contributions. As soon as - % the output routine finishes, TeX starts reconsidering the page - % break. The two columns and the broken-off section both fit on the - % page, because the two columns now take up only half of the page - % goal. When TeX sees \eject from below which follows the final - % section, it invokes the new output routine that we've set after - % \balancecolumns below; \onepageout will try to fit the two columns - % and the final section into the vbox of \pageheight (see - % \pagebody), causing an overfull box. - % - % Note that glue won't work here, because glue does not exercise the - % page builder, unlike penalties (see The TeXbook, pp. 280-281). - \penalty0 - % - \output = {% - % Split the last of the double-column material. Leave it on the - % current page, no automatic page break. - \balancecolumns - % - % If we end up splitting too much material for the current page, - % though, there will be another page break right after this \output - % invocation ends. Having called \balancecolumns once, we do not - % want to call it again. Therefore, reset \output to its normal - % definition right away. (We hope \balancecolumns will never be - % called on to balance too much material, but if it is, this makes - % the output somewhat more palatable.) - \global\output = {\onepageout{\pagecontents\PAGE}}% - }% - \eject - \endgroup % started in \begindoublecolumns - % - % \pagegoal was set to the doubled \vsize above, since we restarted - % the current page. We're now back to normal single-column - % typesetting, so reset \pagegoal to the normal \vsize (after the - % \endgroup where \vsize got restored). - \pagegoal = \vsize -} -% -% Called at the end of the double column material. -\def\balancecolumns{% - \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. - \dimen@ = \ht0 - \advance\dimen@ by \topskip - \advance\dimen@ by-\baselineskip - \divide\dimen@ by 2 % target to split to - %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% - \splittopskip = \topskip - % Loop until we get a decent breakpoint. - {% - \vbadness = 10000 - \loop - \global\setbox3 = \copy0 - \global\setbox1 = \vsplit3 to \dimen@ - \ifdim\ht3>\dimen@ - \global\advance\dimen@ by 1pt - \repeat - }% - %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% - \setbox0=\vbox to\dimen@{\unvbox1}% - \setbox2=\vbox to\dimen@{\unvbox3}% - % - \pagesofar -} -\catcode`\@ = \other - - -\message{sectioning,} -% Chapters, sections, etc. - -% \unnumberedno is an oxymoron, of course. But we count the unnumbered -% sections so that we can refer to them unambiguously in the pdf -% outlines by their "section number". We avoid collisions with chapter -% numbers by starting them at 10000. (If a document ever has 10000 -% chapters, we're in trouble anyway, I'm sure.) -\newcount\unnumberedno \unnumberedno = 10000 -\newcount\chapno -\newcount\secno \secno=0 -\newcount\subsecno \subsecno=0 -\newcount\subsubsecno \subsubsecno=0 - -% This counter is funny since it counts through charcodes of letters A, B, ... -\newcount\appendixno \appendixno = `\@ -% -% \def\appendixletter{\char\the\appendixno} -% We do the following ugly conditional instead of the above simple -% construct for the sake of pdftex, which needs the actual -% letter in the expansion, not just typeset. -% -\def\appendixletter{% - \ifnum\appendixno=`A A% - \else\ifnum\appendixno=`B B% - \else\ifnum\appendixno=`C C% - \else\ifnum\appendixno=`D D% - \else\ifnum\appendixno=`E E% - \else\ifnum\appendixno=`F F% - \else\ifnum\appendixno=`G G% - \else\ifnum\appendixno=`H H% - \else\ifnum\appendixno=`I I% - \else\ifnum\appendixno=`J J% - \else\ifnum\appendixno=`K K% - \else\ifnum\appendixno=`L L% - \else\ifnum\appendixno=`M M% - \else\ifnum\appendixno=`N N% - \else\ifnum\appendixno=`O O% - \else\ifnum\appendixno=`P P% - \else\ifnum\appendixno=`Q Q% - \else\ifnum\appendixno=`R R% - \else\ifnum\appendixno=`S S% - \else\ifnum\appendixno=`T T% - \else\ifnum\appendixno=`U U% - \else\ifnum\appendixno=`V V% - \else\ifnum\appendixno=`W W% - \else\ifnum\appendixno=`X X% - \else\ifnum\appendixno=`Y Y% - \else\ifnum\appendixno=`Z Z% - % The \the is necessary, despite appearances, because \appendixletter is - % expanded while writing the .toc file. \char\appendixno is not - % expandable, thus it is written literally, thus all appendixes come out - % with the same letter (or @) in the toc without it. - \else\char\the\appendixno - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} - -% Each @chapter defines these (using marks) as the number+name, number -% and name of the chapter. Page headings and footings can use -% these. @section does likewise. -\def\thischapter{} -\def\thischapternum{} -\def\thischaptername{} -\def\thissection{} -\def\thissectionnum{} -\def\thissectionname{} - -\newcount\absseclevel % used to calculate proper heading level -\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count - -% @raisesections: treat @section as chapter, @subsection as section, etc. -\def\raisesections{\global\advance\secbase by -1} -\let\up=\raisesections % original BFox name - -% @lowersections: treat @chapter as section, @section as subsection, etc. -\def\lowersections{\global\advance\secbase by 1} -\let\down=\lowersections % original BFox name - -% we only have subsub. -\chardef\maxseclevel = 3 -% -% A numbered section within an unnumbered changes to unnumbered too. -% To achive this, remember the "biggest" unnum. sec. we are currently in: -\chardef\unmlevel = \maxseclevel -% -% Trace whether the current chapter is an appendix or not: -% \chapheadtype is "N" or "A", unnumbered chapters are ignored. -\def\chapheadtype{N} - -% Choose a heading macro -% #1 is heading type -% #2 is heading level -% #3 is text for heading -\def\genhead#1#2#3{% - % Compute the abs. sec. level: - \absseclevel=#2 - \advance\absseclevel by \secbase - % Make sure \absseclevel doesn't fall outside the range: - \ifnum \absseclevel < 0 - \absseclevel = 0 - \else - \ifnum \absseclevel > 3 - \absseclevel = 3 - \fi - \fi - % The heading type: - \def\headtype{#1}% - \if \headtype U% - \ifnum \absseclevel < \unmlevel - \chardef\unmlevel = \absseclevel - \fi - \else - % Check for appendix sections: - \ifnum \absseclevel = 0 - \edef\chapheadtype{\headtype}% - \else - \if \headtype A\if \chapheadtype N% - \errmessage{@appendix... within a non-appendix chapter}% - \fi\fi - \fi - % Check for numbered within unnumbered: - \ifnum \absseclevel > \unmlevel - \def\headtype{U}% - \else - \chardef\unmlevel = 3 - \fi - \fi - % Now print the heading: - \if \headtype U% - \ifcase\absseclevel - \unnumberedzzz{#3}% - \or \unnumberedseczzz{#3}% - \or \unnumberedsubseczzz{#3}% - \or \unnumberedsubsubseczzz{#3}% - \fi - \else - \if \headtype A% - \ifcase\absseclevel - \appendixzzz{#3}% - \or \appendixsectionzzz{#3}% - \or \appendixsubseczzz{#3}% - \or \appendixsubsubseczzz{#3}% - \fi - \else - \ifcase\absseclevel - \chapterzzz{#3}% - \or \seczzz{#3}% - \or \numberedsubseczzz{#3}% - \or \numberedsubsubseczzz{#3}% - \fi - \fi - \fi - \suppressfirstparagraphindent -} - -% an interface: -\def\numhead{\genhead N} -\def\apphead{\genhead A} -\def\unnmhead{\genhead U} - -% @chapter, @appendix, @unnumbered. Increment top-level counter, reset -% all lower-level sectioning counters to zero. -% -% Also set \chaplevelprefix, which we prepend to @float sequence numbers -% (e.g., figures), q.v. By default (before any chapter), that is empty. -\let\chaplevelprefix = \empty -% -\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz -\def\chapterzzz#1{% - % section resetting is \global in case the chapter is in a group, such - % as an @include file. - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\chapno by 1 - % - % Used for \float. - \gdef\chaplevelprefix{\the\chapno.}% - \resetallfloatnos - % - \message{\putwordChapter\space \the\chapno}% - % - % Write the actual heading. - \chapmacro{#1}{Ynumbered}{\the\chapno}% - % - % So @section and the like are numbered underneath this chapter. - \global\let\section = \numberedsec - \global\let\subsection = \numberedsubsec - \global\let\subsubsection = \numberedsubsubsec -} - -\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz -\def\appendixzzz#1{% - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\appendixno by 1 - \gdef\chaplevelprefix{\appendixletter.}% - \resetallfloatnos - % - \def\appendixnum{\putwordAppendix\space \appendixletter}% - \message{\appendixnum}% - % - \chapmacro{#1}{Yappendix}{\appendixletter}% - % - \global\let\section = \appendixsec - \global\let\subsection = \appendixsubsec - \global\let\subsubsection = \appendixsubsubsec -} - -\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz -\def\unnumberedzzz#1{% - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\unnumberedno by 1 - % - % Since an unnumbered has no number, no prefix for figures. - \global\let\chaplevelprefix = \empty - \resetallfloatnos - % - % This used to be simply \message{#1}, but TeX fully expands the - % argument to \message. Therefore, if #1 contained @-commands, TeX - % expanded them. For example, in `@unnumbered The @cite{Book}', TeX - % expanded @cite (which turns out to cause errors because \cite is meant - % to be executed, not expanded). - % - % Anyway, we don't want the fully-expanded definition of @cite to appear - % as a result of the \message, we just want `@cite' itself. We use - % \the<toks register> to achieve this: TeX expands \the<toks> only once, - % simply yielding the contents of <toks register>. (We also do this for - % the toc entries.) - \toks0 = {#1}% - \message{(\the\toks0)}% - % - \chapmacro{#1}{Ynothing}{\the\unnumberedno}% - % - \global\let\section = \unnumberedsec - \global\let\subsection = \unnumberedsubsec - \global\let\subsubsection = \unnumberedsubsubsec -} - -% @centerchap is like @unnumbered, but the heading is centered. -\outer\parseargdef\centerchap{% - % Well, we could do the following in a group, but that would break - % an assumption that \chapmacro is called at the outermost level. - % Thus we are safer this way: --kasal, 24feb04 - \let\centerparametersmaybe = \centerparameters - \unnmhead0{#1}% - \let\centerparametersmaybe = \relax -} - -% @top is like @unnumbered. -\let\top\unnumbered - -% Sections. -\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz -\def\seczzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% -} - -\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz -\def\appendixsectionzzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% -} -\let\appendixsec\appendixsection - -\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz -\def\unnumberedseczzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% -} - -% Subsections. -\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz -\def\numberedsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% -} - -\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz -\def\appendixsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Yappendix}% - {\appendixletter.\the\secno.\the\subsecno}% -} - -\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz -\def\unnumberedsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Ynothing}% - {\the\unnumberedno.\the\secno.\the\subsecno}% -} - -% Subsubsections. -\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz -\def\numberedsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Ynumbered}% - {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz -\def\appendixsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Yappendix}% - {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz -\def\unnumberedsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Ynothing}% - {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -% These macros control what the section commands do, according -% to what kind of chapter we are in (ordinary, appendix, or unnumbered). -% Define them by default for a numbered chapter. -\let\section = \numberedsec -\let\subsection = \numberedsubsec -\let\subsubsection = \numberedsubsubsec - -% Define @majorheading, @heading and @subheading - -% NOTE on use of \vbox for chapter headings, section headings, and such: -% 1) We use \vbox rather than the earlier \line to permit -% overlong headings to fold. -% 2) \hyphenpenalty is set to 10000 because hyphenation in a -% heading is obnoxious; this forbids it. -% 3) Likewise, headings look best if no \parindent is used, and -% if justification is not attempted. Hence \raggedright. - - -\def\majorheading{% - {\advance\chapheadingskip by 10pt \chapbreak }% - \parsearg\chapheadingzzz -} - -\def\chapheading{\chapbreak \parsearg\chapheadingzzz} -\def\chapheadingzzz#1{% - {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}% - \bigskip \par\penalty 200\relax - \suppressfirstparagraphindent -} - -% @heading, @subheading, @subsubheading. -\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} -\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} -\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} - -% These macros generate a chapter, section, etc. heading only -% (including whitespace, linebreaking, etc. around it), -% given all the information in convenient, parsed form. - -%%% Args are the skip and penalty (usually negative) -\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} - -%%% Define plain chapter starts, and page on/off switching for it -% Parameter controlling skip before chapter headings (if needed) - -\newskip\chapheadingskip - -\def\chapbreak{\dobreak \chapheadingskip {-4000}} -\def\chappager{\par\vfill\supereject} -% Because \domark is called before \chapoddpage, the filler page will -% get the headings for the next chapter, which is wrong. But we don't -% care -- we just disable all headings on the filler page. -\def\chapoddpage{% - \chappager - \ifodd\pageno \else - \begingroup - \evenheadline={\hfil}\evenfootline={\hfil}% - \oddheadline={\hfil}\oddfootline={\hfil}% - \hbox to 0pt{}% - \chappager - \endgroup - \fi -} - -\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} - -\def\CHAPPAGoff{% -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chapbreak -\global\let\pagealignmacro=\chappager} - -\def\CHAPPAGon{% -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chappager -\global\let\pagealignmacro=\chappager -\global\def\HEADINGSon{\HEADINGSsingle}} - -\def\CHAPPAGodd{% -\global\let\contentsalignmacro = \chapoddpage -\global\let\pchapsepmacro=\chapoddpage -\global\let\pagealignmacro=\chapoddpage -\global\def\HEADINGSon{\HEADINGSdouble}} - -\CHAPPAGon - -% Chapter opening. -% -% #1 is the text, #2 is the section type (Ynumbered, Ynothing, -% Yappendix, Yomitfromtoc), #3 the chapter number. -% -% To test against our argument. -\def\Ynothingkeyword{Ynothing} -\def\Yomitfromtockeyword{Yomitfromtoc} -\def\Yappendixkeyword{Yappendix} -% -\def\chapmacro#1#2#3{% - % Insert the first mark before the heading break (see notes for \domark). - \let\prevchapterdefs=\lastchapterdefs - \let\prevsectiondefs=\lastsectiondefs - \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}% - \gdef\thissection{}}% - % - \def\temptype{#2}% - \ifx\temptype\Ynothingkeyword - \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% - \gdef\thischapter{\thischaptername}}% - \else\ifx\temptype\Yomitfromtockeyword - \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% - \gdef\thischapter{}}% - \else\ifx\temptype\Yappendixkeyword - \toks0={#1}% - \xdef\lastchapterdefs{% - \gdef\noexpand\thischaptername{\the\toks0}% - \gdef\noexpand\thischapternum{\appendixletter}% - \gdef\noexpand\thischapter{\putwordAppendix{} \noexpand\thischapternum: - \noexpand\thischaptername}% - }% - \else - \toks0={#1}% - \xdef\lastchapterdefs{% - \gdef\noexpand\thischaptername{\the\toks0}% - \gdef\noexpand\thischapternum{\the\chapno}% - \gdef\noexpand\thischapter{\putwordChapter{} \noexpand\thischapternum: - \noexpand\thischaptername}% - }% - \fi\fi\fi - % - % Output the mark. Pass it through \safewhatsit, to take care of - % the preceding space. - \safewhatsit\domark - % - % Insert the chapter heading break. - \pchapsepmacro - % - % Now the second mark, after the heading break. No break points - % between here and the heading. - \let\prevchapterdefs=\lastchapterdefs - \let\prevsectiondefs=\lastsectiondefs - \domark - % - {% - \chapfonts \rm - % - % Have to define \lastsection before calling \donoderef, because the - % xref code eventually uses it. On the other hand, it has to be called - % after \pchapsepmacro, or the headline will change too soon. - \gdef\lastsection{#1}% - % - % Only insert the separating space if we have a chapter/appendix - % number, and don't print the unnumbered ``number''. - \ifx\temptype\Ynothingkeyword - \setbox0 = \hbox{}% - \def\toctype{unnchap}% - \else\ifx\temptype\Yomitfromtockeyword - \setbox0 = \hbox{}% contents like unnumbered, but no toc entry - \def\toctype{omit}% - \else\ifx\temptype\Yappendixkeyword - \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% - \def\toctype{app}% - \else - \setbox0 = \hbox{#3\enspace}% - \def\toctype{numchap}% - \fi\fi\fi - % - % Write the toc entry for this chapter. Must come before the - % \donoderef, because we include the current node name in the toc - % entry, and \donoderef resets it to empty. - \writetocentry{\toctype}{#1}{#3}% - % - % For pdftex, we have to write out the node definition (aka, make - % the pdfdest) after any page break, but before the actual text has - % been typeset. If the destination for the pdf outline is after the - % text, then jumping from the outline may wind up with the text not - % being visible, for instance under high magnification. - \donoderef{#2}% - % - % Typeset the actual heading. - \nobreak % Avoid page breaks at the interline glue. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent=\wd0 \centerparametersmaybe - \unhbox0 #1\par}% - }% - \nobreak\bigskip % no page break after a chapter title - \nobreak -} - -% @centerchap -- centered and unnumbered. -\let\centerparametersmaybe = \relax -\def\centerparameters{% - \advance\rightskip by 3\rightskip - \leftskip = \rightskip - \parfillskip = 0pt -} - - -% I don't think this chapter style is supported any more, so I'm not -% updating it with the new noderef stuff. We'll see. --karl, 11aug03. -% -\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} -% -\def\unnchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\nobreak -} -\def\chfopen #1#2{\chapoddpage {\chapfonts -\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% -\par\penalty 5000 % -} -\def\centerchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt - \hfill {\rm #1}\hfill}}\bigskip \par\nobreak -} -\def\CHAPFopen{% - \global\let\chapmacro=\chfopen - \global\let\centerchapmacro=\centerchfopen} - - -% Section titles. These macros combine the section number parts and -% call the generic \sectionheading to do the printing. -% -\newskip\secheadingskip -\def\secheadingbreak{\dobreak \secheadingskip{-1000}} - -% Subsection titles. -\newskip\subsecheadingskip -\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} - -% Subsubsection titles. -\def\subsubsecheadingskip{\subsecheadingskip} -\def\subsubsecheadingbreak{\subsecheadingbreak} - - -% Print any size, any type, section title. -% -% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is -% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the -% section number. -% -\def\seckeyword{sec} -% -\def\sectionheading#1#2#3#4{% - {% - % Switch to the right set of fonts. - \csname #2fonts\endcsname \rm - % - \def\sectionlevel{#2}% - \def\temptype{#3}% - % - % Insert first mark before the heading break (see notes for \domark). - \let\prevsectiondefs=\lastsectiondefs - \ifx\temptype\Ynothingkeyword - \ifx\sectionlevel\seckeyword - \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}% - \gdef\thissection{\thissectionname}}% - \fi - \else\ifx\temptype\Yomitfromtockeyword - % Don't redefine \thissection. - \else\ifx\temptype\Yappendixkeyword - \ifx\sectionlevel\seckeyword - \toks0={#1}% - \xdef\lastsectiondefs{% - \gdef\noexpand\thissectionname{\the\toks0}% - \gdef\noexpand\thissectionnum{#4}% - \gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum: - \noexpand\thissectionname}% - }% - \fi - \else - \ifx\sectionlevel\seckeyword - \toks0={#1}% - \xdef\lastsectiondefs{% - \gdef\noexpand\thissectionname{\the\toks0}% - \gdef\noexpand\thissectionnum{#4}% - \gdef\noexpand\thissection{\putwordSection{} \noexpand\thissectionnum: - \noexpand\thissectionname}% - }% - \fi - \fi\fi\fi - % - % Output the mark. Pass it through \safewhatsit, to take care of - % the preceding space. - \safewhatsit\domark - % - % Insert space above the heading. - \csname #2headingbreak\endcsname - % - % Now the second mark, after the heading break. No break points - % between here and the heading. - \let\prevsectiondefs=\lastsectiondefs - \domark - % - % Only insert the space after the number if we have a section number. - \ifx\temptype\Ynothingkeyword - \setbox0 = \hbox{}% - \def\toctype{unn}% - \gdef\lastsection{#1}% - \else\ifx\temptype\Yomitfromtockeyword - % for @headings -- no section number, don't include in toc, - % and don't redefine \lastsection. - \setbox0 = \hbox{}% - \def\toctype{omit}% - \let\sectionlevel=\empty - \else\ifx\temptype\Yappendixkeyword - \setbox0 = \hbox{#4\enspace}% - \def\toctype{app}% - \gdef\lastsection{#1}% - \else - \setbox0 = \hbox{#4\enspace}% - \def\toctype{num}% - \gdef\lastsection{#1}% - \fi\fi\fi - % - % Write the toc entry (before \donoderef). See comments in \chapmacro. - \writetocentry{\toctype\sectionlevel}{#1}{#4}% - % - % Write the node reference (= pdf destination for pdftex). - % Again, see comments in \chapmacro. - \donoderef{#3}% - % - % Interline glue will be inserted when the vbox is completed. - % That glue will be a valid breakpoint for the page, since it'll be - % preceded by a whatsit (usually from the \donoderef, or from the - % \writetocentry if there was no node). We don't want to allow that - % break, since then the whatsits could end up on page n while the - % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000. - \nobreak - % - % Output the actual section heading. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent=\wd0 % zero if no section number - \unhbox0 #1}% - }% - % Add extra space after the heading -- half of whatever came above it. - % Don't allow stretch, though. - \kern .5 \csname #2headingskip\endcsname - % - % Do not let the kern be a potential breakpoint, as it would be if it - % was followed by glue. - \nobreak - % - % We'll almost certainly start a paragraph next, so don't let that - % glue accumulate. (Not a breakpoint because it's preceded by a - % discardable item.) - \vskip-\parskip - % - % This is purely so the last item on the list is a known \penalty > - % 10000. This is so \startdefun can avoid allowing breakpoints after - % section headings. Otherwise, it would insert a valid breakpoint between: - % - % @section sec-whatever - % @deffn def-whatever - \penalty 10001 -} - - -\message{toc,} -% Table of contents. -\newwrite\tocfile - -% Write an entry to the toc file, opening it if necessary. -% Called from @chapter, etc. -% -% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} -% We append the current node name (if any) and page number as additional -% arguments for the \{chap,sec,...}entry macros which will eventually -% read this. The node name is used in the pdf outlines as the -% destination to jump to. -% -% We open the .toc file for writing here instead of at @setfilename (or -% any other fixed time) so that @contents can be anywhere in the document. -% But if #1 is `omit', then we don't do anything. This is used for the -% table of contents chapter openings themselves. -% -\newif\iftocfileopened -\def\omitkeyword{omit}% -% -\def\writetocentry#1#2#3{% - \edef\writetoctype{#1}% - \ifx\writetoctype\omitkeyword \else - \iftocfileopened\else - \immediate\openout\tocfile = \jobname.toc - \global\tocfileopenedtrue - \fi - % - \iflinks - {\atdummies - \edef\temp{% - \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}% - \temp - }% - \fi - \fi - % - % Tell \shipout to create a pdf destination on each page, if we're - % writing pdf. These are used in the table of contents. We can't - % just write one on every page because the title pages are numbered - % 1 and 2 (the page numbers aren't printed), and so are the first - % two pages of the document. Thus, we'd have two destinations named - % `1', and two named `2'. - \ifpdf \global\pdfmakepagedesttrue \fi -} - - -% These characters do not print properly in the Computer Modern roman -% fonts, so we must take special care. This is more or less redundant -% with the Texinfo input format setup at the end of this file. -% -\def\activecatcodes{% - \catcode`\"=\active - \catcode`\$=\active - \catcode`\<=\active - \catcode`\>=\active - \catcode`\\=\active - \catcode`\^=\active - \catcode`\_=\active - \catcode`\|=\active - \catcode`\~=\active -} - - -% Read the toc file, which is essentially Texinfo input. -\def\readtocfile{% - \setupdatafile - \activecatcodes - \input \tocreadfilename -} - -\newskip\contentsrightmargin \contentsrightmargin=1in -\newcount\savepageno -\newcount\lastnegativepageno \lastnegativepageno = -1 - -% Prepare to read what we've written to \tocfile. -% -\def\startcontents#1{% - % If @setchapternewpage on, and @headings double, the contents should - % start on an odd page, unlike chapters. Thus, we maintain - % \contentsalignmacro in parallel with \pagealignmacro. - % From: Torbjorn Granlund <tege@matematik.su.se> - \contentsalignmacro - \immediate\closeout\tocfile - % - % Don't need to put `Contents' or `Short Contents' in the headline. - % It is abundantly clear what they are. - \chapmacro{#1}{Yomitfromtoc}{}% - % - \savepageno = \pageno - \begingroup % Set up to handle contents files properly. - \raggedbottom % Worry more about breakpoints than the bottom. - \advance\hsize by -\contentsrightmargin % Don't use the full line length. - % - % Roman numerals for page numbers. - \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi -} - -% redefined for the two-volume lispref. We always output on -% \jobname.toc even if this is redefined. -% -\def\tocreadfilename{\jobname.toc} - -% Normal (long) toc. -% -\def\contents{% - \startcontents{\putwordTOC}% - \openin 1 \tocreadfilename\space - \ifeof 1 \else - \readtocfile - \fi - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \ifeof 1 \else - \pdfmakeoutlines - \fi - \closein 1 - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno -} - -% And just the chapters. -\def\summarycontents{% - \startcontents{\putwordShortTOC}% - % - \let\numchapentry = \shortchapentry - \let\appentry = \shortchapentry - \let\unnchapentry = \shortunnchapentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf - \let\sl=\shortcontsl \let\tt=\shortconttt - \rm - \hyphenpenalty = 10000 - \advance\baselineskip by 1pt % Open it up a little. - \def\numsecentry##1##2##3##4{} - \let\appsecentry = \numsecentry - \let\unnsecentry = \numsecentry - \let\numsubsecentry = \numsecentry - \let\appsubsecentry = \numsecentry - \let\unnsubsecentry = \numsecentry - \let\numsubsubsecentry = \numsecentry - \let\appsubsubsecentry = \numsecentry - \let\unnsubsubsecentry = \numsecentry - \openin 1 \tocreadfilename\space - \ifeof 1 \else - \readtocfile - \fi - \closein 1 - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno -} -\let\shortcontents = \summarycontents - -% Typeset the label for a chapter or appendix for the short contents. -% The arg is, e.g., `A' for an appendix, or `3' for a chapter. -% -\def\shortchaplabel#1{% - % This space should be enough, since a single number is .5em, and the - % widest letter (M) is 1em, at least in the Computer Modern fonts. - % But use \hss just in case. - % (This space doesn't include the extra space that gets added after - % the label; that gets put in by \shortchapentry above.) - % - % We'd like to right-justify chapter numbers, but that looks strange - % with appendix letters. And right-justifying numbers and - % left-justifying letters looks strange when there is less than 10 - % chapters. Have to read the whole toc once to know how many chapters - % there are before deciding ... - \hbox to 1em{#1\hss}% -} - -% These macros generate individual entries in the table of contents. -% The first argument is the chapter or section name. -% The last argument is the page number. -% The arguments in between are the chapter number, section number, ... - -% Chapters, in the main contents. -\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} -% -% Chapters, in the short toc. -% See comments in \dochapentry re vbox and related settings. -\def\shortchapentry#1#2#3#4{% - \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% -} - -% Appendices, in the main contents. -% Need the word Appendix, and a fixed-size box. -% -\def\appendixbox#1{% - % We use M since it's probably the widest letter. - \setbox0 = \hbox{\putwordAppendix{} M}% - \hbox to \wd0{\putwordAppendix{} #1\hss}} -% -\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} - -% Unnumbered chapters. -\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} -\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} - -% Sections. -\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} -\let\appsecentry=\numsecentry -\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} - -% Subsections. -\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} -\let\appsubsecentry=\numsubsecentry -\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} - -% And subsubsections. -\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} -\let\appsubsubsecentry=\numsubsubsecentry -\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} - -% This parameter controls the indentation of the various levels. -% Same as \defaultparindent. -\newdimen\tocindent \tocindent = 15pt - -% Now for the actual typesetting. In all these, #1 is the text and #2 is the -% page number. -% -% If the toc has to be broken over pages, we want it to be at chapters -% if at all possible; hence the \penalty. -\def\dochapentry#1#2{% - \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip - \begingroup - \chapentryfonts - \tocentry{#1}{\dopageno\bgroup#2\egroup}% - \endgroup - \nobreak\vskip .25\baselineskip plus.1\baselineskip -} - -\def\dosecentry#1#2{\begingroup - \secentryfonts \leftskip=\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -\def\dosubsecentry#1#2{\begingroup - \subsecentryfonts \leftskip=2\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -\def\dosubsubsecentry#1#2{\begingroup - \subsubsecentryfonts \leftskip=3\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -% We use the same \entry macro as for the index entries. -\let\tocentry = \entry - -% Space between chapter (or whatever) number and the title. -\def\labelspace{\hskip1em \relax} - -\def\dopageno#1{{\rm #1}} -\def\doshortpageno#1{{\rm #1}} - -\def\chapentryfonts{\secfonts \rm} -\def\secentryfonts{\textfonts} -\def\subsecentryfonts{\textfonts} -\def\subsubsecentryfonts{\textfonts} - - -\message{environments,} -% @foo ... @end foo. - -% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. -% -% Since these characters are used in examples, they should be an even number of -% \tt widths. Each \tt character is 1en, so two makes it 1em. -% -\def\point{$\star$} -\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}} -\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} -\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}} -\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} -\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}} - -% The @error{} command. -% Adapted from the TeXbook's \boxit. -% -\newbox\errorbox -% -{\tentt \global\dimen0 = 3em}% Width of the box. -\dimen2 = .55pt % Thickness of rules -% The text. (`r' is open on the right, `e' somewhat less so on the left.) -\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt} -% -\setbox\errorbox=\hbox to \dimen0{\hfil - \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. - \advance\hsize by -2\dimen2 % Rules. - \vbox{% - \hrule height\dimen2 - \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. - \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. - \kern3pt\vrule width\dimen2}% Space to right. - \hrule height\dimen2} - \hfil} -% -\def\error{\leavevmode\lower.7ex\copy\errorbox} - -% @tex ... @end tex escapes into raw Tex temporarily. -% One exception: @ is still an escape character, so that @end tex works. -% But \@ or @@ will get a plain tex @ character. - -\envdef\tex{% - \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 - \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 - \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie - \catcode `\%=14 - \catcode `\+=\other - \catcode `\"=\other - \catcode `\|=\other - \catcode `\<=\other - \catcode `\>=\other - \escapechar=`\\ - % - \let\b=\ptexb - \let\bullet=\ptexbullet - \let\c=\ptexc - \let\,=\ptexcomma - \let\.=\ptexdot - \let\dots=\ptexdots - \let\equiv=\ptexequiv - \let\!=\ptexexclam - \let\i=\ptexi - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - \let\{=\ptexlbrace - \let\+=\tabalign - \let\}=\ptexrbrace - \let\/=\ptexslash - \let\*=\ptexstar - \let\t=\ptext - \expandafter \let\csname top\endcsname=\ptextop % outer - \let\frenchspacing=\plainfrenchspacing - % - \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% - \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% - \def\@{@}% -} -% There is no need to define \Etex. - -% Define @lisp ... @end lisp. -% @lisp environment forms a group so it can rebind things, -% including the definition of @end lisp (which normally is erroneous). - -% Amount to narrow the margins by for @lisp. -\newskip\lispnarrowing \lispnarrowing=0.4in - -% This is the definition that ^^M gets inside @lisp, @example, and other -% such environments. \null is better than a space, since it doesn't -% have any width. -\def\lisppar{\null\endgraf} - -% This space is always present above and below environments. -\newskip\envskipamount \envskipamount = 0pt - -% Make spacing and below environment symmetrical. We use \parskip here -% to help in doing that, since in @example-like environments \parskip -% is reset to zero; thus the \afterenvbreak inserts no space -- but the -% start of the next paragraph will insert \parskip. -% -\def\aboveenvbreak{{% - % =10000 instead of <10000 because of a special case in \itemzzz and - % \sectionheading, q.v. - \ifnum \lastpenalty=10000 \else - \advance\envskipamount by \parskip - \endgraf - \ifdim\lastskip<\envskipamount - \removelastskip - % it's not a good place to break if the last penalty was \nobreak - % or better ... - \ifnum\lastpenalty<10000 \penalty-50 \fi - \vskip\envskipamount - \fi - \fi -}} - -\let\afterenvbreak = \aboveenvbreak - -% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will -% also clear it, so that its embedded environments do the narrowing again. -\let\nonarrowing=\relax - -% @cartouche ... @end cartouche: draw rectangle w/rounded corners around -% environment contents. -\font\circle=lcircle10 -\newdimen\circthick -\newdimen\cartouter\newdimen\cartinner -\newskip\normbskip\newskip\normpskip\newskip\normlskip -\circthick=\fontdimen8\circle -% -\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth -\def\ctr{{\hskip 6pt\circle\char'010}} -\def\cbl{{\circle\char'012\hskip -6pt}} -\def\cbr{{\hskip 6pt\circle\char'011}} -\def\carttop{\hbox to \cartouter{\hskip\lskip - \ctl\leaders\hrule height\circthick\hfil\ctr - \hskip\rskip}} -\def\cartbot{\hbox to \cartouter{\hskip\lskip - \cbl\leaders\hrule height\circthick\hfil\cbr - \hskip\rskip}} -% -\newskip\lskip\newskip\rskip - -\envdef\cartouche{% - \ifhmode\par\fi % can't be in the midst of a paragraph. - \startsavinginserts - \lskip=\leftskip \rskip=\rightskip - \leftskip=0pt\rightskip=0pt % we want these *outside*. - \cartinner=\hsize \advance\cartinner by-\lskip - \advance\cartinner by-\rskip - \cartouter=\hsize - \advance\cartouter by 18.4pt % allow for 3pt kerns on either - % side, and for 6pt waste from - % each corner char, and rule thickness - \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing = t% - \vbox\bgroup - \baselineskip=0pt\parskip=0pt\lineskip=0pt - \carttop - \hbox\bgroup - \hskip\lskip - \vrule\kern3pt - \vbox\bgroup - \kern3pt - \hsize=\cartinner - \baselineskip=\normbskip - \lineskip=\normlskip - \parskip=\normpskip - \vskip -\parskip - \comment % For explanation, see the end of \def\group. -} -\def\Ecartouche{% - \ifhmode\par\fi - \kern3pt - \egroup - \kern3pt\vrule - \hskip\rskip - \egroup - \cartbot - \egroup - \checkinserts -} - - -% This macro is called at the beginning of all the @example variants, -% inside a group. -\def\nonfillstart{% - \aboveenvbreak - \hfuzz = 12pt % Don't be fussy - \sepspaces % Make spaces be word-separators rather than space tokens. - \let\par = \lisppar % don't ignore blank lines - \obeylines % each line of input is a line of output - \parskip = 0pt - \parindent = 0pt - \emergencystretch = 0pt % don't try to avoid overfull boxes - \ifx\nonarrowing\relax - \advance \leftskip by \lispnarrowing - \exdentamount=\lispnarrowing - \else - \let\nonarrowing = \relax - \fi - \let\exdent=\nofillexdent -} - -% If you want all examples etc. small: @set dispenvsize small. -% If you want even small examples the full size: @set dispenvsize nosmall. -% This affects the following displayed environments: -% @example, @display, @format, @lisp -% -\def\smallword{small} -\def\nosmallword{nosmall} -\let\SETdispenvsize\relax -\def\setnormaldispenv{% - \ifx\SETdispenvsize\smallword - % end paragraph for sake of leading, in case document has no blank - % line. This is redundant with what happens in \aboveenvbreak, but - % we need to do it before changing the fonts, and it's inconvenient - % to change the fonts afterward. - \ifnum \lastpenalty=10000 \else \endgraf \fi - \smallexamplefonts \rm - \fi -} -\def\setsmalldispenv{% - \ifx\SETdispenvsize\nosmallword - \else - \ifnum \lastpenalty=10000 \else \endgraf \fi - \smallexamplefonts \rm - \fi -} - -% We often define two environments, @foo and @smallfoo. -% Let's do it by one command: -\def\makedispenv #1#2{ - \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2} - \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2} - \expandafter\let\csname E#1\endcsname \afterenvbreak - \expandafter\let\csname Esmall#1\endcsname \afterenvbreak -} - -% Define two synonyms: -\def\maketwodispenvs #1#2#3{ - \makedispenv{#1}{#3} - \makedispenv{#2}{#3} -} - -% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. -% -% @smallexample and @smalllisp: use smaller fonts. -% Originally contributed by Pavel@xerox. -% -\maketwodispenvs {lisp}{example}{% - \nonfillstart - \tt\quoteexpand - \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. - \gobble % eat return -} -% @display/@smalldisplay: same as @lisp except keep current font. -% -\makedispenv {display}{% - \nonfillstart - \gobble -} - -% @format/@smallformat: same as @display except don't narrow margins. -% -\makedispenv{format}{% - \let\nonarrowing = t% - \nonfillstart - \gobble -} - -% @flushleft: same as @format, but doesn't obey \SETdispenvsize. -\envdef\flushleft{% - \let\nonarrowing = t% - \nonfillstart - \gobble -} -\let\Eflushleft = \afterenvbreak - -% @flushright. -% -\envdef\flushright{% - \let\nonarrowing = t% - \nonfillstart - \advance\leftskip by 0pt plus 1fill - \gobble -} -\let\Eflushright = \afterenvbreak - - -% @quotation does normal linebreaking (hence we can't use \nonfillstart) -% and narrows the margins. We keep \parskip nonzero in general, since -% we're doing normal filling. So, when using \aboveenvbreak and -% \afterenvbreak, temporarily make \parskip 0. -% -\envdef\quotation{% - {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \parindent=0pt - % - % @cartouche defines \nonarrowing to inhibit narrowing at next level down. - \ifx\nonarrowing\relax - \advance\leftskip by \lispnarrowing - \advance\rightskip by \lispnarrowing - \exdentamount = \lispnarrowing - \else - \let\nonarrowing = \relax - \fi - \parsearg\quotationlabel -} - -% We have retained a nonzero parskip for the environment, since we're -% doing normal filling. -% -\def\Equotation{% - \par - \ifx\quotationauthor\undefined\else - % indent a bit. - \leftline{\kern 2\leftskip \sl ---\quotationauthor}% - \fi - {\parskip=0pt \afterenvbreak}% -} - -% If we're given an argument, typeset it in bold with a colon after. -\def\quotationlabel#1{% - \def\temp{#1}% - \ifx\temp\empty \else - {\bf #1: }% - \fi -} - - -% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>} -% If we want to allow any <char> as delimiter, -% we need the curly braces so that makeinfo sees the @verb command, eg: -% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org -% -% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. -% -% [Knuth] p.344; only we need to do the other characters Texinfo sets -% active too. Otherwise, they get lost as the first character on a -% verbatim line. -\def\dospecials{% - \do\ \do\\\do\{\do\}\do\$\do\&% - \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% - \do\<\do\>\do\|\do\@\do+\do\"% -} -% -% [Knuth] p. 380 -\def\uncatcodespecials{% - \def\do##1{\catcode`##1=\other}\dospecials} -% -% [Knuth] pp. 380,381,391 -% Disable Spanish ligatures ?` and !` of \tt font -\begingroup - \catcode`\`=\active\gdef`{\relax\lq} -\endgroup -% -% Setup for the @verb command. -% -% Eight spaces for a tab -\begingroup - \catcode`\^^I=\active - \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} -\endgroup -% -\def\setupverb{% - \tt % easiest (and conventionally used) font for verbatim - \def\par{\leavevmode\endgraf}% - \catcode`\`=\active - \tabeightspaces - % Respect line breaks, - % print special symbols as themselves, and - % make each space count - % must do in this order: - \obeylines \uncatcodespecials \sepspaces -} - -% Setup for the @verbatim environment -% -% Real tab expansion -\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount -% -\def\starttabbox{\setbox0=\hbox\bgroup} - -% Allow an option to not replace quotes with a regular directed right -% quote/apostrophe (char 0x27), but instead use the undirected quote -% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it -% the default, but it works for pasting with more pdf viewers (at least -% evince), the lilypond developers report. xpdf does work with the -% regular 0x27. -% -\def\codequoteright{% - \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax - \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax - '% - \else \char'15 \fi - \else \char'15 \fi -} -% -% and a similar option for the left quote char vs. a grave accent. -% Modern fonts display ASCII 0x60 as a grave accent, so some people like -% the code environments to do likewise. -% -\def\codequoteleft{% - \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax - \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax - `% - \else \char'22 \fi - \else \char'22 \fi -} -% -\begingroup - \catcode`\^^I=\active - \gdef\tabexpand{% - \catcode`\^^I=\active - \def^^I{\leavevmode\egroup - \dimen0=\wd0 % the width so far, or since the previous tab - \divide\dimen0 by\tabw - \multiply\dimen0 by\tabw % compute previous multiple of \tabw - \advance\dimen0 by\tabw % advance to next multiple of \tabw - \wd0=\dimen0 \box0 \starttabbox - }% - } - \catcode`\'=\active - \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}% - % - \catcode`\`=\active - \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}% - % - \gdef\quoteexpand{\rquoteexpand \lquoteexpand}% -\endgroup - -% start the verbatim environment. -\def\setupverbatim{% - \let\nonarrowing = t% - \nonfillstart - % Easiest (and conventionally used) font for verbatim - \tt - \def\par{\leavevmode\egroup\box0\endgraf}% - \catcode`\`=\active - \tabexpand - \quoteexpand - % Respect line breaks, - % print special symbols as themselves, and - % make each space count - % must do in this order: - \obeylines \uncatcodespecials \sepspaces - \everypar{\starttabbox}% -} - -% Do the @verb magic: verbatim text is quoted by unique -% delimiter characters. Before first delimiter expect a -% right brace, after last delimiter expect closing brace: -% -% \def\doverb'{'<char>#1<char>'}'{#1} -% -% [Knuth] p. 382; only eat outer {} -\begingroup - \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other - \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] -\endgroup -% -\def\verb{\begingroup\setupverb\doverb} -% -% -% Do the @verbatim magic: define the macro \doverbatim so that -% the (first) argument ends when '@end verbatim' is reached, ie: -% -% \def\doverbatim#1@end verbatim{#1} -% -% For Texinfo it's a lot easier than for LaTeX, -% because texinfo's \verbatim doesn't stop at '\end{verbatim}': -% we need not redefine '\', '{' and '}'. -% -% Inspired by LaTeX's verbatim command set [latex.ltx] -% -\begingroup - \catcode`\ =\active - \obeylines % - % ignore everything up to the first ^^M, that's the newline at the end - % of the @verbatim input line itself. Otherwise we get an extra blank - % line in the output. - \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% - % We really want {...\end verbatim} in the body of the macro, but - % without the active space; thus we have to use \xdef and \gobble. -\endgroup -% -\envdef\verbatim{% - \setupverbatim\doverbatim -} -\let\Everbatim = \afterenvbreak - - -% @verbatiminclude FILE - insert text of file in verbatim environment. -% -\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} -% -\def\doverbatiminclude#1{% - {% - \makevalueexpandable - \setupverbatim - \input #1 - \afterenvbreak - }% -} - -% @copying ... @end copying. -% Save the text away for @insertcopying later. -% -% We save the uninterpreted tokens, rather than creating a box. -% Saving the text in a box would be much easier, but then all the -% typesetting commands (@smallbook, font changes, etc.) have to be done -% beforehand -- and a) we want @copying to be done first in the source -% file; b) letting users define the frontmatter in as flexible order as -% possible is very desirable. -% -\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} -\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} -% -\def\insertcopying{% - \begingroup - \parindent = 0pt % paragraph indentation looks wrong on title page - \scanexp\copyingtext - \endgroup -} - - -\message{defuns,} -% @defun etc. - -\newskip\defbodyindent \defbodyindent=.4in -\newskip\defargsindent \defargsindent=50pt -\newskip\deflastargmargin \deflastargmargin=18pt -\newcount\defunpenalty - -% Start the processing of @deffn: -\def\startdefun{% - \ifnum\lastpenalty<10000 - \medbreak - \defunpenalty=10003 % Will keep this @deffn together with the - % following @def command, see below. - \else - % If there are two @def commands in a row, we'll have a \nobreak, - % which is there to keep the function description together with its - % header. But if there's nothing but headers, we need to allow a - % break somewhere. Check specifically for penalty 10002, inserted - % by \printdefunline, instead of 10000, since the sectioning - % commands also insert a nobreak penalty, and we don't want to allow - % a break between a section heading and a defun. - % - % As a minor refinement, we avoid "club" headers by signalling - % with penalty of 10003 after the very first @deffn in the - % sequence (see above), and penalty of 10002 after any following - % @def command. - \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi - % - % Similarly, after a section heading, do not allow a break. - % But do insert the glue. - \medskip % preceded by discardable penalty, so not a breakpoint - \fi - % - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent -} - -\def\dodefunx#1{% - % First, check whether we are in the right environment: - \checkenv#1% - % - % As above, allow line break if we have multiple x headers in a row. - % It's not a great place, though. - \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi - % - % And now, it's time to reuse the body of the original defun: - \expandafter\gobbledefun#1% -} -\def\gobbledefun#1\startdefun{} - -% \printdefunline \deffnheader{text} -% -\def\printdefunline#1#2{% - \begingroup - % call \deffnheader: - #1#2 \endheader - % common ending: - \interlinepenalty = 10000 - \advance\rightskip by 0pt plus 1fil - \endgraf - \nobreak\vskip -\parskip - \penalty\defunpenalty % signal to \startdefun and \dodefunx - % Some of the @defun-type tags do not enable magic parentheses, - % rendering the following check redundant. But we don't optimize. - \checkparencounts - \endgroup -} - -\def\Edefun{\endgraf\medbreak} - -% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; -% the only thing remaining is to define \deffnheader. -% -\def\makedefun#1{% - \expandafter\let\csname E#1\endcsname = \Edefun - \edef\temp{\noexpand\domakedefun - \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% - \temp -} - -% \domakedefun \deffn \deffnx \deffnheader -% -% Define \deffn and \deffnx, without parameters. -% \deffnheader has to be defined explicitly. -% -\def\domakedefun#1#2#3{% - \envdef#1{% - \startdefun - \parseargusing\activeparens{\printdefunline#3}% - }% - \def#2{\dodefunx#1}% - \def#3% -} - -%%% Untyped functions: - -% @deffn category name args -\makedefun{deffn}{\deffngeneral{}} - -% @deffn category class name args -\makedefun{defop}#1 {\defopon{#1\ \putwordon}} - -% \defopon {category on}class name args -\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deffngeneral {subind}category name args -% -\def\deffngeneral#1#2 #3 #4\endheader{% - % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. - \dosubind{fn}{\code{#3}}{#1}% - \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% -} - -%%% Typed functions: - -% @deftypefn category type name args -\makedefun{deftypefn}{\deftypefngeneral{}} - -% @deftypeop category class type name args -\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} - -% \deftypeopon {category on}class type name args -\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deftypefngeneral {subind}category type name args -% -\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% - \dosubind{fn}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% -} - -%%% Typed variables: - -% @deftypevr category type var args -\makedefun{deftypevr}{\deftypecvgeneral{}} - -% @deftypecv category class type var args -\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} - -% \deftypecvof {category of}class type var args -\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } - -% \deftypecvgeneral {subind}category type var args -% -\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% - \dosubind{vr}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% -} - -%%% Untyped variables: - -% @defvr category var args -\makedefun{defvr}#1 {\deftypevrheader{#1} {} } - -% @defcv category class var args -\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} - -% \defcvof {category of}class var args -\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } - -%%% Type: -% @deftp category name args -\makedefun{deftp}#1 #2 #3\endheader{% - \doind{tp}{\code{#2}}% - \defname{#1}{}{#2}\defunargs{#3\unskip}% -} - -% Remaining @defun-like shortcuts: -\makedefun{defun}{\deffnheader{\putwordDeffunc} } -\makedefun{defmac}{\deffnheader{\putwordDefmac} } -\makedefun{defspec}{\deffnheader{\putwordDefspec} } -\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } -\makedefun{defvar}{\defvrheader{\putwordDefvar} } -\makedefun{defopt}{\defvrheader{\putwordDefopt} } -\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } -\makedefun{defmethod}{\defopon\putwordMethodon} -\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} -\makedefun{defivar}{\defcvof\putwordInstanceVariableof} -\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} - -% \defname, which formats the name of the @def (not the args). -% #1 is the category, such as "Function". -% #2 is the return type, if any. -% #3 is the function name. -% -% We are followed by (but not passed) the arguments, if any. -% -\def\defname#1#2#3{% - % Get the values of \leftskip and \rightskip as they were outside the @def... - \advance\leftskip by -\defbodyindent - % - % How we'll format the type name. Putting it in brackets helps - % distinguish it from the body text that may end up on the next line - % just below it. - \def\temp{#1}% - \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} - % - % Figure out line sizes for the paragraph shape. - % The first line needs space for \box0; but if \rightskip is nonzero, - % we need only space for the part of \box0 which exceeds it: - \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip - % The continuations: - \dimen2=\hsize \advance\dimen2 by -\defargsindent - % (plain.tex says that \dimen1 should be used only as global.) - \parshape 2 0in \dimen0 \defargsindent \dimen2 - % - % Put the type name to the right margin. - \noindent - \hbox to 0pt{% - \hfil\box0 \kern-\hsize - % \hsize has to be shortened this way: - \kern\leftskip - % Intentionally do not respect \rightskip, since we need the space. - }% - % - % Allow all lines to be underfull without complaint: - \tolerance=10000 \hbadness=10000 - \exdentamount=\defbodyindent - {% - % defun fonts. We use typewriter by default (used to be bold) because: - % . we're printing identifiers, they should be in tt in principle. - % . in languages with many accents, such as Czech or French, it's - % common to leave accents off identifiers. The result looks ok in - % tt, but exceedingly strange in rm. - % . we don't want -- and --- to be treated as ligatures. - % . this still does not fix the ?` and !` ligatures, but so far no - % one has made identifiers using them :). - \df \tt - \def\temp{#2}% return value type - \ifx\temp\empty\else \tclose{\temp} \fi - #3% output function name - }% - {\rm\enskip}% hskip 0.5 em of \tenrm - % - \boldbrax - % arguments will be output next, if any. -} - -% Print arguments in slanted roman (not ttsl), inconsistently with using -% tt for the name. This is because literal text is sometimes needed in -% the argument list (groff manual), and ttsl and tt are not very -% distinguishable. Prevent hyphenation at `-' chars. -% -\def\defunargs#1{% - % use sl by default (not ttsl), - % tt for the names. - \df \sl \hyphenchar\font=0 - % - % On the other hand, if an argument has two dashes (for instance), we - % want a way to get ttsl. Let's try @var for that. - \let\var=\ttslanted - #1% - \sl\hyphenchar\font=45 -} - -% We want ()&[] to print specially on the defun line. -% -\def\activeparens{% - \catcode`\(=\active \catcode`\)=\active - \catcode`\[=\active \catcode`\]=\active - \catcode`\&=\active -} - -% Make control sequences which act like normal parenthesis chars. -\let\lparen = ( \let\rparen = ) - -% Be sure that we always have a definition for `(', etc. For example, -% if the fn name has parens in it, \boldbrax will not be in effect yet, -% so TeX would otherwise complain about undefined control sequence. -{ - \activeparens - \global\let(=\lparen \global\let)=\rparen - \global\let[=\lbrack \global\let]=\rbrack - \global\let& = \& - - \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} - \gdef\magicamp{\let&=\amprm} -} - -\newcount\parencount - -% If we encounter &foo, then turn on ()-hacking afterwards -\newif\ifampseen -\def\amprm#1 {\ampseentrue{\bf\ }} - -\def\parenfont{% - \ifampseen - % At the first level, print parens in roman, - % otherwise use the default font. - \ifnum \parencount=1 \rm \fi - \else - % The \sf parens (in \boldbrax) actually are a little bolder than - % the contained text. This is especially needed for [ and ] . - \sf - \fi -} -\def\infirstlevel#1{% - \ifampseen - \ifnum\parencount=1 - #1% - \fi - \fi -} -\def\bfafterword#1 {#1 \bf} - -\def\opnr{% - \global\advance\parencount by 1 - {\parenfont(}% - \infirstlevel \bfafterword -} -\def\clnr{% - {\parenfont)}% - \infirstlevel \sl - \global\advance\parencount by -1 -} - -\newcount\brackcount -\def\lbrb{% - \global\advance\brackcount by 1 - {\bf[}% -} -\def\rbrb{% - {\bf]}% - \global\advance\brackcount by -1 -} - -\def\checkparencounts{% - \ifnum\parencount=0 \else \badparencount \fi - \ifnum\brackcount=0 \else \badbrackcount \fi -} -% these should not use \errmessage; the glibc manual, at least, actually -% has such constructs (when documenting function pointers). -\def\badparencount{% - \message{Warning: unbalanced parentheses in @def...}% - \global\parencount=0 -} -\def\badbrackcount{% - \message{Warning: unbalanced square brackets in @def...}% - \global\brackcount=0 -} - - -\message{macros,} -% @macro. - -% To do this right we need a feature of e-TeX, \scantokens, -% which we arrange to emulate with a temporary file in ordinary TeX. -\ifx\eTeXversion\undefined - \newwrite\macscribble - \def\scantokens#1{% - \toks0={#1}% - \immediate\openout\macscribble=\jobname.tmp - \immediate\write\macscribble{\the\toks0}% - \immediate\closeout\macscribble - \input \jobname.tmp - } -\fi - -\def\scanmacro#1{% - \begingroup - \newlinechar`\^^M - \let\xeatspaces\eatspaces - % Undo catcode changes of \startcontents and \doprintindex - % When called from @insertcopying or (short)caption, we need active - % backslash to get it printed correctly. Previously, we had - % \catcode`\\=\other instead. We'll see whether a problem appears - % with macro expansion. --kasal, 19aug04 - \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ - % ... and \example - \spaceisspace - % - % Append \endinput to make sure that TeX does not see the ending newline. - % I've verified that it is necessary both for e-TeX and for ordinary TeX - % --kasal, 29nov03 - \scantokens{#1\endinput}% - \endgroup -} - -\def\scanexp#1{% - \edef\temp{\noexpand\scanmacro{#1}}% - \temp -} - -\newcount\paramno % Count of parameters -\newtoks\macname % Macro name -\newif\ifrecursive % Is it recursive? - -% List of all defined macros in the form -% \definedummyword\macro1\definedummyword\macro2... -% Currently is also contains all @aliases; the list can be split -% if there is a need. -\def\macrolist{} - -% Add the macro to \macrolist -\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} -\def\addtomacrolistxxx#1{% - \toks0 = \expandafter{\macrolist\definedummyword#1}% - \xdef\macrolist{\the\toks0}% -} - -% Utility routines. -% This does \let #1 = #2, with \csnames; that is, -% \let \csname#1\endcsname = \csname#2\endcsname -% (except of course we have to play expansion games). -% -\def\cslet#1#2{% - \expandafter\let - \csname#1\expandafter\endcsname - \csname#2\endcsname -} - -% Trim leading and trailing spaces off a string. -% Concepts from aro-bend problem 15 (see CTAN). -{\catcode`\@=11 -\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} -\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} -\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} -\def\unbrace#1{#1} -\unbrace{\gdef\trim@@@ #1 } #2@{#1} -} - -% Trim a single trailing ^^M off a string. -{\catcode`\^^M=\other \catcode`\Q=3% -\gdef\eatcr #1{\eatcra #1Q^^MQ}% -\gdef\eatcra#1^^MQ{\eatcrb#1Q}% -\gdef\eatcrb#1Q#2Q{#1}% -} - -% Macro bodies are absorbed as an argument in a context where -% all characters are catcode 10, 11 or 12, except \ which is active -% (as in normal texinfo). It is necessary to change the definition of \. - -% Non-ASCII encodings make 8-bit characters active, so un-activate -% them to avoid their expansion. Must do this non-globally, to -% confine the change to the current group. - -% It's necessary to have hard CRs when the macro is executed. This is -% done by making ^^M (\endlinechar) catcode 12 when reading the macro -% body, and then making it the \newlinechar in \scanmacro. - -\def\scanctxt{% - \catcode`\"=\other - \catcode`\+=\other - \catcode`\<=\other - \catcode`\>=\other - \catcode`\@=\other - \catcode`\^=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\~=\other - \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi -} - -\def\scanargctxt{% - \scanctxt - \catcode`\\=\other - \catcode`\^^M=\other -} - -\def\macrobodyctxt{% - \scanctxt - \catcode`\{=\other - \catcode`\}=\other - \catcode`\^^M=\other - \usembodybackslash -} - -\def\macroargctxt{% - \scanctxt - \catcode`\\=\other -} - -% \mbodybackslash is the definition of \ in @macro bodies. -% It maps \foo\ => \csname macarg.foo\endcsname => #N -% where N is the macro parameter number. -% We define \csname macarg.\endcsname to be \realbackslash, so -% \\ in macro replacement text gets you a backslash. - -{\catcode`@=0 @catcode`@\=@active - @gdef@usembodybackslash{@let\=@mbodybackslash} - @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} -} -\expandafter\def\csname macarg.\endcsname{\realbackslash} - -\def\macro{\recursivefalse\parsearg\macroxxx} -\def\rmacro{\recursivetrue\parsearg\macroxxx} - -\def\macroxxx#1{% - \getargs{#1}% now \macname is the macname and \argl the arglist - \ifx\argl\empty % no arguments - \paramno=0% - \else - \expandafter\parsemargdef \argl;% - \fi - \if1\csname ismacro.\the\macname\endcsname - \message{Warning: redefining \the\macname}% - \else - \expandafter\ifx\csname \the\macname\endcsname \relax - \else \errmessage{Macro name \the\macname\space already defined}\fi - \global\cslet{macsave.\the\macname}{\the\macname}% - \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% - \addtomacrolist{\the\macname}% - \fi - \begingroup \macrobodyctxt - \ifrecursive \expandafter\parsermacbody - \else \expandafter\parsemacbody - \fi} - -\parseargdef\unmacro{% - \if1\csname ismacro.#1\endcsname - \global\cslet{#1}{macsave.#1}% - \global\expandafter\let \csname ismacro.#1\endcsname=0% - % Remove the macro name from \macrolist: - \begingroup - \expandafter\let\csname#1\endcsname \relax - \let\definedummyword\unmacrodo - \xdef\macrolist{\macrolist}% - \endgroup - \else - \errmessage{Macro #1 not defined}% - \fi -} - -% Called by \do from \dounmacro on each macro. The idea is to omit any -% macro definitions that have been changed to \relax. -% -\def\unmacrodo#1{% - \ifx #1\relax - % remove this - \else - \noexpand\definedummyword \noexpand#1% - \fi -} - -% This makes use of the obscure feature that if the last token of a -% <parameter list> is #, then the preceding argument is delimited by -% an opening brace, and that opening brace is not consumed. -\def\getargs#1{\getargsxxx#1{}} -\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} -\def\getmacname #1 #2\relax{\macname={#1}} -\def\getmacargs#1{\def\argl{#1}} - -% Parse the optional {params} list. Set up \paramno and \paramlist -% so \defmacro knows what to do. Define \macarg.blah for each blah -% in the params list, to be ##N where N is the position in that list. -% That gets used by \mbodybackslash (above). - -% We need to get `macro parameter char #' into several definitions. -% The technique used is stolen from LaTeX: let \hash be something -% unexpandable, insert that wherever you need a #, and then redefine -% it to # just before using the token list produced. -% -% The same technique is used to protect \eatspaces till just before -% the macro is used. - -\def\parsemargdef#1;{\paramno=0\def\paramlist{}% - \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,} -\def\parsemargdefxxx#1,{% - \if#1;\let\next=\relax - \else \let\next=\parsemargdefxxx - \advance\paramno by 1% - \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname - {\xeatspaces{\hash\the\paramno}}% - \edef\paramlist{\paramlist\hash\the\paramno,}% - \fi\next} - -% These two commands read recursive and nonrecursive macro bodies. -% (They're different since rec and nonrec macros end differently.) - -\long\def\parsemacbody#1@end macro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% -\long\def\parsermacbody#1@end rmacro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% - -% This defines the macro itself. There are six cases: recursive and -% nonrecursive macros of zero, one, and many arguments. -% Much magic with \expandafter here. -% \xdef is used so that macro definitions will survive the file -% they're defined in; @include reads the file inside a group. -\def\defmacro{% - \let\hash=##% convert placeholders to macro parameter chars - \ifrecursive - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\scanmacro{\temp}}% - \or % 1 - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup\noexpand\scanmacro{\temp}}% - \else % many - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{\egroup\noexpand\scanmacro{\temp}}% - \fi - \else - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \or % 1 - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \else % many - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \expandafter\noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{% - \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \fi - \fi} - -\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} - -% \braceorline decides whether the next nonwhitespace character is a -% {. If so it reads up to the closing }, if not, it reads the whole -% line. Whatever was read is then fed to the next control sequence -% as an argument (by \parsebrace or \parsearg) -\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} -\def\braceorlinexxx{% - \ifx\nchar\bgroup\else - \expandafter\parsearg - \fi \macnamexxx} - - -% @alias. -% We need some trickery to remove the optional spaces around the equal -% sign. Just make them active and then expand them all to nothing. -\def\alias{\parseargusing\obeyspaces\aliasxxx} -\def\aliasxxx #1{\aliasyyy#1\relax} -\def\aliasyyy #1=#2\relax{% - {% - \expandafter\let\obeyedspace=\empty - \addtomacrolist{#1}% - \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% - }% - \next -} - - -\message{cross references,} - -\newwrite\auxfile -\newif\ifhavexrefs % True if xref values are known. -\newif\ifwarnedxrefs % True if we warned once that they aren't known. - -% @inforef is relatively simple. -\def\inforef #1{\inforefzzz #1,,,,**} -\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, - node \samp{\ignorespaces#1{}}} - -% @node's only job in TeX is to define \lastnode, which is used in -% cross-references. The @node line might or might not have commas, and -% might or might not have spaces before the first comma, like: -% @node foo , bar , ... -% We don't want such trailing spaces in the node name. -% -\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse} -% -% also remove a trailing comma, in case of something like this: -% @node Help-Cross, , , Cross-refs -\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} -\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} - -\let\nwnode=\node -\let\lastnode=\empty - -% Write a cross-reference definition for the current node. #1 is the -% type (Ynumbered, Yappendix, Ynothing). -% -\def\donoderef#1{% - \ifx\lastnode\empty\else - \setref{\lastnode}{#1}% - \global\let\lastnode=\empty - \fi -} - -% @anchor{NAME} -- define xref target at arbitrary point. -% -\newcount\savesfregister -% -\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} -\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} -\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} - -% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an -% anchor), which consists of three parts: -% 1) NAME-title - the current sectioning name taken from \lastsection, -% or the anchor name. -% 2) NAME-snt - section number and type, passed as the SNT arg, or -% empty for anchors. -% 3) NAME-pg - the page number. -% -% This is called from \donoderef, \anchor, and \dofloat. In the case of -% floats, there is an additional part, which is not written here: -% 4) NAME-lof - the text as it should appear in a @listoffloats. -% -\def\setref#1#2{% - \pdfmkdest{#1}% - \iflinks - {% - \atdummies % preserve commands, but don't expand them - \edef\writexrdef##1##2{% - \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef - ##1}{##2}}% these are parameters of \writexrdef - }% - \toks0 = \expandafter{\lastsection}% - \immediate \writexrdef{title}{\the\toks0 }% - \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. - \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout - }% - \fi -} - -% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is -% the node name, #2 the name of the Info cross-reference, #3 the printed -% node name, #4 the name of the Info file, #5 the name of the printed -% manual. All but the node name can be omitted. -% -\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} -\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} -\def\ref#1{\xrefX[#1,,,,,,,]} -\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup - \unsepspaces - \def\printedmanual{\ignorespaces #5}% - \def\printedrefname{\ignorespaces #3}% - \setbox1=\hbox{\printedmanual\unskip}% - \setbox0=\hbox{\printedrefname\unskip}% - \ifdim \wd0 = 0pt - % No printed node name was explicitly given. - \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax - % Use the node name inside the square brackets. - \def\printedrefname{\ignorespaces #1}% - \else - % Use the actual chapter/section title appear inside - % the square brackets. Use the real section title if we have it. - \ifdim \wd1 > 0pt - % It is in another manual, so we don't have it. - \def\printedrefname{\ignorespaces #1}% - \else - \ifhavexrefs - % We know the real title if we have the xref values. - \def\printedrefname{\refx{#1-title}{}}% - \else - % Otherwise just copy the Info node name. - \def\printedrefname{\ignorespaces #1}% - \fi% - \fi - \fi - \fi - % - % Make link in pdf output. - \ifpdf - {\indexnofonts - \turnoffactive - % This expands tokens, so do it after making catcode changes, so _ - % etc. don't get their TeX definitions. - \getfilename{#4}% - % - % See comments at \activebackslashdouble. - {\activebackslashdouble \xdef\pdfxrefdest{#1}% - \backslashparens\pdfxrefdest}% - % - \leavevmode - \startlink attr{/Border [0 0 0]}% - \ifnum\filenamelength>0 - goto file{\the\filename.pdf} name{\pdfxrefdest}% - \else - goto name{\pdfmkpgn{\pdfxrefdest}}% - \fi - }% - \setcolor{\linkcolor}% - \fi - % - % Float references are printed completely differently: "Figure 1.2" - % instead of "[somenode], p.3". We distinguish them by the - % LABEL-title being set to a magic string. - {% - % Have to otherify everything special to allow the \csname to - % include an _ in the xref name, etc. - \indexnofonts - \turnoffactive - \expandafter\global\expandafter\let\expandafter\Xthisreftitle - \csname XR#1-title\endcsname - }% - \iffloat\Xthisreftitle - % If the user specified the print name (third arg) to the ref, - % print it instead of our usual "Figure 1.2". - \ifdim\wd0 = 0pt - \refx{#1-snt}{}% - \else - \printedrefname - \fi - % - % if the user also gave the printed manual name (fifth arg), append - % "in MANUALNAME". - \ifdim \wd1 > 0pt - \space \putwordin{} \cite{\printedmanual}% - \fi - \else - % node/anchor (non-float) references. - % - % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not - % insert empty discretionaries after hyphens, which means that it will - % not find a line break at a hyphen in a node names. Since some manuals - % are best written with fairly long node names, containing hyphens, this - % is a loss. Therefore, we give the text of the node name again, so it - % is as if TeX is seeing it for the first time. - \ifdim \wd1 > 0pt - \putwordSection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}% - \else - % _ (for example) has to be the character _ for the purposes of the - % control sequence corresponding to the node, but it has to expand - % into the usual \leavevmode...\vrule stuff for purposes of - % printing. So we \turnoffactive for the \refx-snt, back on for the - % printing, back off for the \refx-pg. - {\turnoffactive - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% - \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi - }% - % output the `[mynode]' via a macro so it can be overridden. - \xrefprintnodename\printedrefname - % - % But we always want a comma and a space: - ,\space - % - % output the `page 3'. - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% - \fi - \fi - \endlink -\endgroup} - -% This macro is called from \xrefX for the `[nodename]' part of xref -% output. It's a separate macro only so it can be changed more easily, -% since square brackets don't work well in some documents. Particularly -% one that Bob is working on :). -% -\def\xrefprintnodename#1{[#1]} - -% Things referred to by \setref. -% -\def\Ynothing{} -\def\Yomitfromtoc{} -\def\Ynumbered{% - \ifnum\secno=0 - \putwordChapter@tie \the\chapno - \else \ifnum\subsecno=0 - \putwordSection@tie \the\chapno.\the\secno - \else \ifnum\subsubsecno=0 - \putwordSection@tie \the\chapno.\the\secno.\the\subsecno - \else - \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno - \fi\fi\fi -} -\def\Yappendix{% - \ifnum\secno=0 - \putwordAppendix@tie @char\the\appendixno{}% - \else \ifnum\subsecno=0 - \putwordSection@tie @char\the\appendixno.\the\secno - \else \ifnum\subsubsecno=0 - \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno - \else - \putwordSection@tie - @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno - \fi\fi\fi -} - -% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. -% If its value is nonempty, SUFFIX is output afterward. -% -\def\refx#1#2{% - {% - \indexnofonts - \otherbackslash - \expandafter\global\expandafter\let\expandafter\thisrefX - \csname XR#1\endcsname - }% - \ifx\thisrefX\relax - % If not defined, say something at least. - \angleleft un\-de\-fined\angleright - \iflinks - \ifhavexrefs - \message{\linenumber Undefined cross reference `#1'.}% - \else - \ifwarnedxrefs\else - \global\warnedxrefstrue - \message{Cross reference values unknown; you must run TeX again.}% - \fi - \fi - \fi - \else - % It's defined, so just use it. - \thisrefX - \fi - #2% Output the suffix in any case. -} - -% This is the macro invoked by entries in the aux file. Usually it's -% just a \def (we prepend XR to the control sequence name to avoid -% collisions). But if this is a float type, we have more work to do. -% -\def\xrdef#1#2{% - {% The node name might contain 8-bit characters, which in our current - % implementation are changed to commands like @'e. Don't let these - % mess up the control sequence name. - \indexnofonts - \turnoffactive - \xdef\safexrefname{#1}% - }% - % - \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref - % - % Was that xref control sequence that we just defined for a float? - \expandafter\iffloat\csname XR\safexrefname\endcsname - % it was a float, and we have the (safe) float type in \iffloattype. - \expandafter\let\expandafter\floatlist - \csname floatlist\iffloattype\endcsname - % - % Is this the first time we've seen this float type? - \expandafter\ifx\floatlist\relax - \toks0 = {\do}% yes, so just \do - \else - % had it before, so preserve previous elements in list. - \toks0 = \expandafter{\floatlist\do}% - \fi - % - % Remember this xref in the control sequence \floatlistFLOATTYPE, - % for later use in \listoffloats. - \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0 - {\safexrefname}}% - \fi -} - -% Read the last existing aux file, if any. No error if none exists. -% -\def\tryauxfile{% - \openin 1 \jobname.aux - \ifeof 1 \else - \readdatafile{aux}% - \global\havexrefstrue - \fi - \closein 1 -} - -\def\setupdatafile{% - \catcode`\^^@=\other - \catcode`\^^A=\other - \catcode`\^^B=\other - \catcode`\^^C=\other - \catcode`\^^D=\other - \catcode`\^^E=\other - \catcode`\^^F=\other - \catcode`\^^G=\other - \catcode`\^^H=\other - \catcode`\^^K=\other - \catcode`\^^L=\other - \catcode`\^^N=\other - \catcode`\^^P=\other - \catcode`\^^Q=\other - \catcode`\^^R=\other - \catcode`\^^S=\other - \catcode`\^^T=\other - \catcode`\^^U=\other - \catcode`\^^V=\other - \catcode`\^^W=\other - \catcode`\^^X=\other - \catcode`\^^Z=\other - \catcode`\^^[=\other - \catcode`\^^\=\other - \catcode`\^^]=\other - \catcode`\^^^=\other - \catcode`\^^_=\other - % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. - % in xref tags, i.e., node names. But since ^^e4 notation isn't - % supported in the main text, it doesn't seem desirable. Furthermore, - % that is not enough: for node names that actually contain a ^ - % character, we would end up writing a line like this: 'xrdef {'hat - % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first - % argument, and \hat is not an expandable control sequence. It could - % all be worked out, but why? Either we support ^^ or we don't. - % - % The other change necessary for this was to define \auxhat: - % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter - % and then to call \auxhat in \setq. - % - \catcode`\^=\other - % - % Special characters. Should be turned off anyway, but... - \catcode`\~=\other - \catcode`\[=\other - \catcode`\]=\other - \catcode`\"=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\<=\other - \catcode`\>=\other - \catcode`\$=\other - \catcode`\#=\other - \catcode`\&=\other - \catcode`\%=\other - \catcode`+=\other % avoid \+ for paranoia even though we've turned it off - % - % This is to support \ in node names and titles, since the \ - % characters end up in a \csname. It's easier than - % leaving it active and making its active definition an actual \ - % character. What I don't understand is why it works in the *value* - % of the xrdef. Seems like it should be a catcode12 \, and that - % should not typeset properly. But it works, so I'm moving on for - % now. --karl, 15jan04. - \catcode`\\=\other - % - % Make the characters 128-255 be printing characters. - {% - \count1=128 - \def\loop{% - \catcode\count1=\other - \advance\count1 by 1 - \ifnum \count1<256 \loop \fi - }% - }% - % - % @ is our escape character in .aux files, and we need braces. - \catcode`\{=1 - \catcode`\}=2 - \catcode`\@=0 -} - -\def\readdatafile#1{% -\begingroup - \setupdatafile - \input\jobname.#1 -\endgroup} - - -\message{insertions,} -% including footnotes. - -\newcount \footnoteno - -% The trailing space in the following definition for supereject is -% vital for proper filling; pages come out unaligned when you do a -% pagealignmacro call if that space before the closing brace is -% removed. (Generally, numeric constants should always be followed by a -% space to prevent strange expansion errors.) -\def\supereject{\par\penalty -20000\footnoteno =0 } - -% @footnotestyle is meaningful for info output only. -\let\footnotestyle=\comment - -{\catcode `\@=11 -% -% Auto-number footnotes. Otherwise like plain. -\gdef\footnote{% - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - \global\advance\footnoteno by \@ne - \edef\thisfootno{$^{\the\footnoteno}$}% - % - % In case the footnote comes at the end of a sentence, preserve the - % extra spacing after we do the footnote number. - \let\@sf\empty - \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi - % - % Remove inadvertent blank space before typesetting the footnote number. - \unskip - \thisfootno\@sf - \dofootnote -}% - -% Don't bother with the trickery in plain.tex to not require the -% footnote text as a parameter. Our footnotes don't need to be so general. -% -% Oh yes, they do; otherwise, @ifset (and anything else that uses -% \parseargline) fails inside footnotes because the tokens are fixed when -% the footnote is read. --karl, 16nov96. -% -\gdef\dofootnote{% - \insert\footins\bgroup - % We want to typeset this text as a normal paragraph, even if the - % footnote reference occurs in (for example) a display environment. - % So reset some parameters. - \hsize=\pagewidth - \interlinepenalty\interfootnotelinepenalty - \splittopskip\ht\strutbox % top baseline for broken footnotes - \splitmaxdepth\dp\strutbox - \floatingpenalty\@MM - \leftskip\z@skip - \rightskip\z@skip - \spaceskip\z@skip - \xspaceskip\z@skip - \parindent\defaultparindent - % - \smallfonts \rm - % - % Because we use hanging indentation in footnotes, a @noindent appears - % to exdent this text, so make it be a no-op. makeinfo does not use - % hanging indentation so @noindent can still be needed within footnote - % text after an @example or the like (not that this is good style). - \let\noindent = \relax - % - % Hang the footnote text off the number. Use \everypar in case the - % footnote extends for more than one paragraph. - \everypar = {\hang}% - \textindent{\thisfootno}% - % - % Don't crash into the line above the footnote text. Since this - % expands into a box, it must come within the paragraph, lest it - % provide a place where TeX can split the footnote. - \footstrut - \futurelet\next\fo@t -} -}%end \catcode `\@=11 - -% In case a @footnote appears in a vbox, save the footnote text and create -% the real \insert just after the vbox finished. Otherwise, the insertion -% would be lost. -% Similarly, if a @footnote appears inside an alignment, save the footnote -% text to a box and make the \insert when a row of the table is finished. -% And the same can be done for other insert classes. --kasal, 16nov03. - -% Replace the \insert primitive by a cheating macro. -% Deeper inside, just make sure that the saved insertions are not spilled -% out prematurely. -% -\def\startsavinginserts{% - \ifx \insert\ptexinsert - \let\insert\saveinsert - \else - \let\checkinserts\relax - \fi -} - -% This \insert replacement works for both \insert\footins{foo} and -% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}. -% -\def\saveinsert#1{% - \edef\next{\noexpand\savetobox \makeSAVEname#1}% - \afterassignment\next - % swallow the left brace - \let\temp = -} -\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} -\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} - -\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} - -\def\placesaveins#1{% - \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname - {\box#1}% -} - -% eat @SAVE -- beware, all of them have catcode \other: -{ - \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) - \gdef\gobblesave @SAVE{} -} - -% initialization: -\def\newsaveins #1{% - \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% - \next -} -\def\newsaveinsX #1{% - \csname newbox\endcsname #1% - \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts - \checksaveins #1}% -} - -% initialize: -\let\checkinserts\empty -\newsaveins\footins -\newsaveins\margin - - -% @image. We use the macros from epsf.tex to support this. -% If epsf.tex is not installed and @image is used, we complain. -% -% Check for and read epsf.tex up front. If we read it only at @image -% time, we might be inside a group, and then its definitions would get -% undone and the next image would fail. -\openin 1 = epsf.tex -\ifeof 1 \else - % Do not bother showing banner with epsf.tex v2.7k (available in - % doc/epsf.tex and on ctan). - \def\epsfannounce{\toks0 = }% - \input epsf.tex -\fi -\closein 1 -% -% We will only complain once about lack of epsf.tex. -\newif\ifwarnednoepsf -\newhelp\noepsfhelp{epsf.tex must be installed for images to - work. It is also included in the Texinfo distribution, or you can get - it from ftp://tug.org/tex/epsf.tex.} -% -\def\image#1{% - \ifx\epsfbox\undefined - \ifwarnednoepsf \else - \errhelp = \noepsfhelp - \errmessage{epsf.tex not found, images will be ignored}% - \global\warnednoepsftrue - \fi - \else - \imagexxx #1,,,,,\finish - \fi -} -% -% Arguments to @image: -% #1 is (mandatory) image filename; we tack on .eps extension. -% #2 is (optional) width, #3 is (optional) height. -% #4 is (ignored optional) html alt text. -% #5 is (ignored optional) extension. -% #6 is just the usual extra ignored arg for parsing this stuff. -\newif\ifimagevmode -\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup - \catcode`\^^M = 5 % in case we're inside an example - \normalturnoffactive % allow _ et al. in names - % If the image is by itself, center it. - \ifvmode - \imagevmodetrue - \nobreak\medskip - % Usually we'll have text after the image which will insert - % \parskip glue, so insert it here too to equalize the space - % above and below. - \nobreak\vskip\parskip - \nobreak - \fi - % - % Leave vertical mode so that indentation from an enclosing - % environment such as @quotation is respected. On the other hand, if - % it's at the top level, we don't want the normal paragraph indentation. - \noindent - % - % Output the image. - \ifpdf - \dopdfimage{#1}{#2}{#3}% - \else - % \epsfbox itself resets \epsf?size at each figure. - \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi - \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi - \epsfbox{#1.eps}% - \fi - % - \ifimagevmode \medskip \fi % space after the standalone image -\endgroup} - - -% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables, -% etc. We don't actually implement floating yet, we always include the -% float "here". But it seemed the best name for the future. -% -\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish} - -% There may be a space before second and/or third parameter; delete it. -\def\eatcommaspace#1, {#1,} - -% #1 is the optional FLOATTYPE, the text label for this float, typically -% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, -% this float will not be numbered and cannot be referred to. -% -% #2 is the optional xref label. Also must be present for the float to -% be referable. -% -% #3 is the optional positioning argument; for now, it is ignored. It -% will somehow specify the positions allowed to float to (here, top, bottom). -% -% We keep a separate counter for each FLOATTYPE, which we reset at each -% chapter-level command. -\let\resetallfloatnos=\empty -% -\def\dofloat#1,#2,#3,#4\finish{% - \let\thiscaption=\empty - \let\thisshortcaption=\empty - % - % don't lose footnotes inside @float. - % - % BEWARE: when the floats start float, we have to issue warning whenever an - % insert appears inside a float which could possibly float. --kasal, 26may04 - % - \startsavinginserts - % - % We can't be used inside a paragraph. - \par - % - \vtop\bgroup - \def\floattype{#1}% - \def\floatlabel{#2}% - \def\floatloc{#3}% we do nothing with this yet. - % - \ifx\floattype\empty - \let\safefloattype=\empty - \else - {% - % the floattype might have accents or other special characters, - % but we need to use it in a control sequence name. - \indexnofonts - \turnoffactive - \xdef\safefloattype{\floattype}% - }% - \fi - % - % If label is given but no type, we handle that as the empty type. - \ifx\floatlabel\empty \else - % We want each FLOATTYPE to be numbered separately (Figure 1, - % Table 1, Figure 2, ...). (And if no label, no number.) - % - \expandafter\getfloatno\csname\safefloattype floatno\endcsname - \global\advance\floatno by 1 - % - {% - % This magic value for \lastsection is output by \setref as the - % XREFLABEL-title value. \xrefX uses it to distinguish float - % labels (which have a completely different output format) from - % node and anchor labels. And \xrdef uses it to construct the - % lists of floats. - % - \edef\lastsection{\floatmagic=\safefloattype}% - \setref{\floatlabel}{Yfloat}% - }% - \fi - % - % start with \parskip glue, I guess. - \vskip\parskip - % - % Don't suppress indentation if a float happens to start a section. - \restorefirstparagraphindent -} - -% we have these possibilities: -% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap -% @float Foo,lbl & no caption: Foo 1.1 -% @float Foo & @caption{Cap}: Foo: Cap -% @float Foo & no caption: Foo -% @float ,lbl & Caption{Cap}: 1.1: Cap -% @float ,lbl & no caption: 1.1 -% @float & @caption{Cap}: Cap -% @float & no caption: -% -\def\Efloat{% - \let\floatident = \empty - % - % In all cases, if we have a float type, it comes first. - \ifx\floattype\empty \else \def\floatident{\floattype}\fi - % - % If we have an xref label, the number comes next. - \ifx\floatlabel\empty \else - \ifx\floattype\empty \else % if also had float type, need tie first. - \appendtomacro\floatident{\tie}% - \fi - % the number. - \appendtomacro\floatident{\chaplevelprefix\the\floatno}% - \fi - % - % Start the printed caption with what we've constructed in - % \floatident, but keep it separate; we need \floatident again. - \let\captionline = \floatident - % - \ifx\thiscaption\empty \else - \ifx\floatident\empty \else - \appendtomacro\captionline{: }% had ident, so need a colon between - \fi - % - % caption text. - \appendtomacro\captionline{\scanexp\thiscaption}% - \fi - % - % If we have anything to print, print it, with space before. - % Eventually this needs to become an \insert. - \ifx\captionline\empty \else - \vskip.5\parskip - \captionline - % - % Space below caption. - \vskip\parskip - \fi - % - % If have an xref label, write the list of floats info. Do this - % after the caption, to avoid chance of it being a breakpoint. - \ifx\floatlabel\empty \else - % Write the text that goes in the lof to the aux file as - % \floatlabel-lof. Besides \floatident, we include the short - % caption if specified, else the full caption if specified, else nothing. - {% - \atdummies - % - % since we read the caption text in the macro world, where ^^M - % is turned into a normal character, we have to scan it back, so - % we don't write the literal three characters "^^M" into the aux file. - \scanexp{% - \xdef\noexpand\gtemp{% - \ifx\thisshortcaption\empty - \thiscaption - \else - \thisshortcaption - \fi - }% - }% - \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident - \ifx\gtemp\empty \else : \gtemp \fi}}% - }% - \fi - \egroup % end of \vtop - % - % place the captured inserts - % - % BEWARE: when the floats start floating, we have to issue warning - % whenever an insert appears inside a float which could possibly - % float. --kasal, 26may04 - % - \checkinserts -} - -% Append the tokens #2 to the definition of macro #1, not expanding either. -% -\def\appendtomacro#1#2{% - \expandafter\def\expandafter#1\expandafter{#1#2}% -} - -% @caption, @shortcaption -% -\def\caption{\docaption\thiscaption} -\def\shortcaption{\docaption\thisshortcaption} -\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} -\def\defcaption#1#2{\egroup \def#1{#2}} - -% The parameter is the control sequence identifying the counter we are -% going to use. Create it if it doesn't exist and assign it to \floatno. -\def\getfloatno#1{% - \ifx#1\relax - % Haven't seen this figure type before. - \csname newcount\endcsname #1% - % - % Remember to reset this floatno at the next chap. - \expandafter\gdef\expandafter\resetallfloatnos - \expandafter{\resetallfloatnos #1=0 }% - \fi - \let\floatno#1% -} - -% \setref calls this to get the XREFLABEL-snt value. We want an @xref -% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we -% first read the @float command. -% -\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}% - -% Magic string used for the XREFLABEL-title value, so \xrefX can -% distinguish floats from other xref types. -\def\floatmagic{!!float!!} - -% #1 is the control sequence we are passed; we expand into a conditional -% which is true if #1 represents a float ref. That is, the magic -% \lastsection value which we \setref above. -% -\def\iffloat#1{\expandafter\doiffloat#1==\finish} -% -% #1 is (maybe) the \floatmagic string. If so, #2 will be the -% (safe) float type for this float. We set \iffloattype to #2. -% -\def\doiffloat#1=#2=#3\finish{% - \def\temp{#1}% - \def\iffloattype{#2}% - \ifx\temp\floatmagic -} - -% @listoffloats FLOATTYPE - print a list of floats like a table of contents. -% -\parseargdef\listoffloats{% - \def\floattype{#1}% floattype - {% - % the floattype might have accents or other special characters, - % but we need to use it in a control sequence name. - \indexnofonts - \turnoffactive - \xdef\safefloattype{\floattype}% - }% - % - % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE. - \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax - \ifhavexrefs - % if the user said @listoffloats foo but never @float foo. - \message{\linenumber No `\safefloattype' floats to list.}% - \fi - \else - \begingroup - \leftskip=\tocindent % indent these entries like a toc - \let\do=\listoffloatsdo - \csname floatlist\safefloattype\endcsname - \endgroup - \fi -} - -% This is called on each entry in a list of floats. We're passed the -% xref label, in the form LABEL-title, which is how we save it in the -% aux file. We strip off the -title and look up \XRLABEL-lof, which -% has the text we're supposed to typeset here. -% -% Figures without xref labels will not be included in the list (since -% they won't appear in the aux file). -% -\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish} -\def\listoffloatsdoentry#1-title\finish{{% - % Can't fully expand XR#1-lof because it can contain anything. Just - % pass the control sequence. On the other hand, XR#1-pg is just the - % page number, and we want to fully expand that so we can get a link - % in pdf output. - \toksA = \expandafter{\csname XR#1-lof\endcsname}% - % - % use the same \entry macro we use to generate the TOC and index. - \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}% - \writeentry -}} - - -\message{localization,} - -% @documentlanguage is usually given very early, just after -% @setfilename. If done too late, it may not override everything -% properly. Single argument is the language (de) or locale (de_DE) -% abbreviation. It would be nice if we could set up a hyphenation file. -% -{ - \catcode`\_ = \active - \globaldefs=1 -\parseargdef\documentlanguage{\begingroup - \let_=\normalunderscore % normal _ character for filenames - \tex % read txi-??.tex file in plain TeX. - % Read the file by the name they passed if it exists. - \openin 1 txi-#1.tex - \ifeof 1 - \documentlanguagetrywithoutunderscore{#1_\finish}% - \else - \input txi-#1.tex - \fi - \closein 1 - \endgroup -\endgroup} -} -% -% If they passed de_DE, and txi-de_DE.tex doesn't exist, -% try txi-de.tex. -% -\def\documentlanguagetrywithoutunderscore#1_#2\finish{% - \openin 1 txi-#1.tex - \ifeof 1 - \errhelp = \nolanghelp - \errmessage{Cannot read language file txi-#1.tex}% - \else - \input txi-#1.tex - \fi - \closein 1 -} -% -\newhelp\nolanghelp{The given language definition file cannot be found or -is empty. Maybe you need to install it? In the current directory -should work if nowhere else does.} - -% Set the catcode of characters 128 through 255 to the specified number. -% -\def\setnonasciicharscatcode#1{% - \count255=128 - \loop\ifnum\count255<256 - \global\catcode\count255=#1\relax - \advance\count255 by 1 - \repeat -} - -\def\setnonasciicharscatcodenonglobal#1{% - \count255=128 - \loop\ifnum\count255<256 - \catcode\count255=#1\relax - \advance\count255 by 1 - \repeat -} - -% @documentencoding sets the definition of non-ASCII characters -% according to the specified encoding. -% -\parseargdef\documentencoding{% - % Encoding being declared for the document. - \def\declaredencoding{\csname #1.enc\endcsname}% - % - % Supported encodings: names converted to tokens in order to be able - % to compare them with \ifx. - \def\ascii{\csname US-ASCII.enc\endcsname}% - \def\latnine{\csname ISO-8859-15.enc\endcsname}% - \def\latone{\csname ISO-8859-1.enc\endcsname}% - \def\lattwo{\csname ISO-8859-2.enc\endcsname}% - \def\utfeight{\csname UTF-8.enc\endcsname}% - % - \ifx \declaredencoding \ascii - \asciichardefs - % - \else \ifx \declaredencoding \lattwo - \setnonasciicharscatcode\active - \lattwochardefs - % - \else \ifx \declaredencoding \latone - \setnonasciicharscatcode\active - \latonechardefs - % - \else \ifx \declaredencoding \latnine - \setnonasciicharscatcode\active - \latninechardefs - % - \else \ifx \declaredencoding \utfeight - \setnonasciicharscatcode\active - \utfeightchardefs - % - \else - \message{Unknown document encoding #1, ignoring.}% - % - \fi % utfeight - \fi % latnine - \fi % latone - \fi % lattwo - \fi % ascii -} - -% A message to be logged when using a character that isn't available -% the default font encoding (OT1). -% -\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} - -% Take account of \c (plain) vs. \, (Texinfo) difference. -\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi} - -% First, make active non-ASCII characters in order for them to be -% correctly categorized when TeX reads the replacement text of -% macros containing the character definitions. -\setnonasciicharscatcode\active -% -% Latin1 (ISO-8859-1) character definitions. -\def\latonechardefs{% - \gdef^^a0{~} - \gdef^^a1{\exclamdown} - \gdef^^a2{\missingcharmsg{CENT SIGN}} - \gdef^^a3{{\pounds}} - \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} - \gdef^^a5{\missingcharmsg{YEN SIGN}} - \gdef^^a6{\missingcharmsg{BROKEN BAR}} - \gdef^^a7{\S} - \gdef^^a8{\"{}} - \gdef^^a9{\copyright} - \gdef^^aa{\ordf} - \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}} - \gdef^^ac{$\lnot$} - \gdef^^ad{\-} - \gdef^^ae{\registeredsymbol} - \gdef^^af{\={}} - % - \gdef^^b0{\textdegree} - \gdef^^b1{$\pm$} - \gdef^^b2{$^2$} - \gdef^^b3{$^3$} - \gdef^^b4{\'{}} - \gdef^^b5{$\mu$} - \gdef^^b6{\P} - % - \gdef^^b7{$^.$} - \gdef^^b8{\cedilla\ } - \gdef^^b9{$^1$} - \gdef^^ba{\ordm} - % - \gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}} - \gdef^^bc{$1\over4$} - \gdef^^bd{$1\over2$} - \gdef^^be{$3\over4$} - \gdef^^bf{\questiondown} - % - \gdef^^c0{\`A} - \gdef^^c1{\'A} - \gdef^^c2{\^A} - \gdef^^c3{\~A} - \gdef^^c4{\"A} - \gdef^^c5{\ringaccent A} - \gdef^^c6{\AE} - \gdef^^c7{\cedilla C} - \gdef^^c8{\`E} - \gdef^^c9{\'E} - \gdef^^ca{\^E} - \gdef^^cb{\"E} - \gdef^^cc{\`I} - \gdef^^cd{\'I} - \gdef^^ce{\^I} - \gdef^^cf{\"I} - % - \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}} - \gdef^^d1{\~N} - \gdef^^d2{\`O} - \gdef^^d3{\'O} - \gdef^^d4{\^O} - \gdef^^d5{\~O} - \gdef^^d6{\"O} - \gdef^^d7{$\times$} - \gdef^^d8{\O} - \gdef^^d9{\`U} - \gdef^^da{\'U} - \gdef^^db{\^U} - \gdef^^dc{\"U} - \gdef^^dd{\'Y} - \gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}} - \gdef^^df{\ss} - % - \gdef^^e0{\`a} - \gdef^^e1{\'a} - \gdef^^e2{\^a} - \gdef^^e3{\~a} - \gdef^^e4{\"a} - \gdef^^e5{\ringaccent a} - \gdef^^e6{\ae} - \gdef^^e7{\cedilla c} - \gdef^^e8{\`e} - \gdef^^e9{\'e} - \gdef^^ea{\^e} - \gdef^^eb{\"e} - \gdef^^ec{\`{\dotless i}} - \gdef^^ed{\'{\dotless i}} - \gdef^^ee{\^{\dotless i}} - \gdef^^ef{\"{\dotless i}} - % - \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}} - \gdef^^f1{\~n} - \gdef^^f2{\`o} - \gdef^^f3{\'o} - \gdef^^f4{\^o} - \gdef^^f5{\~o} - \gdef^^f6{\"o} - \gdef^^f7{$\div$} - \gdef^^f8{\o} - \gdef^^f9{\`u} - \gdef^^fa{\'u} - \gdef^^fb{\^u} - \gdef^^fc{\"u} - \gdef^^fd{\'y} - \gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}} - \gdef^^ff{\"y} -} - -% Latin9 (ISO-8859-15) encoding character definitions. -\def\latninechardefs{% - % Encoding is almost identical to Latin1. - \latonechardefs - % - \gdef^^a4{\euro} - \gdef^^a6{\v S} - \gdef^^a8{\v s} - \gdef^^b4{\v Z} - \gdef^^b8{\v z} - \gdef^^bc{\OE} - \gdef^^bd{\oe} - \gdef^^be{\"Y} -} - -% Latin2 (ISO-8859-2) character definitions. -\def\lattwochardefs{% - \gdef^^a0{~} - \gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}} - \gdef^^a2{\u{}} - \gdef^^a3{\L} - \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} - \gdef^^a5{\v L} - \gdef^^a6{\'S} - \gdef^^a7{\S} - \gdef^^a8{\"{}} - \gdef^^a9{\v S} - \gdef^^aa{\cedilla S} - \gdef^^ab{\v T} - \gdef^^ac{\'Z} - \gdef^^ad{\-} - \gdef^^ae{\v Z} - \gdef^^af{\dotaccent Z} - % - \gdef^^b0{\textdegree} - \gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}} - \gdef^^b2{\missingcharmsg{OGONEK}} - \gdef^^b3{\l} - \gdef^^b4{\'{}} - \gdef^^b5{\v l} - \gdef^^b6{\'s} - \gdef^^b7{\v{}} - \gdef^^b8{\cedilla\ } - \gdef^^b9{\v s} - \gdef^^ba{\cedilla s} - \gdef^^bb{\v t} - \gdef^^bc{\'z} - \gdef^^bd{\H{}} - \gdef^^be{\v z} - \gdef^^bf{\dotaccent z} - % - \gdef^^c0{\'R} - \gdef^^c1{\'A} - \gdef^^c2{\^A} - \gdef^^c3{\u A} - \gdef^^c4{\"A} - \gdef^^c5{\'L} - \gdef^^c6{\'C} - \gdef^^c7{\cedilla C} - \gdef^^c8{\v C} - \gdef^^c9{\'E} - \gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}} - \gdef^^cb{\"E} - \gdef^^cc{\v E} - \gdef^^cd{\'I} - \gdef^^ce{\^I} - \gdef^^cf{\v D} - % - \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}} - \gdef^^d1{\'N} - \gdef^^d2{\v N} - \gdef^^d3{\'O} - \gdef^^d4{\^O} - \gdef^^d5{\H O} - \gdef^^d6{\"O} - \gdef^^d7{$\times$} - \gdef^^d8{\v R} - \gdef^^d9{\ringaccent U} - \gdef^^da{\'U} - \gdef^^db{\H U} - \gdef^^dc{\"U} - \gdef^^dd{\'Y} - \gdef^^de{\cedilla T} - \gdef^^df{\ss} - % - \gdef^^e0{\'r} - \gdef^^e1{\'a} - \gdef^^e2{\^a} - \gdef^^e3{\u a} - \gdef^^e4{\"a} - \gdef^^e5{\'l} - \gdef^^e6{\'c} - \gdef^^e7{\cedilla c} - \gdef^^e8{\v c} - \gdef^^e9{\'e} - \gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}} - \gdef^^eb{\"e} - \gdef^^ec{\v e} - \gdef^^ed{\'\i} - \gdef^^ee{\^\i} - \gdef^^ef{\v d} - % - \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}} - \gdef^^f1{\'n} - \gdef^^f2{\v n} - \gdef^^f3{\'o} - \gdef^^f4{\^o} - \gdef^^f5{\H o} - \gdef^^f6{\"o} - \gdef^^f7{$\div$} - \gdef^^f8{\v r} - \gdef^^f9{\ringaccent u} - \gdef^^fa{\'u} - \gdef^^fb{\H u} - \gdef^^fc{\"u} - \gdef^^fd{\'y} - \gdef^^fe{\cedilla t} - \gdef^^ff{\dotaccent{}} -} - -% UTF-8 character definitions. -% -% This code to support UTF-8 is based on LaTeX's utf8.def, with some -% changes for Texinfo conventions. It is included here under the GPL by -% permission from Frank Mittelbach and the LaTeX team. -% -\newcount\countUTFx -\newcount\countUTFy -\newcount\countUTFz - -\gdef\UTFviiiTwoOctets#1#2{\expandafter - \UTFviiiDefined\csname u8:#1\string #2\endcsname} -% -\gdef\UTFviiiThreeOctets#1#2#3{\expandafter - \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname} -% -\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter - \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname} - -\gdef\UTFviiiDefined#1{% - \ifx #1\relax - \message{\linenumber Unicode char \string #1 not defined for Texinfo}% - \else - \expandafter #1% - \fi -} - -\begingroup - \catcode`\~13 - \catcode`\"12 - - \def\UTFviiiLoop{% - \global\catcode\countUTFx\active - \uccode`\~\countUTFx - \uppercase\expandafter{\UTFviiiTmp}% - \advance\countUTFx by 1 - \ifnum\countUTFx < \countUTFy - \expandafter\UTFviiiLoop - \fi} - - \countUTFx = "C2 - \countUTFy = "E0 - \def\UTFviiiTmp{% - \xdef~{\noexpand\UTFviiiTwoOctets\string~}} - \UTFviiiLoop - - \countUTFx = "E0 - \countUTFy = "F0 - \def\UTFviiiTmp{% - \xdef~{\noexpand\UTFviiiThreeOctets\string~}} - \UTFviiiLoop - - \countUTFx = "F0 - \countUTFy = "F4 - \def\UTFviiiTmp{% - \xdef~{\noexpand\UTFviiiFourOctets\string~}} - \UTFviiiLoop -\endgroup - -\begingroup - \catcode`\"=12 - \catcode`\<=12 - \catcode`\.=12 - \catcode`\,=12 - \catcode`\;=12 - \catcode`\!=12 - \catcode`\~=13 - - \gdef\DeclareUnicodeCharacter#1#2{% - \countUTFz = "#1\relax - \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% - \begingroup - \parseXMLCharref - \def\UTFviiiTwoOctets##1##2{% - \csname u8:##1\string ##2\endcsname}% - \def\UTFviiiThreeOctets##1##2##3{% - \csname u8:##1\string ##2\string ##3\endcsname}% - \def\UTFviiiFourOctets##1##2##3##4{% - \csname u8:##1\string ##2\string ##3\string ##4\endcsname}% - \expandafter\expandafter\expandafter\expandafter - \expandafter\expandafter\expandafter - \gdef\UTFviiiTmp{#2}% - \endgroup} - - \gdef\parseXMLCharref{% - \ifnum\countUTFz < "A0\relax - \errhelp = \EMsimple - \errmessage{Cannot define Unicode char value < 00A0}% - \else\ifnum\countUTFz < "800\relax - \parseUTFviiiA,% - \parseUTFviiiB C\UTFviiiTwoOctets.,% - \else\ifnum\countUTFz < "10000\relax - \parseUTFviiiA;% - \parseUTFviiiA,% - \parseUTFviiiB E\UTFviiiThreeOctets.{,;}% - \else - \parseUTFviiiA;% - \parseUTFviiiA,% - \parseUTFviiiA!% - \parseUTFviiiB F\UTFviiiFourOctets.{!,;}% - \fi\fi\fi - } - - \gdef\parseUTFviiiA#1{% - \countUTFx = \countUTFz - \divide\countUTFz by 64 - \countUTFy = \countUTFz - \multiply\countUTFz by 64 - \advance\countUTFx by -\countUTFz - \advance\countUTFx by 128 - \uccode `#1\countUTFx - \countUTFz = \countUTFy} - - \gdef\parseUTFviiiB#1#2#3#4{% - \advance\countUTFz by "#10\relax - \uccode `#3\countUTFz - \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} -\endgroup - -\def\utfeightchardefs{% - \DeclareUnicodeCharacter{00A0}{\tie} - \DeclareUnicodeCharacter{00A1}{\exclamdown} - \DeclareUnicodeCharacter{00A3}{\pounds} - \DeclareUnicodeCharacter{00A8}{\"{ }} - \DeclareUnicodeCharacter{00A9}{\copyright} - \DeclareUnicodeCharacter{00AA}{\ordf} - \DeclareUnicodeCharacter{00AB}{\guillemetleft} - \DeclareUnicodeCharacter{00AD}{\-} - \DeclareUnicodeCharacter{00AE}{\registeredsymbol} - \DeclareUnicodeCharacter{00AF}{\={ }} - - \DeclareUnicodeCharacter{00B0}{\ringaccent{ }} - \DeclareUnicodeCharacter{00B4}{\'{ }} - \DeclareUnicodeCharacter{00B8}{\cedilla{ }} - \DeclareUnicodeCharacter{00BA}{\ordm} - \DeclareUnicodeCharacter{00BB}{\guillemetright} - \DeclareUnicodeCharacter{00BF}{\questiondown} - - \DeclareUnicodeCharacter{00C0}{\`A} - \DeclareUnicodeCharacter{00C1}{\'A} - \DeclareUnicodeCharacter{00C2}{\^A} - \DeclareUnicodeCharacter{00C3}{\~A} - \DeclareUnicodeCharacter{00C4}{\"A} - \DeclareUnicodeCharacter{00C5}{\AA} - \DeclareUnicodeCharacter{00C6}{\AE} - \DeclareUnicodeCharacter{00C7}{\cedilla{C}} - \DeclareUnicodeCharacter{00C8}{\`E} - \DeclareUnicodeCharacter{00C9}{\'E} - \DeclareUnicodeCharacter{00CA}{\^E} - \DeclareUnicodeCharacter{00CB}{\"E} - \DeclareUnicodeCharacter{00CC}{\`I} - \DeclareUnicodeCharacter{00CD}{\'I} - \DeclareUnicodeCharacter{00CE}{\^I} - \DeclareUnicodeCharacter{00CF}{\"I} - - \DeclareUnicodeCharacter{00D1}{\~N} - \DeclareUnicodeCharacter{00D2}{\`O} - \DeclareUnicodeCharacter{00D3}{\'O} - \DeclareUnicodeCharacter{00D4}{\^O} - \DeclareUnicodeCharacter{00D5}{\~O} - \DeclareUnicodeCharacter{00D6}{\"O} - \DeclareUnicodeCharacter{00D8}{\O} - \DeclareUnicodeCharacter{00D9}{\`U} - \DeclareUnicodeCharacter{00DA}{\'U} - \DeclareUnicodeCharacter{00DB}{\^U} - \DeclareUnicodeCharacter{00DC}{\"U} - \DeclareUnicodeCharacter{00DD}{\'Y} - \DeclareUnicodeCharacter{00DF}{\ss} - - \DeclareUnicodeCharacter{00E0}{\`a} - \DeclareUnicodeCharacter{00E1}{\'a} - \DeclareUnicodeCharacter{00E2}{\^a} - \DeclareUnicodeCharacter{00E3}{\~a} - \DeclareUnicodeCharacter{00E4}{\"a} - \DeclareUnicodeCharacter{00E5}{\aa} - \DeclareUnicodeCharacter{00E6}{\ae} - \DeclareUnicodeCharacter{00E7}{\cedilla{c}} - \DeclareUnicodeCharacter{00E8}{\`e} - \DeclareUnicodeCharacter{00E9}{\'e} - \DeclareUnicodeCharacter{00EA}{\^e} - \DeclareUnicodeCharacter{00EB}{\"e} - \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}} - \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}} - \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}} - \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}} - - \DeclareUnicodeCharacter{00F1}{\~n} - \DeclareUnicodeCharacter{00F2}{\`o} - \DeclareUnicodeCharacter{00F3}{\'o} - \DeclareUnicodeCharacter{00F4}{\^o} - \DeclareUnicodeCharacter{00F5}{\~o} - \DeclareUnicodeCharacter{00F6}{\"o} - \DeclareUnicodeCharacter{00F8}{\o} - \DeclareUnicodeCharacter{00F9}{\`u} - \DeclareUnicodeCharacter{00FA}{\'u} - \DeclareUnicodeCharacter{00FB}{\^u} - \DeclareUnicodeCharacter{00FC}{\"u} - \DeclareUnicodeCharacter{00FD}{\'y} - \DeclareUnicodeCharacter{00FF}{\"y} - - \DeclareUnicodeCharacter{0100}{\=A} - \DeclareUnicodeCharacter{0101}{\=a} - \DeclareUnicodeCharacter{0102}{\u{A}} - \DeclareUnicodeCharacter{0103}{\u{a}} - \DeclareUnicodeCharacter{0106}{\'C} - \DeclareUnicodeCharacter{0107}{\'c} - \DeclareUnicodeCharacter{0108}{\^C} - \DeclareUnicodeCharacter{0109}{\^c} - \DeclareUnicodeCharacter{010A}{\dotaccent{C}} - \DeclareUnicodeCharacter{010B}{\dotaccent{c}} - \DeclareUnicodeCharacter{010C}{\v{C}} - \DeclareUnicodeCharacter{010D}{\v{c}} - \DeclareUnicodeCharacter{010E}{\v{D}} - - \DeclareUnicodeCharacter{0112}{\=E} - \DeclareUnicodeCharacter{0113}{\=e} - \DeclareUnicodeCharacter{0114}{\u{E}} - \DeclareUnicodeCharacter{0115}{\u{e}} - \DeclareUnicodeCharacter{0116}{\dotaccent{E}} - \DeclareUnicodeCharacter{0117}{\dotaccent{e}} - \DeclareUnicodeCharacter{011A}{\v{E}} - \DeclareUnicodeCharacter{011B}{\v{e}} - \DeclareUnicodeCharacter{011C}{\^G} - \DeclareUnicodeCharacter{011D}{\^g} - \DeclareUnicodeCharacter{011E}{\u{G}} - \DeclareUnicodeCharacter{011F}{\u{g}} - - \DeclareUnicodeCharacter{0120}{\dotaccent{G}} - \DeclareUnicodeCharacter{0121}{\dotaccent{g}} - \DeclareUnicodeCharacter{0124}{\^H} - \DeclareUnicodeCharacter{0125}{\^h} - \DeclareUnicodeCharacter{0128}{\~I} - \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}} - \DeclareUnicodeCharacter{012A}{\=I} - \DeclareUnicodeCharacter{012B}{\={\dotless{i}}} - \DeclareUnicodeCharacter{012C}{\u{I}} - \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}} - - \DeclareUnicodeCharacter{0130}{\dotaccent{I}} - \DeclareUnicodeCharacter{0131}{\dotless{i}} - \DeclareUnicodeCharacter{0132}{IJ} - \DeclareUnicodeCharacter{0133}{ij} - \DeclareUnicodeCharacter{0134}{\^J} - \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}} - \DeclareUnicodeCharacter{0139}{\'L} - \DeclareUnicodeCharacter{013A}{\'l} - - \DeclareUnicodeCharacter{0141}{\L} - \DeclareUnicodeCharacter{0142}{\l} - \DeclareUnicodeCharacter{0143}{\'N} - \DeclareUnicodeCharacter{0144}{\'n} - \DeclareUnicodeCharacter{0147}{\v{N}} - \DeclareUnicodeCharacter{0148}{\v{n}} - \DeclareUnicodeCharacter{014C}{\=O} - \DeclareUnicodeCharacter{014D}{\=o} - \DeclareUnicodeCharacter{014E}{\u{O}} - \DeclareUnicodeCharacter{014F}{\u{o}} - - \DeclareUnicodeCharacter{0150}{\H{O}} - \DeclareUnicodeCharacter{0151}{\H{o}} - \DeclareUnicodeCharacter{0152}{\OE} - \DeclareUnicodeCharacter{0153}{\oe} - \DeclareUnicodeCharacter{0154}{\'R} - \DeclareUnicodeCharacter{0155}{\'r} - \DeclareUnicodeCharacter{0158}{\v{R}} - \DeclareUnicodeCharacter{0159}{\v{r}} - \DeclareUnicodeCharacter{015A}{\'S} - \DeclareUnicodeCharacter{015B}{\'s} - \DeclareUnicodeCharacter{015C}{\^S} - \DeclareUnicodeCharacter{015D}{\^s} - \DeclareUnicodeCharacter{015E}{\cedilla{S}} - \DeclareUnicodeCharacter{015F}{\cedilla{s}} - - \DeclareUnicodeCharacter{0160}{\v{S}} - \DeclareUnicodeCharacter{0161}{\v{s}} - \DeclareUnicodeCharacter{0162}{\cedilla{t}} - \DeclareUnicodeCharacter{0163}{\cedilla{T}} - \DeclareUnicodeCharacter{0164}{\v{T}} - - \DeclareUnicodeCharacter{0168}{\~U} - \DeclareUnicodeCharacter{0169}{\~u} - \DeclareUnicodeCharacter{016A}{\=U} - \DeclareUnicodeCharacter{016B}{\=u} - \DeclareUnicodeCharacter{016C}{\u{U}} - \DeclareUnicodeCharacter{016D}{\u{u}} - \DeclareUnicodeCharacter{016E}{\ringaccent{U}} - \DeclareUnicodeCharacter{016F}{\ringaccent{u}} - - \DeclareUnicodeCharacter{0170}{\H{U}} - \DeclareUnicodeCharacter{0171}{\H{u}} - \DeclareUnicodeCharacter{0174}{\^W} - \DeclareUnicodeCharacter{0175}{\^w} - \DeclareUnicodeCharacter{0176}{\^Y} - \DeclareUnicodeCharacter{0177}{\^y} - \DeclareUnicodeCharacter{0178}{\"Y} - \DeclareUnicodeCharacter{0179}{\'Z} - \DeclareUnicodeCharacter{017A}{\'z} - \DeclareUnicodeCharacter{017B}{\dotaccent{Z}} - \DeclareUnicodeCharacter{017C}{\dotaccent{z}} - \DeclareUnicodeCharacter{017D}{\v{Z}} - \DeclareUnicodeCharacter{017E}{\v{z}} - - \DeclareUnicodeCharacter{01C4}{D\v{Z}} - \DeclareUnicodeCharacter{01C5}{D\v{z}} - \DeclareUnicodeCharacter{01C6}{d\v{z}} - \DeclareUnicodeCharacter{01C7}{LJ} - \DeclareUnicodeCharacter{01C8}{Lj} - \DeclareUnicodeCharacter{01C9}{lj} - \DeclareUnicodeCharacter{01CA}{NJ} - \DeclareUnicodeCharacter{01CB}{Nj} - \DeclareUnicodeCharacter{01CC}{nj} - \DeclareUnicodeCharacter{01CD}{\v{A}} - \DeclareUnicodeCharacter{01CE}{\v{a}} - \DeclareUnicodeCharacter{01CF}{\v{I}} - - \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}} - \DeclareUnicodeCharacter{01D1}{\v{O}} - \DeclareUnicodeCharacter{01D2}{\v{o}} - \DeclareUnicodeCharacter{01D3}{\v{U}} - \DeclareUnicodeCharacter{01D4}{\v{u}} - - \DeclareUnicodeCharacter{01E2}{\={\AE}} - \DeclareUnicodeCharacter{01E3}{\={\ae}} - \DeclareUnicodeCharacter{01E6}{\v{G}} - \DeclareUnicodeCharacter{01E7}{\v{g}} - \DeclareUnicodeCharacter{01E8}{\v{K}} - \DeclareUnicodeCharacter{01E9}{\v{k}} - - \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}} - \DeclareUnicodeCharacter{01F1}{DZ} - \DeclareUnicodeCharacter{01F2}{Dz} - \DeclareUnicodeCharacter{01F3}{dz} - \DeclareUnicodeCharacter{01F4}{\'G} - \DeclareUnicodeCharacter{01F5}{\'g} - \DeclareUnicodeCharacter{01F8}{\`N} - \DeclareUnicodeCharacter{01F9}{\`n} - \DeclareUnicodeCharacter{01FC}{\'{\AE}} - \DeclareUnicodeCharacter{01FD}{\'{\ae}} - \DeclareUnicodeCharacter{01FE}{\'{\O}} - \DeclareUnicodeCharacter{01FF}{\'{\o}} - - \DeclareUnicodeCharacter{021E}{\v{H}} - \DeclareUnicodeCharacter{021F}{\v{h}} - - \DeclareUnicodeCharacter{0226}{\dotaccent{A}} - \DeclareUnicodeCharacter{0227}{\dotaccent{a}} - \DeclareUnicodeCharacter{0228}{\cedilla{E}} - \DeclareUnicodeCharacter{0229}{\cedilla{e}} - \DeclareUnicodeCharacter{022E}{\dotaccent{O}} - \DeclareUnicodeCharacter{022F}{\dotaccent{o}} - - \DeclareUnicodeCharacter{0232}{\=Y} - \DeclareUnicodeCharacter{0233}{\=y} - \DeclareUnicodeCharacter{0237}{\dotless{j}} - - \DeclareUnicodeCharacter{1E02}{\dotaccent{B}} - \DeclareUnicodeCharacter{1E03}{\dotaccent{b}} - \DeclareUnicodeCharacter{1E04}{\udotaccent{B}} - \DeclareUnicodeCharacter{1E05}{\udotaccent{b}} - \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}} - \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}} - \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}} - \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}} - \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}} - \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}} - \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}} - \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}} - - \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}} - \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}} - - \DeclareUnicodeCharacter{1E20}{\=G} - \DeclareUnicodeCharacter{1E21}{\=g} - \DeclareUnicodeCharacter{1E22}{\dotaccent{H}} - \DeclareUnicodeCharacter{1E23}{\dotaccent{h}} - \DeclareUnicodeCharacter{1E24}{\udotaccent{H}} - \DeclareUnicodeCharacter{1E25}{\udotaccent{h}} - \DeclareUnicodeCharacter{1E26}{\"H} - \DeclareUnicodeCharacter{1E27}{\"h} - - \DeclareUnicodeCharacter{1E30}{\'K} - \DeclareUnicodeCharacter{1E31}{\'k} - \DeclareUnicodeCharacter{1E32}{\udotaccent{K}} - \DeclareUnicodeCharacter{1E33}{\udotaccent{k}} - \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}} - \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}} - \DeclareUnicodeCharacter{1E36}{\udotaccent{L}} - \DeclareUnicodeCharacter{1E37}{\udotaccent{l}} - \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}} - \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}} - \DeclareUnicodeCharacter{1E3E}{\'M} - \DeclareUnicodeCharacter{1E3F}{\'m} - - \DeclareUnicodeCharacter{1E40}{\dotaccent{M}} - \DeclareUnicodeCharacter{1E41}{\dotaccent{m}} - \DeclareUnicodeCharacter{1E42}{\udotaccent{M}} - \DeclareUnicodeCharacter{1E43}{\udotaccent{m}} - \DeclareUnicodeCharacter{1E44}{\dotaccent{N}} - \DeclareUnicodeCharacter{1E45}{\dotaccent{n}} - \DeclareUnicodeCharacter{1E46}{\udotaccent{N}} - \DeclareUnicodeCharacter{1E47}{\udotaccent{n}} - \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}} - \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}} - - \DeclareUnicodeCharacter{1E54}{\'P} - \DeclareUnicodeCharacter{1E55}{\'p} - \DeclareUnicodeCharacter{1E56}{\dotaccent{P}} - \DeclareUnicodeCharacter{1E57}{\dotaccent{p}} - \DeclareUnicodeCharacter{1E58}{\dotaccent{R}} - \DeclareUnicodeCharacter{1E59}{\dotaccent{r}} - \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}} - \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}} - \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}} - \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}} - - \DeclareUnicodeCharacter{1E60}{\dotaccent{S}} - \DeclareUnicodeCharacter{1E61}{\dotaccent{s}} - \DeclareUnicodeCharacter{1E62}{\udotaccent{S}} - \DeclareUnicodeCharacter{1E63}{\udotaccent{s}} - \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}} - \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}} - \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}} - \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}} - \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}} - \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}} - - \DeclareUnicodeCharacter{1E7C}{\~V} - \DeclareUnicodeCharacter{1E7D}{\~v} - \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}} - \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}} - - \DeclareUnicodeCharacter{1E80}{\`W} - \DeclareUnicodeCharacter{1E81}{\`w} - \DeclareUnicodeCharacter{1E82}{\'W} - \DeclareUnicodeCharacter{1E83}{\'w} - \DeclareUnicodeCharacter{1E84}{\"W} - \DeclareUnicodeCharacter{1E85}{\"w} - \DeclareUnicodeCharacter{1E86}{\dotaccent{W}} - \DeclareUnicodeCharacter{1E87}{\dotaccent{w}} - \DeclareUnicodeCharacter{1E88}{\udotaccent{W}} - \DeclareUnicodeCharacter{1E89}{\udotaccent{w}} - \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}} - \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}} - \DeclareUnicodeCharacter{1E8C}{\"X} - \DeclareUnicodeCharacter{1E8D}{\"x} - \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}} - \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}} - - \DeclareUnicodeCharacter{1E90}{\^Z} - \DeclareUnicodeCharacter{1E91}{\^z} - \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}} - \DeclareUnicodeCharacter{1E93}{\udotaccent{z}} - \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}} - \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}} - \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}} - \DeclareUnicodeCharacter{1E97}{\"t} - \DeclareUnicodeCharacter{1E98}{\ringaccent{w}} - \DeclareUnicodeCharacter{1E99}{\ringaccent{y}} - - \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}} - \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}} - - \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}} - \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}} - \DeclareUnicodeCharacter{1EBC}{\~E} - \DeclareUnicodeCharacter{1EBD}{\~e} - - \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}} - \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}} - \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}} - \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}} - - \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}} - \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}} - - \DeclareUnicodeCharacter{1EF2}{\`Y} - \DeclareUnicodeCharacter{1EF3}{\`y} - \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}} - - \DeclareUnicodeCharacter{1EF8}{\~Y} - \DeclareUnicodeCharacter{1EF9}{\~y} - - \DeclareUnicodeCharacter{2013}{--} - \DeclareUnicodeCharacter{2014}{---} - \DeclareUnicodeCharacter{2018}{\quoteleft} - \DeclareUnicodeCharacter{2019}{\quoteright} - \DeclareUnicodeCharacter{201A}{\quotesinglbase} - \DeclareUnicodeCharacter{201C}{\quotedblleft} - \DeclareUnicodeCharacter{201D}{\quotedblright} - \DeclareUnicodeCharacter{201E}{\quotedblbase} - \DeclareUnicodeCharacter{2022}{\bullet} - \DeclareUnicodeCharacter{2026}{\dots} - \DeclareUnicodeCharacter{2039}{\guilsinglleft} - \DeclareUnicodeCharacter{203A}{\guilsinglright} - \DeclareUnicodeCharacter{20AC}{\euro} - - \DeclareUnicodeCharacter{2192}{\expansion} - \DeclareUnicodeCharacter{21D2}{\result} - - \DeclareUnicodeCharacter{2212}{\minus} - \DeclareUnicodeCharacter{2217}{\point} - \DeclareUnicodeCharacter{2261}{\equiv} -}% end of \utfeightchardefs - - -% US-ASCII character definitions. -\def\asciichardefs{% nothing need be done - \relax -} - -% Make non-ASCII characters printable again for compatibility with -% existing Texinfo documents that may use them, even without declaring a -% document encoding. -% -\setnonasciicharscatcode \other - - -\message{formatting,} - -\newdimen\defaultparindent \defaultparindent = 15pt - -\chapheadingskip = 15pt plus 4pt minus 2pt -\secheadingskip = 12pt plus 3pt minus 2pt -\subsecheadingskip = 9pt plus 2pt minus 2pt - -% Prevent underfull vbox error messages. -\vbadness = 10000 - -% Don't be so finicky about underfull hboxes, either. -\hbadness = 2000 - -% Following George Bush, get rid of widows and orphans. -\widowpenalty=10000 -\clubpenalty=10000 - -% Use TeX 3.0's \emergencystretch to help line breaking, but if we're -% using an old version of TeX, don't do anything. We want the amount of -% stretch added to depend on the line length, hence the dependence on -% \hsize. We call this whenever the paper size is set. -% -\def\setemergencystretch{% - \ifx\emergencystretch\thisisundefined - % Allow us to assign to \emergencystretch anyway. - \def\emergencystretch{\dimen0}% - \else - \emergencystretch = .15\hsize - \fi -} - -% Parameters in order: 1) textheight; 2) textwidth; -% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip; -% 7) physical page height; 8) physical page width. -% -% We also call \setleading{\textleading}, so the caller should define -% \textleading. The caller should also set \parskip. -% -\def\internalpagesizes#1#2#3#4#5#6#7#8{% - \voffset = #3\relax - \topskip = #6\relax - \splittopskip = \topskip - % - \vsize = #1\relax - \advance\vsize by \topskip - \outervsize = \vsize - \advance\outervsize by 2\topandbottommargin - \pageheight = \vsize - % - \hsize = #2\relax - \outerhsize = \hsize - \advance\outerhsize by 0.5in - \pagewidth = \hsize - % - \normaloffset = #4\relax - \bindingoffset = #5\relax - % - \ifpdf - \pdfpageheight #7\relax - \pdfpagewidth #8\relax - % if we don't reset these, they will remain at "1 true in" of - % whatever layout pdftex was dumped with. - \pdfhorigin = 1 true in - \pdfvorigin = 1 true in - \fi - % - \setleading{\textleading} - % - \parindent = \defaultparindent - \setemergencystretch -} - -% @letterpaper (the default). -\def\letterpaper{{\globaldefs = 1 - \parskip = 3pt plus 2pt minus 1pt - \textleading = 13.2pt - % - % If page is nothing but text, make it come out even. - \internalpagesizes{607.2pt}{6in}% that's 46 lines - {\voffset}{.25in}% - {\bindingoffset}{36pt}% - {11in}{8.5in}% -}} - -% Use @smallbook to reset parameters for 7x9.25 trim size. -\def\smallbook{{\globaldefs = 1 - \parskip = 2pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.5in}{5in}% - {-.2in}{0in}% - {\bindingoffset}{16pt}% - {9.25in}{7in}% - % - \lispnarrowing = 0.3in - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = .5cm -}} - -% Use @smallerbook to reset parameters for 6x9 trim size. -% (Just testing, parameters still in flux.) -\def\smallerbook{{\globaldefs = 1 - \parskip = 1.5pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.4in}{4.8in}% - {-.2in}{-.4in}% - {0pt}{14pt}% - {9in}{6in}% - % - \lispnarrowing = 0.25in - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = .4cm -}} - -% Use @afourpaper to print on European A4 paper. -\def\afourpaper{{\globaldefs = 1 - \parskip = 3pt plus 2pt minus 1pt - \textleading = 13.2pt - % - % Double-side printing via postscript on Laserjet 4050 - % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. - % To change the settings for a different printer or situation, adjust - % \normaloffset until the front-side and back-side texts align. Then - % do the same for \bindingoffset. You can set these for testing in - % your texinfo source file like this: - % @tex - % \global\normaloffset = -6mm - % \global\bindingoffset = 10mm - % @end tex - \internalpagesizes{673.2pt}{160mm}% that's 51 lines - {\voffset}{\hoffset}% - {\bindingoffset}{44pt}% - {297mm}{210mm}% - % - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = 5mm -}} - -% Use @afivepaper to print on European A5 paper. -% From romildo@urano.iceb.ufop.br, 2 July 2000. -% He also recommends making @example and @lisp be small. -\def\afivepaper{{\globaldefs = 1 - \parskip = 2pt plus 1pt minus 0.1pt - \textleading = 12.5pt - % - \internalpagesizes{160mm}{120mm}% - {\voffset}{\hoffset}% - {\bindingoffset}{8pt}% - {210mm}{148mm}% - % - \lispnarrowing = 0.2in - \tolerance = 800 - \hfuzz = 1.2pt - \contentsrightmargin = 0pt - \defbodyindent = 2mm - \tableindent = 12mm -}} - -% A specific text layout, 24x15cm overall, intended for A4 paper. -\def\afourlatex{{\globaldefs = 1 - \afourpaper - \internalpagesizes{237mm}{150mm}% - {\voffset}{4.6mm}% - {\bindingoffset}{7mm}% - {297mm}{210mm}% - % - % Must explicitly reset to 0 because we call \afourpaper. - \globaldefs = 0 -}} - -% Use @afourwide to print on A4 paper in landscape format. -\def\afourwide{{\globaldefs = 1 - \afourpaper - \internalpagesizes{241mm}{165mm}% - {\voffset}{-2.95mm}% - {\bindingoffset}{7mm}% - {297mm}{210mm}% - \globaldefs = 0 -}} - -% @pagesizes TEXTHEIGHT[,TEXTWIDTH] -% Perhaps we should allow setting the margins, \topskip, \parskip, -% and/or leading, also. Or perhaps we should compute them somehow. -% -\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} -\def\pagesizesyyy#1,#2,#3\finish{{% - \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi - \globaldefs = 1 - % - \parskip = 3pt plus 2pt minus 1pt - \setleading{\textleading}% - % - \dimen0 = #1\relax - \advance\dimen0 by \voffset - % - \dimen2 = \hsize - \advance\dimen2 by \normaloffset - % - \internalpagesizes{#1}{\hsize}% - {\voffset}{\normaloffset}% - {\bindingoffset}{44pt}% - {\dimen0}{\dimen2}% -}} - -% Set default to letter. -% -\letterpaper - - -\message{and turning on texinfo input format.} - -% Define macros to output various characters with catcode for normal text. -\catcode`\"=\other -\catcode`\~=\other -\catcode`\^=\other -\catcode`\_=\other -\catcode`\|=\other -\catcode`\<=\other -\catcode`\>=\other -\catcode`\+=\other -\catcode`\$=\other -\def\normaldoublequote{"} -\def\normaltilde{~} -\def\normalcaret{^} -\def\normalunderscore{_} -\def\normalverticalbar{|} -\def\normalless{<} -\def\normalgreater{>} -\def\normalplus{+} -\def\normaldollar{$}%$ font-lock fix - -% This macro is used to make a character print one way in \tt -% (where it can probably be output as-is), and another way in other fonts, -% where something hairier probably needs to be done. -% -% #1 is what to print if we are indeed using \tt; #2 is what to print -% otherwise. Since all the Computer Modern typewriter fonts have zero -% interword stretch (and shrink), and it is reasonable to expect all -% typewriter fonts to have this, we can check that font parameter. -% -\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi} - -% Same as above, but check for italic font. Actually this also catches -% non-italic slanted fonts since it is impossible to distinguish them from -% italic fonts. But since this is only used by $ and it uses \sl anyway -% this is not a problem. -\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi} - -% Turn off all special characters except @ -% (and those which the user can use as if they were ordinary). -% Most of these we simply print from the \tt font, but for some, we can -% use math or other variants that look better in normal text. - -\catcode`\"=\active -\def\activedoublequote{{\tt\char34}} -\let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt\char126}} -\chardef\hat=`\^ -\catcode`\^=\active -\def^{{\tt \hat}} - -\catcode`\_=\active -\def_{\ifusingtt\normalunderscore\_} -\let\realunder=_ -% Subroutine for the previous macro. -\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } - -\catcode`\|=\active -\def|{{\tt\char124}} -\chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} -\chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -\catcode`\$=\active -\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix - -% If a .fmt file is being used, characters that might appear in a file -% name cannot be active until we have parsed the command line. -% So turn them off again, and have \everyjob (or @setfilename) turn them on. -% \otherifyactive is called near the end of this file. -\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} - -% Used sometimes to turn off (effectively) the active characters even after -% parsing them. -\def\turnoffactive{% - \normalturnoffactive - \otherbackslash -} - -\catcode`\@=0 - -% \backslashcurfont outputs one backslash character in current font, -% as in \char`\\. -\global\chardef\backslashcurfont=`\\ -\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work - -% \realbackslash is an actual character `\' with catcode other, and -% \doublebackslash is two of them (for the pdf outlines). -{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} - -% In texinfo, backslash is an active character; it prints the backslash -% in fixed width font. -\catcode`\\=\active -@def@normalbackslash{{@tt@backslashcurfont}} -% On startup, @fixbackslash assigns: -% @let \ = @normalbackslash - -% \rawbackslash defines an active \ to do \backslashcurfont. -% \otherbackslash defines an active \ to be a literal `\' character with -% catcode other. -@gdef@rawbackslash{@let\=@backslashcurfont} -@gdef@otherbackslash{@let\=@realbackslash} - -% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of -% the literal character `\'. -% -@def@normalturnoffactive{% - @let\=@normalbackslash - @let"=@normaldoublequote - @let~=@normaltilde - @let^=@normalcaret - @let_=@normalunderscore - @let|=@normalverticalbar - @let<=@normalless - @let>=@normalgreater - @let+=@normalplus - @let$=@normaldollar %$ font-lock fix - @unsepspaces -} - -% Make _ and + \other characters, temporarily. -% This is canceled by @fixbackslash. -@otherifyactive - -% If a .fmt file is being used, we don't want the `\input texinfo' to show up. -% That is what \eatinput is for; after that, the `\' should revert to printing -% a backslash. -% -@gdef@eatinput input texinfo{@fixbackslash} -@global@let\ = @eatinput - -% On the other hand, perhaps the file did not have a `\input texinfo'. Then -% the first `\' in the file would cause an error. This macro tries to fix -% that, assuming it is called before the first `\' could plausibly occur. -% Also turn back on active characters that might appear in the input -% file name, in case not using a pre-dumped format. -% -@gdef@fixbackslash{% - @ifx\@eatinput @let\ = @normalbackslash @fi - @catcode`+=@active - @catcode`@_=@active -} - -% Say @foo, not \foo, in error messages. -@escapechar = `@@ - -% These look ok in all fonts, so just make them not special. -@catcode`@& = @other -@catcode`@# = @other -@catcode`@% = @other - - -@c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) -@c page-delimiter: "^\\\\message" -@c time-stamp-start: "def\\\\texinfoversion{" -@c time-stamp-format: "%:y-%02m-%02d.%02H" -@c time-stamp-end: "}" -@c End: - -@c vim:sw=2: - -@ignore - arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 -@end ignore diff --git a/Build/source/utils/texinfo/doc/texinfo.txi b/Build/source/utils/texinfo/doc/texinfo.txi deleted file mode 100644 index e3478242da6..00000000000 --- a/Build/source/utils/texinfo/doc/texinfo.txi +++ /dev/null @@ -1,21203 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi -@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi. - -@c Everything between the start/end of header lines will be passed by -@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of -@c header' node for more info. -@c %**start of header - -@c makeinfo and texinfo.tex ignore all text before @setfilename. -@c -@c Ordinarily, the setfilename argument ends with .info. But -@c texinfo.info-13 is too long for 14-character filesystems. -@setfilename texinfo - -@c Automake automatically updates version.texi to @set VERSION and -@c @set UPDATED to appropriate values. -@include version.texi -@settitle GNU Texinfo @value{VERSION} - -@c Define a new index for options. -@defcodeindex op -@c Put everything except function (command, in this case) names in one -@c index (arbitrarily chosen to be the concept index). -@syncodeindex op cp -@syncodeindex vr cp -@syncodeindex pg cp - -@paragraphindent 2 -@c finalout - -@comment %**end of header - -@copying -This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), -a documentation system that can produce both online information and a -printed manual from a single source. - -Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@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. -* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. -* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. -* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. -* makeinfo: (texinfo)Invoking makeinfo. 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, -@c so this same source can be used for other paper sizes as well. -@c smallbook -@c set smallbook -@c @@clear smallbook - -@c If you like blank pages, add through texi2dvi -t. -@c setchapternewpage odd - -@c Currently undocumented command, 5 December 1993: -@c nwnode (Same as node, but no warnings; for `makeinfo'.) - - -@shorttitlepage GNU Texinfo - -@titlepage -@title Texinfo -@subtitle The GNU Documentation Format -@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} - -@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 -@insertcopying - -@sp 1 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-67-1 @c for version 4.0, September 1999. -@c ISBN 1-882114-65-5 is for version 3.12, March 1998. -@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. -@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995. - -@sp 1 -Cover art by Etienne Suvasa. -@end titlepage - - -@summarycontents -@contents - - -@ifnottex -@node Top -@top Texinfo - -This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), -a documentation system that can produce both online information and a -printed manual from a single source. - -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. - -@end ifnottex - -@menu -* Copying Conditions:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: Using the GNU Emacs Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* Structuring:: Creating chapters, sections, appendices, etc. -* Nodes:: Writing nodes, the basic unit of Texinfo. -* Menus:: Writing menus. -* Cross References:: Writing cross references. -* Marking Text:: Marking words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: Block quotations, examples, etc. -* Lists and Tables:: Itemized or numbered lists, and tables. -* Special Displays:: Floating figures and footnotes. -* Indices:: Creating indices. -* Insertions:: Inserting @@-signs, braces, etc. -* Breaks:: Forcing or preventing line and page breaks. -* Definition Commands:: Describing functions and the like uniformly. -* Conditionals:: Specifying text for only some output cases. -* Internationalization:: Supporting languages other than English. -* Defining New Texinfo Commands:: User-defined macros and aliases. -* Hardcopy:: Output for paper, with @TeX{}. -* Creating and Installing Info Files:: Details on Info output. -* Generating HTML:: Details on HTML output. - -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo Files:: Complete examples, including full texts. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* GNU Free Documentation License::Copying this manual. -* Command and Variable Index:: A menu containing commands and variables. -* General Index:: A menu covering many topics. - -@detailmenu - --- The Detailed Node Listing --- - -Overview of Texinfo - -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* 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. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. - -Using Texinfo Mode - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - -Updating Nodes and Menus - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - -Beginning a Texinfo File - -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -Texinfo File Header - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. - -Document Permissions - -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. - -Title and Copyright Pages - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. - -The `Top' Node and Master Menu - -* Top Node Example:: -* Master Menu Parts:: - -Global Document Commands - -* documentdescription:: Document summary for the HTML output. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* firstparagraphindent:: Suppress indentation of the first paragraph. -* exampleindent:: Specify environment indentation. - -Ending a Texinfo File - -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* File End:: How to mark the end of a file. - -Chapter Structuring - -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. - -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. - -The @code{@@node} Command - -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. - -Menus - -* Menu Location:: Menus go at the ends of short nodes. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. - -Cross References - -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. - -@code{@@xref} - -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. - -Marking Words and Phrases - -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. - -Indicating Definitions, Commands, etc. - -* Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: A literal sequence of characters. -* verb:: A verbatim 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. -* abbr:: Indicating abbreviations. -* acronym:: Indicating acronyms. -* indicateurl:: Indicating a World Wide Web reference. -* email:: Indicating 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. - -Quotations and Examples - -* Block Enclosing Commands:: Different constructs for different purposes. -* quotation:: Writing a quotation. -* example:: Writing an example in a fixed-width font. -* verbatim:: Writing a verbatim example. -* verbatiminclude:: Including a file verbatim. -* lisp:: Illustrating Lisp code. -* small:: Examples in a smaller font. -* display:: Writing an example in the current font. -* format:: Writing an example without narrowed margins. -* exdent:: Undo indentation on a line. -* flushleft & flushright:: Pushing text flush left or flush right. -* noindent:: Preventing paragraph indentation. -* indent:: Forcing paragraph indentation. -* cartouche:: Drawing rounded rectangles around examples. - -Lists and Tables - -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. - -Making a Two-column Table - -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. - -@code{@@multitable}: Multi-column Tables - -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. - -Special Displays - -* Floats:: Figures, tables, and the like. -* Images:: Including graphics and images. -* Footnotes:: Writing footnotes. - -Floats - -* float:: Producing floating material. -* caption shortcaption:: Specifying descriptions for floats. -* listoffloats:: A table of contents for floats. - -Inserting Images - -* Image Syntax:: -* Image Scaling:: - -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - -Indices - -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entries. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. - -Combining Indices - -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - -Special Insertions - -* Atsign Braces Comma:: Inserting @@ and @{@} and ,. -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Inserting Quotation Marks:: How to insert quotation marks. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* euro:: How to insert the Euro currency symbol. -* pounds:: How to insert the pounds currency symbol. -* textdegree:: How to insert the degrees symbol. -* minus:: How to insert a minus sign. -* geq leq:: How to insert greater/less-than-or-equal signs. -* math:: How to format a mathematical expression. -* Click Sequences:: Inserting GUI usage sequences. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. - -Inserting @@ and @{@} and @comma{} - -* Inserting an Atsign:: -* Inserting Braces:: -* Inserting a Comma:: - -Inserting Space - -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* frenchspacing:: Specifying end-of-sentence spacing. -* dmn:: How to format a dimension. - -Inserting Ellipsis and Bullets - -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. - -Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} - -* tex:: The @TeX{} logos. -* copyright symbol:: The copyright symbol (c in a circle). -* registered symbol:: The registered symbol (R in a circle). - -Glyphs for Examples - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - -Glyphs Summary - -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: - -Forcing and Preventing Breaks - -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* - and hyphenation:: Helping @TeX{} with hyphenation points. -* allowcodebreaks:: Controlling line breaks within @@code text. -* w:: Preventing unwanted line breaks in text. -* tie:: Inserting an unbreakable but varying space. -* sp:: Inserting blank lines. -* page:: Forcing the start of a new page. -* group:: Preventing unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. - -Definition Commands - -* Def Cmd Template:: Writing descriptions using definition commands. -* Def Cmd Continuation Lines:: Continuing the heading over source lines. -* Optional Arguments:: Handling optional and repeated arguments. -* deffnx:: Group two or more `first' lines. -* Def Cmds in Detail:: Reference for all the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: An example. - -The Definition Commands - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Data Types:: The definition command for data types. -* Abstract Objects:: Commands for object-oriented programming. - -Object-Oriented Programming - -* Variables: Object-Oriented Variables. -* Methods: Object-Oriented Methods. - -Conditionally Visible Text - -* Conditional Commands:: Text for a given format. -* Conditional Not Commands:: Text for any format other than a given one. -* Raw Formatter Commands:: Using raw formatter commands. -* set clear value:: Variable tests and substitutions. -* Conditional Nesting:: Using conditionals inside conditionals. - -@code{@@set}, @code{@@clear}, and @code{@@value} - -* set value:: Expand a flag variable to a string. -* ifset ifclear:: Format a region if a flag is set. -* value Example:: An easy way to update edition information. - -Internationalization - -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. - -Defining New Texinfo Commands - -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. - -Formatting and Printing 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. -* 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{}. -* 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 A4 or A5 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. -* Obtaining TeX:: How to Obtain @TeX{}. - -Creating and Installing Info Files - -* Creating an Info File:: -* Installing an Info File:: - -Creating an Info File - -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* 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. - -Installing an Info File - -* 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. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: @code{install-info} options. - -Generating HTML - -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: Influencing HTML output with Cascading Style Sheets. -* HTML Xref:: Cross-references in HTML output. - -HTML Cross-references - -* Link Basics: HTML Xref Link Basics. -* Node Expansion: HTML Xref Node Name Expansion. -* Command Expansion: HTML Xref Command Expansion. -* 8-bit Expansion: HTML Xref 8-bit Character Expansion. -* Mismatch: HTML Xref Mismatch. - -@@-Command List - -* Command Syntax:: General syntax for varieties of @@-commands. - -Sample Texinfo Files - -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: - -GNU Free Documentation License - -Include Files - -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. - -Page Headings - -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. - -Formatting Mistakes - -* makeinfo Preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with @TeX{} formatting. -* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. - -Finding Badly Referenced Nodes - -* Using Info-validate:: How to run @code{Info-validate}. -* 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 - - -@node Copying Conditions -@unnumbered Texinfo Copying Conditions -@cindex Copying conditions -@cindex Conditions for copying Texinfo - -The programs currently being distributed that relate to Texinfo include -@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. -These programs are @dfn{free}; this means that everyone is free to use -them and free to redistribute them on a free basis. The Texinfo-related -programs are not in the public domain; they are copyrighted and there -are restrictions on their distribution, but these restrictions are -designed to permit everything that a good cooperating citizen would want -to do. What is not allowed is to try to prevent others from further -sharing any version of these programs that they might get from you. - -Specifically, we want to make sure that you have the right to give away -copies of the programs that relate to Texinfo, that you receive source -code or else can get it if you want it, that you can change these -programs or use pieces of them in new free programs, and that you know -you can do these things. - -To make sure that everyone has such rights, we have to forbid you to -deprive anyone else of these rights. For example, if you distribute -copies of the Texinfo related programs, you must give the recipients all -the rights that you have. You must make sure that they, too, receive or -can get the source code. And you must tell them their rights. - -Also, for our own protection, we must make certain that everyone finds -out that there is no warranty for the programs that relate to Texinfo. -If these programs are modified by someone else and passed on, we want -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. - -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. This manual specifically is covered by -the GNU Free Documentation License (@pxref{GNU Free Documentation -License}). - - -@node Overview -@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. - -@menu -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* 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. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. -@end menu - - -@node Reporting Bugs -@section Reporting Bugs - -@cindex Bugs, reporting -@cindex Suggestions for Texinfo, making -@cindex Reporting bugs -We welcome bug reports and suggestions for any aspect of the Texinfo system, -programs, documentation, installation, anything. 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 and operating system names and versions. -@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 any unusual options you gave to @command{configure}. -@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. - -@cindex Patches, contributing -Patches are most welcome; if possible, please make them with -@samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging -Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, -emacs, The GNU Emacs Manual}), and follow the existing coding style. - - -@node Using Texinfo -@section Using Texinfo - -@cindex Using Texinfo in general -@cindex Texinfo, introduction to -@cindex Introduction to Texinfo - -Using Texinfo, you can create a printed document (via the @TeX{} -typesetting system) the normal features of a book, including chapters, -sections, cross references, and indices. From the same Texinfo source -file, you can create an Info file with special features to make -documentation browsing easy. You can also create from that same -source file an HTML output file suitable for use with a web browser, -or an XML file. See the next section (@pxref{Output Formats}) for -details and the exact commands to generate output from the source. - -@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 format -A Texinfo source file is a plain ASCII file containing text -interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) -that tell the typesetting and formatting programs what to do. You can -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}.) - -You can use Texinfo to create both online 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}. - - -@node Output Formats -@section Output Formats -@cindex Output formats -@cindex Back-end output formats - -Here is a brief overview of the output formats currently supported by -Texinfo. - -@table @asis -@item Info -@cindex Info output -(Generated via @command{makeinfo}.) This format is essentially a -plain text transliteration of the Texinfo source. It adds a few -control characters to separate nodes and provide navigational -information for menus, cross-references, indices, and so on. See the -next section (@pxref{Info Files}) for more details on this format. -The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}), -and the standalone @command{info} program (@pxref{Top -,, Info Standalone, info-stnd, GNU Info}), among others, can read these -files. @xref{Creating and Installing Info Files}. - -@item Plain text -@cindex Plain text output -(Generated via @command{makeinfo --no-headers}.) This is almost the -same as Info output, except the navigational control characters are -omitted. Also, standard output is used by default. - -@item HTML -@cindex HTML output -@cindex W3 consortium -@cindex Mozilla -@cindex Lynx -@cindex Emacs-W3 -(Generated via @command{makeinfo --html}.) This is the Hyper Text -Markup Language that has become the most commonly used language for -writing documents on the World Wide Web. Web browsers, such as -Mozilla, Lynx, and Emacs-W3, can render this language online. There -are many versions of HTML; @command{makeinfo} tries to use a subset -of the language that can be interpreted by any common browser. For -details of the HTML language and much related information, see -@uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. - -@item DVI -@cindex DVI output -@pindex dvips -@pindex xdvi -(Generated via @command{texi2dvi}.) This DeVice Independent binary -format is output by the @TeX{} typesetting program -(@uref{http://tug.org}). This is then read by a DVI `driver', which -writes the actual device-specific commands that can be viewed or -printed, notably Dvips for translation to PostScript (@pxref{Invoking -Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display -(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. - -Be aware that the Texinfo language is very different from and much -stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}. -For more information on @TeX{} in general, please see the book -@cite{@TeX{} for the Impatient}, available from -@uref{http://savannah.gnu.org/projects/teximpatient}. - -@item PDF -@cindex PDF output -@cindex Beebe, Nelson -@pindex pdftex -(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This -format was developed by Adobe Systems for portable document -interchange, based on their previous PostScript language. It can -represent the exact appearance of a document, including fonts and -graphics, and supporting arbitrary scaling. It is intended to be -platform-independent and easily viewable, among other design goals; -@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has -some background. Texinfo uses the @command{pdftex} program, a variant -of @TeX{}, to output PDF; see -@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. - -@item XML -@cindex XML output -@cindex DTD, for Texinfo XML -@pindex texinfo.dtd -(Generated via @command{makeinfo --xml}.) XML is a generic syntax -specification usable for any sort of content (see, for example, -@uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output, -unlike all the formats above, interprets very little of the Texinfo -source. Rather, it merely translates the Texinfo markup commands into -XML syntax, for processing by further XML tools. The particular -syntax output is defined in the file @file{texinfo.dtd} included in -the Texinfo source distribution. - -@item Docbook -@cindex Docbook output -(Generated via @command{makeinfo --docbook}.) This is an XML-based -format developed some years ago, primarily for technical -documentation. It therefore bears some resemblance, in broad -outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want -to convert from Docbook @emph{to} Texinfo, please see -@uref{http://docbook2X.sourceforge.net}. - -@end table - -@cindex Man page output, not supported -From time to time, proposals are made to generate traditional Unix man -pages from Texinfo source. However, because man pages have a very -strict conventional format, generating a good man page requires a -completely different source than the typical Texinfo applications of -writing a good user tutorial and/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 -Man pages still have their place, and if you wish to support them, you -may find the program @command{help2man} to 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 programs in -the Texinfo distribution. It is GNU software written by Brendan -O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}. - -@cindex Output formats, supporting more -@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. - - -@node Info Files -@section Info Files -@cindex Info files - -An Info file is a Texinfo file formatted so that the Info documentation -reading program can operate on it. (@code{makeinfo} -and @code{texinfo-format-buffer} are two commands that convert a Texinfo file -into an Info file.) - -Info files are divided into pieces called @dfn{nodes}, each of which -contains the discussion of one topic. Each node has a name, and -contains both text for the user to read and pointers to other nodes, -which are identified by their names. The Info program displays one node -at a time, and provides commands with which the user can move to other -related nodes. - -@xref{Top,,, info, GNU Info}, for more information about using Info. - -Each node of an Info file may have any number of child nodes that -describe subtopics of the node's topic. The names of child -nodes are listed in a @dfn{menu} within the parent node; this -allows you to use certain Info commands to move to one of the child -nodes. Generally, an Info file is organized like a book. If a node -is at the logical level of a chapter, its child nodes are at the level -of sections; likewise, the child nodes of sections are at the level -of subsections. - -All the children of any one parent are linked together in a -bidirectional chain of `Next' and `Previous' pointers. The `Next' -pointer provides a link to the next section, and the `Previous' pointer -provides a link to the previous section. This means that all the nodes -that are at the level of sections within a chapter are linked together. -Normally the order in this chain is the same as the order of the -children in the parent's menu. Each child node records the parent node -name as its `Up' pointer. The last child has no `Next' pointer, and the -first child has the parent both as its `Previous' and as its `Up' -pointer.@footnote{In some documents, the first child has no `Previous' -pointer. Occasionally, the last child has the node name of the next -following higher level node as its `Next' pointer.} - -The book-like structuring of an Info file into nodes that correspond -to chapters, sections, and the like is a matter of convention, not a -requirement. The `Up', `Previous', and `Next' pointers of a node can -point to any other nodes, and a menu can contain any other nodes. -Thus, the node structure can be any directed graph. But it is usually -more comprehensible to follow a structure that corresponds to the -structure of chapters and sections in a printed book or report.@refill - -In addition to menus and to `Next', `Previous', and `Up' pointers, Info -provides pointers of another kind, called references, that can be -sprinkled throughout the text. This is usually the best way to -represent links that do not fit a hierarchical structure.@refill - -Usually, you will design a document so that its nodes match the -structure of chapters and sections in the printed output. But -occasionally there are times when this is not right for the material -being discussed. Therefore, Texinfo uses separate commands to specify -the node structure for the Info file and the section structure for the -printed output.@refill - -Generally, you enter an Info file through a node that by convention is -named `Top'. This node normally contains just a brief summary of the -file's purpose, and a large menu through which the rest of the file is -reached. From this node, you can either traverse the file -systematically by going from node to node, or you can go to a specific -node listed in the main menu, or you can search the index menus and then -go directly to the node that has the information you want. Alternatively, -with the standalone Info program, you can specify specific menu items on -the command line (@pxref{Top,,, info, Info}). - -If you want to read through an Info file in sequence, as if it were a -printed manual, you can hit @key{SPC} repeatedly, or you get the whole -file with the advanced Info command @kbd{g *}. (@inforef{Advanced, -Advanced Info commands, info}.)@refill - -@c !!! dir file may be located in one of many places: -@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/info -@c /usr/local/lib/info -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 URIs of any kind. - - -@node Printed Books -@section Printed Books -@cindex Printed book and manual characteristics -@cindex Manual characteristics, printed -@cindex Book characteristics, printed -@cindex Texinfo printed book characteristics -@cindex Characteristics, printed books or manuals - -@cindex Knuth, Donald -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.} - -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, -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 -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 -@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 -the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. - -In the United States, documents are most often printed on 8.5 inch by 11 -inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But -you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by -235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper -(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, , -Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4 -Paper}.) - -By changing the parameters in @file{texinfo.tex}, you can change the -size of the printed document. In addition, you can change the style in -which the printed document is formatted; for example, you can change the -sizes and fonts used, the amount of indentation for each paragraph, the -degree to which words are hyphenated, and the like. By changing the -specifications, you can make a book look dignified, old and serious, or -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. -(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information -about @TeX{}.)@refill - -@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 -@ref{Obtaining TeX, , How to Obtain @TeX{}}. - - -@node Formatting Commands -@section @@-commands -@cindex @@-commands -@cindex Formatting commands - -In a Texinfo file, the commands that tell @TeX{} how to typeset the -printed manual and tell @code{makeinfo} and -@code{texinfo-format-buffer} how to create an Info file are preceded -by @samp{@@}; they are called @dfn{@@-commands}. For example, -@code{@@node} is the command to indicate a node and @code{@@chapter} -is the command to indicate the start of a chapter.@refill - -@quotation Note -Almost all @@ command names are entirely lower case. -@end quotation - -The Texinfo @@-commands are a strictly limited set of constructs. The -strict limits make it possible for Texinfo files to be understood both -by @TeX{} and by the code that converts them into Info files. You can -display Info files on any terminal that displays alphabetic and -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: - -@itemize @bullet -@item -Write a command such as @code{@@quotation} at the beginning of a line as -the only text on the line. (@code{@@quotation} begins an indented -environment.) - -@item -Write a command such as @code{@@chapter} at the beginning of a line -followed by the command's arguments, in this case the chapter title, on -the rest of the line. (@code{@@chapter} creates chapter titles.)@refill - -@item -Write a command such as @code{@@dots@{@}} wherever you wish but usually -within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill - -@item -Write a command such as @code{@@code@{@var{sample-code}@}} wherever you -wish (but usually within a sentence) with its argument, -@var{sample-code} in this example, between the braces. (@code{@@code} -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, 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. -@end itemize - -@noindent -@cindex Braces, when to use -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 -non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; -they do not need braces.@refill - -As you gain experience with Texinfo, you will rapidly learn how to -write the different commands: the different ways to write commands -actually make it easier to write and read Texinfo files than if all -commands followed exactly the same syntax. @xref{Command Syntax, , -@@-Command Syntax}, for all the details. - - -@node Conventions -@section General Syntactic Conventions -@cindex General syntactic conventions -@cindex Syntactic conventions -@cindex Conventions, syntactic -@cindex Characters, basic input - -This section describes the general conventions used in all Texinfo documents. - -@itemize @bullet -@item -@cindex Source files, characters used -All printable 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, while -@samp{@{} and @samp{@}} are used to surround arguments to 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{@@@}}. - -@item -@cindex Paragraph separator -@cindex Blank lines, as paragraph separator -@cindex Newlines, as blank lines -Separate paragraphs with one or more blank lines. Currently Texinfo -only recognizes newline characters as end of line, not the CRLF -sequence used on some systems; so a @dfn{blank line} means exactly two -consecutive newlines. Sometimes blank lines are useful or convenient -in other cases as well; you can use the @code{@@noindent} to inhibit -paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}). - -@item -Texinfo supports the usual quotation marks used in English, and -quotation marks used in other languages, please see @ref{Inserting -Quotation Marks}. - -@item -@cindex Multiple dashes in source -@cindex Dashes in source -@cindex Hyphens in source, two or three in a row -@cindex Em dash, producing -@cindex En dash, producing -Use three hyphens in a row, @samp{---}, to produce a long dash---like -this (called an @dfn{em dash}), used for punctuation in sentences. -Use two hyphens, @samp{--}, to produce a medium dash (called an -@dfn{en dash}), used primarily for numeric ranges, as in ``June -25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen -used in compound words. For display on the screen, Info reduces three -hyphens to two and two hyphens to one (not transitively!). Of course, -any number of hyphens in the source remain as they are in literal -contexts, such as @code{@@code} and @code{@@example}. - -@item -@cindex Tabs; don't use! -@strong{Caution:} Last, do not use tab characters in a Texinfo file -(except in verbatim modes)! @TeX{} uses variable-width fonts, which -means that it is impractical at best to define a tab to work in all -circumstances. Consequently, @TeX{} treats tabs like single spaces, -and that is not what they look like in the source. Furthermore, -@code{makeinfo} does nothing special with tabs, and thus a tab -character in your input file will usually appear differently in the -output. - -@noindent -To avoid this problem, Texinfo mode in GNU Emacs inserts -multiple spaces when you press the @key{TAB} key. Also, you can run -@code{untabify} in Emacs to convert tabs in a region to multiple -spaces, or use the @code{unexpand} command from the shell. - -@end itemize - - -@node Comments -@section Comments - -@cindex Comments -@findex comment -@findex c @r{(comment)} - -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 -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 @code{@@c} in the middle of -a line, and only the text that follows after the @code{@@comment} or -@code{@@c} command does not appear; but some commands, such as -@code{@@settitle} and @code{@@setfilename}, work on a whole line. You -cannot use @code{@@comment} or @code{@@c} in a line beginning with such -a command. - -@cindex Ignored text -@cindex Unprocessed text -@findex ignore -You can write long stretches of text that will not appear in either -the Info file or the printed manual by using the @code{@@ignore} and -@code{@@end ignore} commands. Write each of these commands on a line -of its own, starting each command at the beginning of the line. Text -between these two commands does not appear in the processed output. -You can use @code{@@ignore} and @code{@@end ignore} for writing -comments. - -Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or -@code{@@ifclear} conditions is ignored in the sense that it will not -contribute to the formatted output. However, @TeX{} and makeinfo must -still parse the ignored text, in order to understand when to @emph{stop} -ignoring text from the source file; that means that you may still get -error messages if you have invalid Texinfo commands within ignored text. - - -@node Minimum -@section What a Texinfo File Must Have -@cindex Minimal Texinfo file (requirements) -@cindex Must have in Texinfo file -@cindex Required in Texinfo file -@cindex Texinfo file minimum - -By convention, the name of a Texinfo file ends with (in order of -preference) one of the extensions @file{.texinfo}, @file{.texi}, -@file{.txi}, or @file{.tex}. The longer extensions are preferred since -they describe 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 @strong{must} begin with lines like this: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -@noindent -The contents of the file follow this beginning, and then you -@strong{must} end a Texinfo file with a line like this: - -@example -@@bye -@end example - -@findex \input @r{(raw @TeX{} startup)} -@noindent -Here's an explanation: - -@itemize @bullet -@item -The @samp{\input texinfo} line tells @TeX{} to use the -@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo -@@-commands into @TeX{} typesetting commands. (Note the use of the -backslash, @samp{\}; this is correct for @TeX{}.) - -@item -The @code{@@setfilename} line provides a name for the Info file and -tells @TeX{} to open auxiliary files. @strong{All text before -@code{@@setfilename} is ignored!} - -@item -The @code{@@settitle} line specifies a title for the page headers (or -footers) of the printed manual, and the default document description for -the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle} -is optional---if you don't mind your document being titled `Untitled'. - -@item -The @code{@@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. - -@end itemize - -Typically, 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: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@@c %**end of header -@end group -@end example - -@noindent -In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into -Texinfo mode when you edit the file. - -The @code{@@c} lines which surround the @code{@@setfilename} and -@code{@@settitle} lines are optional, but you need them in order to -run @TeX{} or Info on just part of the file. (@xref{Start of Header}.) - -Furthermore, you will usually provide a Texinfo file with a title page, -indices, and the like, all of which are explained in this manual. 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. - - -@node Six Parts -@section Six Parts of a Texinfo File - -Generally, a Texinfo file contains more than the minimal beginning and -end described in the previous section---it usually contains the six -parts listed below. These are described fully in the following sections. - -@table @r -@item 1. Header -The @dfn{Header} names the file, tells @TeX{} which definitions file to -use, and other such housekeeping tasks. - -@item 2. Summary and Copyright -The @dfn{Summary and Copyright} segment describes the document and -contains the copyright notice and copying permissions. This is done -with the @code{@@copying} command. - -@item 3. Title and Copyright -The @dfn{Title and Copyright} segment contains the title and copyright -pages for the printed manual. The segment must be enclosed between -@code{@@titlepage} and @code{@@end titlepage} commands. The title and -copyright page appear only in the printed manual. - -@item 4. `Top' Node and Master Menu -The `Top' node starts off the online output; it does not appear in the -printed manual. We recommend including the copying permissions here as -well as the segments above. And it contains at least a top-level menu -listing the chapters, and possibly a @dfn{Master Menu} listing all the -nodes in the entire document. - -@item 5. Body -The @dfn{Body} of the document is typically structured like a -traditional book or encyclopedia, but it may be free form. - -@item 6. End -The @dfn{End} segment may contain commands for printing indices, and -closes with the @code{@@bye} command on a line of its own. -@end table - - -@node Short Sample -@section A Short Sample Texinfo File -@cindex Sample Texinfo file, with comments - -Here is a very short but complete Texinfo file, in the six conventional -parts enumerated in the previous section, so you can see how Texinfo -source appears in practice. The first three parts of the file, from -@samp{\input texinfo} through to @samp{@@end titlepage}, look more -intimidating than they are: most of the material is standard -boilerplate; when writing a manual, you simply change the names as -appropriate. - -@xref{Beginning a File}, for full documentation on the commands listed -here. @xref{GNU Sample Texts}, for the full texts to be used in GNU -manuals. - -In the following, the sample text is @emph{indented}; comments on it are -not. The complete file, without interspersed comments, is shown in -@ref{Short Sample Texinfo File}. - -@subheading Part 1: Header - -@noindent -The header does not appear in either the Info file or the -printed output. It sets various parameters, including the -name of the Info file and the title used in the header. - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Manual 1.0 -@@c %**end of header -@end group -@end example - -@subheading Part 2: Summary Description and Copyright - -@noindent -A real manual includes more text here, according to the license under -which it is distributed. @xref{GNU Sample Texts}. - -@example -@group -@@copying -This is a short example of a complete Texinfo file, version 1.0. - -Copyright @@copyright@{@} 2005 Free Software Foundation, Inc. -@@end copying -@end group -@end example - -@subheading Part 3: Titlepage, Contents, Copyright - -@noindent -The titlepage segment does not appear in the online output, only in the -printed manual. We use the @code{@@insertcopying} command to -include the permission text from the previous section, instead of -writing it out again; it is output on the back of the title page. The -@code{@@contents} command generates a table of contents. - -@example -@group -@@titlepage -@@title Sample Title -@end group - -@group -@@c The following two commands start the copyright page. -@@page -@@vskip 0pt plus 1filll -@@insertcopying -@@end titlepage -@end group - -@@c Output the table of contents at the beginning. -@@contents -@end example - -@subheading Part 4: `Top' Node and Master Menu - -@noindent -The `Top' node contains the master menu for the Info file. Since the -printed manual uses a table of contents rather than a menu, it -excludes the `Top' node. We repeat the short description from the -beginning of the @samp{@@copying} text, but there's no need to repeat -the copyright information, so we don't use @samp{@@insertcopying} here. -The @samp{@@top} command itself helps @command{makeinfo} determine the -relationships between nodes. - -@example -@@ifnottex -@@node Top -@@top Short Sample - -This is a short sample Texinfo file. -@@end ifnottex - -@group -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Index:: Complete index. -@@end menu -@end group -@end example - - -@subheading Part 5: The Body of the Document - -@noindent -The body segment contains all the text of the document, but not the -indices or table of contents. This example illustrates a node and a -chapter containing an enumerated list. - -@example -@group -@@node First Chapter -@@chapter First Chapter - -@@cindex chapter, first -@end group - -@group -This is the first chapter. -@@cindex index entry, another -@end group - -@group -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate -@end group -@end example - - -@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, and the @code{@@bye} command that marks -the end of the document. - -@example -@group -@@node Index -@@unnumbered Index -@end group - -@group -@@printindex cp - -@@bye -@end group -@end example - - -@subheading Some Results - -Here is what the contents of the first chapter of the sample look like: - -@sp 1 -@need 700 -@quotation -This is the first chapter. - -Here is a numbered list. - -@enumerate -@item -This is the first item. - -@item -This is the second item. -@end enumerate -@end quotation - - -@node History -@section History - -@cindex Stallman, Richard M. -@cindex Chassell, Robert J. -@cindex Fox, Brian -@cindex Berry, Karl -Richard M. Stallman invented the Texinfo format, wrote the initial -processors, and created Edition 1.0 of this manual. Robert@tie{}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} programs. Karl Berry has -continued maintenance since Texinfo 3.8 (manual 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 the -indefatigable Eli Zaretskii and Andreas Schwab, who have provided -patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn, -tirelessly recorded and reported mistakes and obscurities. Zack -Weinberg did the impossible by implementing the macro syntax in -@file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her -frequent reviews of nearly similar editions. 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 -@cindex Texinfo history -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. Much more -consequentially, it strove to describe document contents rather than -formatting, an idea wholeheartedly adopted by Texinfo. - -@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{}. The earliest Bo@TeX{} version seems to have been -0.02 on October 31, 1984. - -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 online and -as printed hard copy. - - -@node Texinfo Mode -@chapter Using Texinfo Mode -@cindex Texinfo mode -@cindex Mode, using Texinfo -@cindex GNU Emacs -@cindex Emacs - -You may edit a Texinfo file with any text editor you choose. A Texinfo -file is no different from any other ASCII file. However, GNU Emacs -comes with a special mode, called Texinfo mode, that provides Emacs -commands and tools to help ease your work. - -This chapter describes features of GNU Emacs' Texinfo mode but not any -features of the Texinfo formatting language. So if you are reading this -manual straight through from the beginning, you may want to skim through -this chapter briefly and come back to it after reading succeeding -chapters which describe the Texinfo formatting language in detail. - -@menu -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. -@end menu - -@node Texinfo Mode Overview -@section Texinfo Mode Overview - -Texinfo mode provides special features for working with Texinfo files. -You can: - -@itemize @bullet -@item -Insert frequently used @@-commands. @refill - -@item -Automatically create @code{@@node} lines. - -@item -Show the structure of a Texinfo source file.@refill - -@item -Automatically create or update the `Next', -`Previous', and `Up' pointers of a node. - -@item -Automatically create or update menus.@refill - -@item -Automatically create a master menu.@refill - -@item -Format a part or all of a file for Info.@refill - -@item -Typeset and print part or all of a file.@refill -@end itemize - -Perhaps the two most helpful features are those for inserting frequently -used @@-commands and for creating node pointers and menus.@refill - -@node Emacs Editing -@section The Usual GNU Emacs Editing Commands - -In most cases, the usual Text mode commands work the same in Texinfo -mode as they do in Text mode. Texinfo mode adds new editing commands -and tools to GNU Emacs' general purpose editing features. The major -difference concerns filling. In Texinfo mode, the paragraph -separation variable and syntax table are redefined so that Texinfo -commands that should be on lines of their own are not inadvertently -included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) -command will refill a paragraph but not mix an indexing command on a -line adjacent to it into the paragraph.@refill - -In addition, Texinfo mode sets the @code{page-delimiter} variable to -the value of @code{texinfo-chapter-level-regexp}; by default, this is -a regular expression matching the commands for chapters and their -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 n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, -The GNU Emacs 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} -extension. Also, Emacs switches to Texinfo mode -when you visit a -file that has @samp{-*-texinfo-*-} in its first line. If ever you are -in another mode and wish to switch to Texinfo mode, type @code{M-x -texinfo-mode}.@refill - -Like all other Emacs features, you can customize or enhance Texinfo -mode as you wish. In particular, the keybindings are very easy to -change. The keybindings described here are the default or standard -ones.@refill - -@node Inserting -@comment node-name, next, previous, up -@section Inserting Frequently Used Commands -@cindex Inserting frequently used commands -@cindex Frequently used commands, inserting -@cindex Commands, inserting them - -Texinfo mode provides commands to insert various frequently used -@@-commands into the buffer. You can use these commands to save -keystrokes.@refill - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command:@refill - -@table @kbd -@item C-c C-c c -@itemx M-x texinfo-insert-@@code -@findex texinfo-insert-@@code -Insert @code{@@code@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c d -@itemx M-x texinfo-insert-@@dfn -@findex texinfo-insert-@@dfn -Insert @code{@@dfn@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c e -@itemx M-x texinfo-insert-@@end -@findex texinfo-insert-@@end -Insert @code{@@end} and attempt to insert the correct following word, -such as @samp{example} or @samp{table}. (This command does not handle -nested lists correctly, but inserts the word appropriate to the -immediately preceding list.)@refill - -@item C-c C-c i -@itemx M-x texinfo-insert-@@item -@findex texinfo-insert-@@item -Insert @code{@@item} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c k -@itemx M-x texinfo-insert-@@kbd -@findex texinfo-insert-@@kbd -Insert @code{@@kbd@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c n -@itemx M-x texinfo-insert-@@node -@findex texinfo-insert-@@node -Insert @code{@@node} and a comment line -listing the sequence for the `Next', -`Previous', and `Up' nodes. -Leave point after the @code{@@node}.@refill - -@item C-c C-c o -@itemx M-x texinfo-insert-@@noindent -@findex texinfo-insert-@@noindent -Insert @code{@@noindent} and put the -cursor at the beginning of the next line.@refill - -@item C-c C-c s -@itemx M-x texinfo-insert-@@samp -@findex texinfo-insert-@@samp -Insert @code{@@samp@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c t -@itemx M-x texinfo-insert-@@table -@findex texinfo-insert-@@table -Insert @code{@@table} followed by a @key{SPC} -and leave the cursor after the @key{SPC}.@refill - -@item C-c C-c v -@itemx M-x texinfo-insert-@@var -@findex texinfo-insert-@@var -Insert @code{@@var@{@}} and put the -cursor between the braces.@refill - -@item C-c C-c x -@itemx M-x texinfo-insert-@@example -@findex texinfo-insert-@@example -Insert @code{@@example} and put the -cursor at the beginning of the next line.@refill - -@c M-@{ was the binding for texinfo-insert-braces; -@c in Emacs 19, backward-paragraph will take this binding. -@item C-c C-c @{ -@itemx M-x texinfo-insert-braces -@findex texinfo-insert-braces -Insert @code{@{@}} and put the cursor between the braces.@refill - -@item C-c @} -@itemx C-c ] -@itemx M-x up-list -@findex up-list -Move from between a pair of braces forward past the closing brace. -Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which -is, however, more mnemonic; hence the two keybindings. (Also, you can -move out from between braces by typing @kbd{C-f}.)@refill -@end table - -To put a command such as @w{@code{@@code@{@dots{}@}}} around an -@emph{existing} word, position the cursor in front of the word and type -@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. -The value of the prefix argument tells Emacs how many words following -point to include between braces---@samp{1} for one word, @samp{2} for -two words, and so on. Use a negative argument to enclose the previous -word or words. If you do not specify a prefix argument, Emacs inserts -the @@-command string and positions the cursor between the braces. This -feature works only for those @@-commands that operate on a word or words -within one line, such as @code{@@kbd} and @code{@@var}.@refill - -This set of insert commands was created after analyzing the frequency -with which different @@-commands are used in the @cite{GNU Emacs -Manual} and the @cite{GDB Manual}. If you wish to add your own insert -commands, you can bind a keyboard macro to a key, use abbreviations, -or extend the code in @file{texinfo.el}.@refill - -@findex texinfo-start-menu-description -@cindex Menu description, start -@cindex Description for menu, start -@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert -command that works differently from the other insert commands. It -inserts a node's section or chapter title in the space for the -description in a menu entry line. (A menu entry has three parts, the -entry name, the node name, and the description. Only the node name is -required, but a description helps explain what the node is about. -@xref{Menu Parts, , The Parts of a Menu}.)@refill - -To use @code{texinfo-start-menu-description}, position point in a menu -entry line and type @kbd{C-c C-c C-d}. The command looks for and copies -the title that goes with the node name, and inserts the title as a -description; it positions point at beginning of the inserted text so you -can edit it. The function does not insert the title if the menu entry -line already contains a description.@refill - -This command is only an aid to writing descriptions; it does not do the -whole job. You must edit the inserted text since a title tends to use -the same words as a node name but a useful description uses different -words.@refill - -@node Showing the Structure -@comment node-name, next, previous, up -@section Showing the Section Structure of a File -@cindex Showing the section structure of a file -@cindex Section structure of a file, showing it -@cindex Structure of a file, showing it -@cindex Outline of file structure, showing it -@cindex Contents-like outline of file structure -@cindex File section structure, showing it -@cindex Texinfo file section structure, showing it - -You can show the section structure of a Texinfo file by using the -@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command -shows the section structure of a Texinfo file by listing the lines -that begin with the @@-commands for @code{@@chapter}, -@code{@@section}, and the like. It constructs what amounts -to a table of contents. These lines are displayed in another buffer -called the @samp{*Occur*} buffer. In that buffer, 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.@refill - -@table @kbd -@item C-c C-s -@itemx M-x texinfo-show-structure -@findex texinfo-show-structure -Show the @code{@@chapter}, @code{@@section}, and such lines of a -Texinfo file.@refill - -@item C-c C-c -@itemx M-x occur-mode-goto-occurrence -@findex occur-mode-goto-occurrence -Go to the line in the Texinfo file corresponding to the line under the -cursor in the @file{*Occur*} buffer.@refill -@end table - -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. - -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 -@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 -information about the narrowing commands.)@refill - -@vindex page-delimiter -@cindex Page delimiter in Texinfo mode -In addition to providing the @code{texinfo-show-structure} command, -Texinfo mode sets the value of the page delimiter variable to match -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 n p} (@code{narrow-to-page}) command to narrow to a chapter. -@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information -about the page commands.@refill - -@node Updating Nodes and Menus -@comment node-name, next, previous, up -@section Updating Nodes and Menus -@cindex Updating nodes and menus -@cindex Create nodes, menus automatically -@cindex Insert nodes, menus automatically -@cindex Automatically insert nodes, menus - -Texinfo mode provides commands for automatically creating or updating -menus and node pointers. The commands are called ``update'' commands -because their most frequent use is for updating a Texinfo file after you -have worked on it; but you can use them to insert the `Next', -`Previous', and `Up' pointers into an @code{@@node} line that has none -and to create menus in a file that has none. - -If you do not use the updating commands, you need to write menus and -node pointers by hand, which is a tedious task.@refill - -@menu -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. -@end menu - -@node Updating Commands -@subsection The Updating Commands - -You can use the updating commands to:@refill - -@itemize @bullet -@item -insert or update the `Next', `Previous', and `Up' pointers of a -node,@refill - -@item -insert or update the menu for a section, and@refill - -@item -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 -region or in a whole Texinfo file.@refill - -The updating commands work only with conventional Texinfo files, which -are structured hierarchically like books. In such files, a structuring -command line must follow closely after each @code{@@node} line, except -for the `Top' @code{@@node} line. (A @dfn{structuring command line} is -a line beginning with @code{@@chapter}, @code{@@section}, or other -similar command.) - -You can write the structuring command line on the line that follows -immediately after an @code{@@node} line or else on the line that -follows after a single @code{@@comment} line or a single -@code{@@ifinfo} line. You cannot interpose more than one line between -the @code{@@node} line and the structuring command line; and you may -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 -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. This -is a deficiency. Rather than use menu entries, you can use cross -references to refer to other Info files. None of the updating commands -affect cross references.@refill - -Texinfo mode has five updating commands that are used most often: two -are for updating the node pointers or menu of a single node (or a -region); two are for updating every node pointer and menu in a file; -and one, the @code{texinfo-master-menu} command, is for creating a -master menu for a complete file, and optionally, for updating every -node and menu in the whole Texinfo file.@refill - -The @code{texinfo-master-menu} command is the primary command:@refill - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -@findex texinfo-master-menu -Create or update a master menu that includes all the other menus -(incorporating the descriptions from pre-existing menus, if -any).@refill - -With an argument (prefix argument, @kbd{C-u,} if interactive), first create or -update all the nodes and all the regular menus in the buffer before -constructing the master menu. (@xref{The Top Node, , The Top Node and -Master Menu}, for more about a master menu.)@refill - -For @code{texinfo-master-menu} to work, the Texinfo file must have a -`Top' node and at least one subsequent node.@refill - -After extensively editing a Texinfo file, you can type the following: - -@example -C-u M-x texinfo-master-menu -@exdent or -C-u C-c C-u m -@end example - -@noindent -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 -file.@refill - -@need 1000 -The commands are:@refill - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -@findex texinfo-update-node -Insert the `Next', `Previous', and `Up' pointers for the node that point is -within (i.e., for the @code{@@node} line preceding point). If the -@code{@@node} line has pre-existing `Next', `Previous', or `Up' -pointers in it, the old pointers are removed and new ones inserted. -With an argument (prefix argument, @kbd{C-u}, if interactive), this command -updates all @code{@@node} lines in the region (which is the text -between point and mark).@refill - -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -@findex texinfo-make-menu -Create or update the menu in the node that point is within. -With an argument (@kbd{C-u} as prefix argument, if -interactive), the command makes or updates menus for the -nodes which are either within or a part of the -region.@refill - -Whenever @code{texinfo-make-menu} updates an existing menu, the -descriptions from that menu are incorporated into the new menu. This -is done by copying descriptions from the existing menu to the entries -in the new menu that have the same node names. If the node names are -different, the descriptions are not copied to the new menu.@refill - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -@findex texinfo-every-node-update -Insert or update the `Next', `Previous', and `Up' pointers for every -node in the buffer.@refill - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -@findex texinfo-all-menus-update -Create or update all the menus in the buffer. With an argument -(@kbd{C-u} as prefix argument, if interactive), first insert -or update all the node -pointers before working on the menus.@refill - -If a master menu exists, the @code{texinfo-all-menus-update} command -updates it; but the command does not create a new master menu if none -already exists. (Use the @code{texinfo-master-menu} command for -that.)@refill - -When working on a document that does not merit a master menu, you can -type the following: - -@example -C-u C-c C-u C-a -@exdent or -C-u M-x texinfo-all-menus-update -@end example - -@noindent -This updates all the nodes and menus.@refill -@end table - -The @code{texinfo-column-for-description} variable specifies the -column to which menu descriptions are indented. By default, the value -is 32 although it can be useful to reduce it to as low as 24. You -can set the variable via customization (@pxref{Changing an Option,,, -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}). - -Also, the @code{texinfo-indent-menu-description} command may be used to -indent existing menu descriptions to a specified column. Finally, if -you wish, you can use the @code{texinfo-insert-node-lines} command to -insert missing @code{@@node} lines into a file. (@xref{Other Updating -Commands}, for more information.)@refill - -@node Updating Requirements -@subsection Updating Requirements -@cindex Updating requirements -@cindex Requirements for updating commands - -To use the updating commands, you must organize the Texinfo file -hierarchically with chapters, sections, subsections, and the like. -When you construct the hierarchy of the manual, do not `jump down' -more than one level at a time: you can follow the `Top' node with a -chapter, but not with a section; you can follow a chapter with a -section, but not with a subsection. However, you may `jump up' any -number of levels at one time---for example, from a subsection to a -chapter.@refill - -Each @code{@@node} line, with the exception of the line for the `Top' -node, must be followed by a line with a structuring command such as -@code{@@chapter}, @code{@@section}, or -@code{@@unnumberedsubsec}.@refill - -Each @code{@@node} line/structuring-command line combination -must look either like this: - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@comment node-name, next, previous, up -@@section Comments -@end group -@end example - -or like this (without the @code{@@comment} line): - -@example -@group -@@node Comments, Minimum, Conventions, Overview -@@section Comments -@end group -@end example - -or like this (without the explicit node pointers): - -@example -@group -@@node Comments -@@section Comments -@end group -@end example - -@noindent -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.) - -If a file has a `Top' node, it must be called @samp{top} or @samp{Top} -and be the first node in the file. - -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. - - -@node Other Updating Commands -@subsection Other Updating Commands - -In addition to the five major updating commands, Texinfo mode -possesses several less frequently used updating commands:@refill - -@table @kbd -@item M-x texinfo-insert-node-lines -@findex texinfo-insert-node-lines -Insert @code{@@node} lines before the @code{@@chapter}, -@code{@@section}, and other sectioning commands wherever they are -missing throughout a region in a Texinfo file.@refill - -With an argument (@kbd{C-u} as prefix argument, if interactive), the -@code{texinfo-insert-node-lines} command not only inserts -@code{@@node} lines but also inserts the chapter or section titles as -the names of the corresponding nodes. In addition, it inserts the -titles as node names in pre-existing @code{@@node} lines that lack -names. Since node names should be more concise than section or -chapter titles, you must manually edit node names so inserted.@refill - -For example, the following marks a whole buffer as a region and inserts -@code{@@node} lines and titles throughout:@refill - -@example -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. - -@item M-x texinfo-multiple-files-update -@findex texinfo-multiple-files-update @r{(in brief)} -Update nodes and menus in a document built from several separate files. -With @kbd{C-u} as a prefix argument, create and insert a master menu in -the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first -update all the menus and all the `Next', `Previous', and `Up' pointers -of all the included files before creating and inserting a master menu in -the outer file. The @code{texinfo-multiple-files-update} command is -described in the appendix on @code{@@include} files. -@xref{texinfo-multiple-files-update}. - -@item M-x texinfo-indent-menu-description -@findex texinfo-indent-menu-description -Indent every description in the menu following point to the specified -column. You can use this command to give yourself more space for -descriptions. With an argument (@kbd{C-u} as prefix argument, if -interactive), the @code{texinfo-indent-menu-description} command indents -every description in every menu in the region. However, this command -does not indent the second and subsequent lines of a multi-line -description.@refill - -@item M-x texinfo-sequential-node-update -@findex texinfo-sequential-node-update -Insert the names of the nodes immediately following and preceding the -current node as the `Next' or `Previous' pointers regardless of those -nodes' hierarchical level. This means that the `Next' node of a -subsection may well be the next chapter. Sequentially ordered nodes are -useful for novels and other documents that you read through -sequentially. (However, in Info, the @kbd{g *} command lets -you look through the file sequentially, so sequentially ordered nodes -are not strictly necessary.) With an argument (prefix argument, if -interactive), the @code{texinfo-sequential-node-update} command -sequentially updates all the nodes in the region.@refill -@end table - -@node Info Formatting -@comment node-name, next, previous, up -@section Formatting for Info -@cindex Formatting for Info -@cindex Running an Info formatter -@cindex Info formatting - -Texinfo mode provides several commands for formatting part or all of a -Texinfo file for Info. Often, when you are writing a document, you -want to format only part of a file---that is, a region.@refill - -You can use either the @code{texinfo-format-region} or the -@code{makeinfo-region} command to format a region:@refill - -@table @kbd -@findex texinfo-format-region -@item C-c C-e C-r -@itemx M-x texinfo-format-region -@itemx C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@end table - -You can use either the @code{texinfo-format-buffer} or the -@code{makeinfo-buffer} command to format a whole buffer:@refill - -@table @kbd -@findex texinfo-format-buffer -@item C-c C-e C-b -@itemx M-x texinfo-format-buffer -@itemx C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@end table - -@need 1000 -For example, after writing a Texinfo file, you can type the following: - -@example -C-u C-c C-u m -@exdent or -C-u M-x texinfo-master-menu -@end example - -@noindent -This updates all the nodes and menus. Then type the following to create -an Info file: - -@example -C-c C-m C-b -@exdent or -M-x makeinfo-buffer -@end example - -For @TeX{} or the Info formatting commands to work, the file @emph{must} -include a line that has @code{@@setfilename} in its header. - -@xref{Creating an Info File}, for details about Info formatting.@refill - -@node Printing -@comment node-name, next, previous, up -@section Printing -@cindex Formatting for printing -@cindex Printing a region or buffer -@cindex Region formatting and printing -@cindex Buffer formatting and printing -@cindex Part of file formatting and printing - -Typesetting and printing a Texinfo file is a multi-step process in which -you first create a file for printing (called a DVI file), and then -print the file. Optionally, you may also create indices. To do this, -you must run the @code{texindex} command after first running the -@code{tex} typesetting command; and then you must run the @code{tex} -command again. Or else run the @code{texi2dvi} command which -automatically creates indices as needed (@pxref{Format with texi2dvi}). - -Often, when you are writing a document, you want to typeset and print -only part of a file to see what it will look like. You can use the -@code{texinfo-tex-region} and related commands for this purpose. Use -the @code{texinfo-tex-buffer} command to format all of a -buffer.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -@findex texinfo-tex-buffer -Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the -buffer, this command automatically creates or updates indices as -needed.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -@findex texinfo-tex-region -Run @TeX{} on the region.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Run @code{texindex} to sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does -not run @code{texindex} automatically; it only runs the @code{tex} -typesetting command. You must run the @code{texinfo-tex-region} command -a second time after sorting the raw index files with the @code{texindex} -command. (Usually, you do not format an index when you format a region, -only when you format a buffer. Now that the @code{texi2dvi} command -exists, there is little or no need for this command.)@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -@findex texinfo-tex-print -Print the file (or the part of the file) previously formatted with -@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill -@end table - -For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the -file @emph{must} start with a @samp{\input texinfo} line and must -include an @code{@@settitle} line. The file must end with @code{@@bye} -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 -commands, such as @code{tex-show-print-queue}.@refill - -@node Texinfo Mode Summary -@comment node-name, next, previous, up -@section Texinfo Mode Summary - -In Texinfo mode, each set of commands has default keybindings that -begin with the same keys. All the commands that are custom-created -for Texinfo mode begin with @kbd{C-c}. The keys are somewhat -mnemonic.@refill - -@subheading Insert Commands - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command to be inserted. (It might make more -sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but -@kbd{C-c C-c} is quick to type.)@refill - -@example -C-c C-c c @r{Insert} @samp{@@code}. -C-c C-c d @r{Insert} @samp{@@dfn}. -C-c C-c e @r{Insert} @samp{@@end}. -C-c C-c i @r{Insert} @samp{@@item}. -C-c C-c n @r{Insert} @samp{@@node}. -C-c C-c s @r{Insert} @samp{@@samp}. -C-c C-c v @r{Insert} @samp{@@var}. -C-c @{ @r{Insert braces.} -C-c ] -C-c @} @r{Move out of enclosing braces.} - -@group -C-c C-c C-d @r{Insert a node's section title} - @r{in the space for the description} - @r{in a menu entry line.} -@end group -@end example - -@subheading Show Structure - -The @code{texinfo-show-structure} command is often used within a -narrowed region.@refill - -@example -C-c C-s @r{List all the headings.} -@end example - -@subheading The Master Update Command - -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 -M-x texinfo-master-menu - @r{Create or update a master menu.} -@end group - -@group -C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} - @r{create or update all nodes and regular} - @r{menus, and then create a master menu.} -@end group -@end example - -@subheading Update Pointers - -The update pointer commands are invoked by typing @kbd{C-c C-u} and -then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for -@code{texinfo-every-node-update}.@refill - -@example -C-c C-u C-n @r{Update a node.} -C-c C-u C-e @r{Update every node in the buffer.} -@end example - -@subheading Update Menus - -Invoke the update menu commands by typing @kbd{C-c C-u} -and then either @kbd{C-m} for @code{texinfo-make-menu} or -@kbd{C-a} for @code{texinfo-all-menus-update}. To update -both nodes and menus at the same time, precede @kbd{C-c C-u -C-a} with @kbd{C-u}.@refill - -@example -C-c C-u C-m @r{Make or update a menu.} - -@group -C-c C-u C-a @r{Make or update all} - @r{menus in a buffer.} -@end group - -@group -C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} - @r{first create or update all nodes and} - @r{then create or update all menus.} -@end group -@end example - -@subheading Format for Info - -The Info formatting commands that are written in Emacs Lisp are -invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region -or @kbd{C-b} for the whole buffer.@refill - -The Info formatting commands that are written in C and based on the -@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then -either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill - -@need 800 -@noindent -Use the @code{texinfo-format@dots{}} commands: - -@example -@group -C-c C-e C-r @r{Format the region.} -C-c C-e C-b @r{Format the buffer.} -@end group -@end example - -@need 750 -@noindent -Use @code{makeinfo}: - -@example -C-c C-m C-r @r{Format the region.} -C-c C-m C-b @r{Format the buffer.} -C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} -C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} -@end example - -@subheading Typeset and Print - -The @TeX{} typesetting and printing commands are invoked by typing -@kbd{C-c C-t} and then another control command: @kbd{C-r} for -@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, -and so on.@refill - -@example -C-c C-t C-r @r{Run @TeX{} on the region.} -C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} -C-c C-t C-i @r{Run} @code{texindex}. -C-c C-t C-p @r{Print the DVI file.} -C-c C-t C-q @r{Show the print queue.} -C-c C-t C-d @r{Delete a job from the print queue.} -C-c C-t C-k @r{Kill the current @TeX{} formatting job.} -C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} -C-c C-t C-l @r{Recenter the output buffer.} -@end example - -@subheading Other Updating Commands - -The remaining updating commands do not have standard keybindings because -they are rarely used. - -@example -@group -M-x texinfo-insert-node-lines - @r{Insert missing @code{@@node} lines in region.} - @r{With @kbd{C-u} as a prefix argument,} - @r{use section titles as node names.} -@end group - -@group -M-x texinfo-multiple-files-update - @r{Update a multi-file document.} - @r{With @kbd{C-u 2} as a prefix argument,} - @r{create or update all nodes and menus} - @r{in all included files first.} -@end group - -@group -M-x texinfo-indent-menu-description - @r{Indent descriptions.} -@end group - -@group -M-x texinfo-sequential-node-update - @r{Insert node pointers in strict sequence.} -@end group -@end example - - -@node Beginning a File -@chapter Beginning a Texinfo File -@cindex Beginning a Texinfo file -@cindex Texinfo file beginning -@cindex File beginning - -Certain pieces of information must be provided at the beginning of a -Texinfo file, such as the name for the output file(s), the title of the -document, and the Top node. A table of contents is also generally -produced here. - -This chapter expands on the minimal complete Texinfo source file -previously given (@pxref{Six Parts}). It describes the numerous -commands for handling the traditional frontmatter items in Texinfo. - -@cindex Frontmatter, text in -Straight text outside of any command before the Top node should be -avoided. Such text is treated differently in the different output -formats: visible in @TeX{} and HTML, by default not shown in Info -readers, and so on. - -@menu -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. -@end menu - - -@node Sample Beginning -@section Sample Texinfo File Beginning - -@cindex Example beginning of Texinfo file - -The following sample shows what is needed. The elements given here are -explained in more detail in the following sections. Other commands are -often included at the beginning of Texinfo files, but the ones here are -the most critical. - -@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. - -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename @var{infoname}.info -@@settitle @var{name-of-manual} @var{version} -@@c %**end of header - -@@copying -This manual is for @var{program}, version @var{version}. - -Copyright @@copyright@{@} @var{years} @var{copyright-owner}. - -@group -@@quotation -Permission is granted to @dots{} -@@end quotation -@@end copying -@end group - -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@end group - -@group -@@c The following two commands -@@c start the copyright page. -@@page -@@vskip 0pt plus 1filll -@@insertcopying -@end group - -Published by @dots{} -@@end titlepage - -@@c So the toc is printed at the start. -@@contents - -@@ifnottex -@@node Top -@@top @var{title} - -This manual is for @var{program}, version @var{version}. -@@end ifnottex - -@group -@@menu -* First Chapter:: Getting started @dots{} -* Second Chapter:: @dots{} - @dots{} -* Copying:: Your rights and freedoms. -@@end menu -@end group - -@group -@@node First Chapter -@@chapter First Chapter - -@@cindex first chapter -@@cindex chapter, first -@dots{} -@end group -@end example - - -@node Texinfo File Header -@section Texinfo File Header -@cindex Header for Texinfo files -@cindex Texinfo file header - -Texinfo files start with at least three lines that provide Info and -@TeX{} with necessary information. These are the @code{\input texinfo} -line, the @code{@@settitle} line, and the @code{@@setfilename} line. - -Also, if you want to format just part of the Texinfo file, you must -write the @code{@@settitle} and @code{@@setfilename} lines between -start-of-header and end-of-header lines. The start- and end-of-header -lines are optional, but they do no harm, so you might as well always -include them. - -Any command that affects document formatting as a whole makes sense to -include in the header. @code{@@synindex} (@pxref{synindex}), for -instance, is another command often included in the header. @xref{GNU -Sample Texts}, for complete sample texts. - -Thus, the beginning of a Texinfo file generally looks like this: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Manual 1.0 -@@c %**end of header -@end group -@end example - -@menu -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. -@end menu - - -@node First Line -@subsection The First Line of a Texinfo File -@cindex First line of a Texinfo file -@cindex Beginning line of a Texinfo file -@cindex Header of a Texinfo file - -Every Texinfo file that is to be the top-level input to @TeX{} must begin -with a line that looks like this: - -@example -\input texinfo @@c -*-texinfo-*- -@end example - -@noindent -This line serves two functions: - -@enumerate -@item -When the file is processed by @TeX{}, the @samp{\input texinfo} command -tells @TeX{} to load the macros needed for processing a Texinfo file. -These are in a file called @file{texinfo.tex}, which should have been -installed on your system along with either the @TeX{} or Texinfo -software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of -a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex} -file causes the switch from @samp{\} to @samp{@@}; before the switch -occurs, @TeX{} requires @samp{\}, which is why it appears at the -beginning of the file. - -@item -When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode -specification tells Emacs to use Texinfo mode. -@end enumerate - - -@node Start of Header -@subsection Start of Header -@cindex Start of header line - -A start-of-header line is a Texinfo comment that looks like this: - -@example -@@c %**start of header -@end example - -Write the start-of-header line on the second line of a Texinfo file. -Follow the start-of-header line with @code{@@setfilename} and -@code{@@settitle} lines and, optionally, with other commands that -globally affect the document formatting, such as @code{@@synindex} or -@code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of -Header}). - -The start- and end-of-header lines allow you to format only part of a -Texinfo file for Info or printing. @xref{texinfo-format commands}. - -The odd string of characters, @samp{%**}, is to ensure that no other -comment is accidentally taken for a start-of-header line. You can -change it if you wish by setting the @code{tex-start-of-header} and/or -@code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}. - - -@node setfilename -@subsection @code{@@setfilename}: Set the output file name -@findex setfilename -@cindex Texinfo requires @code{@@setfilename} - -In order to serve as the primary input file for either @code{makeinfo} -or @TeX{}, a Texinfo file must contain a line that looks like this: - -@example -@@setfilename @var{info-file-name} -@end example - -Write the @code{@@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. - -@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. - -The @code{@@setfilename} line specifies the name of the output file to -be generated. This name must 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}) entirely from the input file -name, or, preferably, replace it with the @samp{.info} extension. - -@cindex Length of file names -@cindex File name collision -@cindex Info file name, choosing -Although an explicit @samp{.info} extension is preferable, 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 @samp{-1}, -@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original -file name. (@xref{Tag and Split Files}.) The subfile name -@file{texinfo.info-10}, for example, is too long for old systems with a -14-character limit on filenames; 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 severe -limits on file names, it may 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. - -When producing HTML output, @code{makeinfo} will replace any extension -with @samp{html}, or add @samp{.html} if the given name has no -extension. - -@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 -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{}}). - - -@node settitle -@subsection @code{@@settitle}: Set the document title -@findex settitle - -In order to be made into a printed manual, a Texinfo file must contain -a line that looks like this: - -@example -@@settitle @var{title} -@end example - -Write the @code{@@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 what would otherwise be a comment. - -The @code{@@settitle} command should precede everything that generates -actual output. The best place for it is right after the -@code{@@setfilename} command (see the previous section). - -@cindex <title> HTML tag -In the HTML file produced by @command{makeinfo}, @var{title} serves as -the document @samp{<title>}. It also becomes the default document -description in the @samp{<head>} part (@pxref{documentdescription}). - -The title in the @code{@@settitle} command does not affect the title as -it appears on the title page. Thus, the two do not need not match -exactly. A practice we recommend is to include the version or edition -number of the manual in the @code{@@settitle} title; on the title page, -the version number generally appears as a @code{@@subtitle} so it would -be omitted from the @code{@@title}. @xref{titlepage}. - -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 @code{@@chapter} command.) By default, no page footer is -printed. - -Even if you are printing in a single-sided style, @TeX{} looks for an -@code{@@settitle} command line, in case you include the manual title -in the heading. - -@TeX{} prints page headings only for that text that comes after the -@code{@@end titlepage} command in the Texinfo file, or that comes -after an @code{@@headings} command that turns on headings. -(@xref{headings on off, , The @code{@@headings} Command}, for more -information.) - -You may, if you wish, create your own, customized headings and footings. -@xref{Headings}, for a detailed discussion of this. - - -@node End of Header -@subsection End of Header -@cindex End of header line - -Follow the header lines with an @w{end-of-header} line, which is a -Texinfo comment that looks like this: - -@example -@@c %**end of header -@end example - -@xref{Start of Header}. - - -@node Document Permissions -@section Document Permissions -@cindex Document Permissions -@cindex Copying Permissions - -The copyright notice and copying permissions for a document need to -appear in several places in the various Texinfo output formats. -Therefore, Texinfo provides a command (@code{@@copying}) to declare -this text once, and another command (@code{@@insertcopying}) to -insert the text at appropriate points. - -@menu -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. -@end menu - - -@node copying -@subsection @code{@@copying}: Declare Copying Permissions -@findex copying - -The @code{@@copying} command should be given very early in the document; -the recommended location is right after the header material -(@pxref{Texinfo File Header}). It conventionally consists of a sentence -or two about what the program is, identification of the documentation -itself, the legal copyright line, and the copying permissions. Here is -a skeletal example: - -@example -@@copying -This manual is for @var{program} (version @var{version}, updated -@var{date}), which @dots{} - -Copyright @@copyright@{@} @var{years} @var{copyright-owner}. - -@@quotation -Permission is granted to @dots{} -@@end quotation -@@end copying -@end example - -The @code{@@quotation} has no legal significance; it's there to improve -readability in some contexts. - -@xref{GNU Sample Texts}, for the full text to be used in GNU manuals. -@xref{GNU Free Documentation License}, for the license itself under -which GNU and other free manuals are distributed. You need to include -the license as an appendix to your document. - -The text of @code{@@copying} is output as a comment at the beginning of -Info, HTML, and XML output files. It is @emph{not} output implicitly in -plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to -emit the copying information. See the next section for details. - -@findex copyright -The @code{@@copyright@{@}} command generates a @samp{c} inside a circle -in output formats that support this (print and HTML). In the other -formats (Info and plain text), it generates @samp{(C)}. The copyright -notice itself has the following legally defined sequence: - -@example -Copyright @copyright{} @var{years} @var{copyright-owner}. -@end example - -@cindex Copyright word, always in English -The word `Copyright' must always be written in English, even if the -document is otherwise written in another language. This is due to -international law. - -@cindex Years, in copyright line -The list of years should include all years in which a version was -completed (even if it was released in a subsequent year). Ranges are -not allowed; each year must be written out individually and in full, -separated by commas. - -@cindex Copyright holder for FSF works -@cindex Holder of copyright for FSF works -@cindex Owner of copyright for FSF works -The copyright owner (or owners) is whoever holds legal copyright on the -work. In the case of works assigned to the FSF, the owner is `Free -Software Foundation, Inc.'. - -The copyright `line' may actually be split across multiple lines, both -in the source document and in the output. This often happens for -documents with a long history, having many different years of -publication. If you do use several lines, do not indent any of them -(or anything else in the @code{@@copying} block) in the source file. - -@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for -additional information. - - -@node insertcopying -@subsection @code{@@insertcopying}: Include Permissions Text -@findex insertcopying -@cindex Copying text, including -@cindex Permissions text, including -@cindex Including permissions text - -The @code{@@insertcopying} command is simply written on a line by -itself, like this: - -@example -@@insertcopying -@end example - -This inserts the text previously defined by @code{@@copying}. To meet -legal requirements, it must be used on the copyright page in the printed -manual (@pxref{Copyright}). - -The @code{@@copying} command itself causes the permissions text to -appear in an Info file @emph{before} the first node. The text is also -copied into the beginning of each split Info output file, as is legally -necessary. This location implies a human reading the manual using Info -does @emph{not} see this text (except when using the advanced Info -command @kbd{g *}), but this does not matter for legal purposes, -because the text is present. - -Similarly, the @code{@@copying} text is automatically included at the -beginning of each HTML output file, as an HTML comment. Again, this -text is not visible (unless the reader views the HTML source). - -The permissions text defined by @code{@@copying} also appears -automatically at the beginning of the XML output file. - - -@node Titlepage & Copyright Page -@section Title and Copyright Pages - -In hard copy output, the manual's name and author are usually printed on -a title page. Copyright information is usually printed on the back of -the title page. - -The title and copyright pages appear in the printed manual, but not in -the Info file. Because of this, it is possible to use several slightly -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 appears in the printed manual. - -@cindex Title page, for plain text -@cindex Copyright page, for plain text -You may wish to include titlepage-like information for plain text -output. Simply place any such leading material between -@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo} -includes this when writing plain text (@samp{--no-headers}), along with -an @code{@@insertcopying}. - -@menu -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. -@end menu - - -@node titlepage -@subsection @code{@@titlepage} -@cindex Title page -@findex titlepage - -Start the material for the title page and following copyright page -with @code{@@titlepage} on a line by itself and end it with -@code{@@end titlepage} on a line by itself. - -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!) - -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 independent 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{The Top Node}.) - -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. - -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. - -@findex shorttitlepage -@cindex Bastard title page -@cindex Title page, bastard -For extremely simple documents, and for the bastard title page in -traditional book frontmatter, Texinfo also provides a command -@code{@@shorttitlepage} which takes the rest of the line as the title. -The argument is typeset on a page by itself and followed by a blank -page. - - -@node titlefont center sp -@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} -@findex titlefont -@findex center -@findex sp @r{(titlepage line spacing)} - -You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} -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.) - -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. - -For HTML output, each @code{@@titlefont} command produces an -@code{<h1>} heading, but the HTML document @code{<title>} is not -affected. For that, you must put an @code{@@settitle} command before -the @code{@@titlefont} command (@pxref{settitle}). - -@need 700 -For example: - -@example -@@titlefont@{Texinfo@} -@end example - -Use the @code{@@center} command at the beginning of a line to center -the remaining text on that line. Thus, - -@example -@@center @@titlefont@{Texinfo@} -@end example - -@noindent -centers the title, which in this example is ``Texinfo'' printed -in the title font. - -Use the @code{@@sp} command to insert vertical space. For example: - -@example -@@sp 2 -@end example - -@noindent -This inserts two blank lines on the printed page. (@xref{sp, , -@code{@@sp}}, for more information about the @code{@@sp} -command.) - -A template for this method looks like this: - -@example -@group -@@titlepage -@@sp 10 -@@center @@titlefont@{@var{name-of-manual-when-printed}@} -@@sp 2 -@@center @var{subtitle-if-any} -@@sp 2 -@@center @var{author} -@dots{} -@@end titlepage -@end group -@end example - -The spacing of the example fits an 8.5 by 11 inch manual. - -You can in fact use these commands anywhere, not just on a title page, -but since they are not logical markup commands, we don't recommend -them. - -@node title subtitle author -@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} -@findex title -@findex subtitle -@findex author - -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. - -Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} -commands at the beginning of a line followed by the title, subtitle, -or author. These commands are only effective in @TeX{} output; it's -an error to use them anywhere except within @code{@@titlepage}. - -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 @code{@@subtitle} command sets subtitles in a normal-sized font -flush to the right-hand side of the page. - -The @code{@@author} command sets the names of the author or authors in -a middle-sized font flush to the left-hand side of the page on a line -near the bottom of the title page. The names are underlined with a -black rule that is thinner than the rule that underlines the title. -(The black rule only occurs if the @code{@@author} command line is -followed by an @code{@@page} command line.) - -There are two ways to use the @code{@@author} command: you can write -the name or names on the remaining part of the line that starts with -an @code{@@author} command: - -@example -@@author by Jane Smith and John Doe -@end example - -@noindent -or you can write the names one above each other by using two (or more) -@code{@@author} commands: - -@example -@group -@@author Jane Smith -@@author John Doe -@end group -@end example - -@noindent -(Only the bottom name is underlined with a black rule.) - -@need 950 -A template for this method looks like this: - -@example -@group -@@titlepage -@@title @var{name-of-manual-when-printed} -@@subtitle @var{subtitle-if-any} -@@subtitle @var{second-subtitle} -@@author @var{author} -@@page -@dots{} -@@end titlepage -@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: - -@example -@group -@@titlepage -@@titlefont@{GNU Software@} -@@sp 1 -@@title for MS-Windows and MS-DOS -@@subtitle Edition @@value@{e@} for Release @@value@{cde@} -@@author by Daniel Hagerty, Melissa Weisshaus -@@author and Eli Zaretskii -@end group -@end example - -@noindent -(The use of @code{@@value} here is explained in @ref{value Example}. - - -@node Copyright -@subsection Copyright Page -@cindex Copyright page -@cindex Printed permissions -@cindex Permissions, printed - -By international treaty, the copyright notice for a book must be either -on the title page or on the back of the title page. When the copyright -notice is on the back of the title page, that page is customarily not -numbered. Therefore, in Texinfo, the information on the copyright page -should be within @code{@@titlepage} and @code{@@end titlepage} -commands. - -@findex vskip @r{@TeX{} vertical skip} -@findex filll @r{@TeX{} dimension} -Use the @code{@@page} command to cause a page break. To push the -copyright notice and the other text on the copyright page towards the -bottom of the page, use the following incantation after @code{@@page}: - -@example -@@vskip 0pt plus 1filll -@end example - -@noindent -This is a @TeX{} command that is not supported by the Info formatting -commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt -plus 1filll} means to put in zero points of mandatory whitespace, and as -much optional whitespace as needed to push the following text to the -bottom of the page. Note the use of three @samp{l}s in the word -@samp{filll}; this is correct. - -To insert the copyright text itself, write @code{@@insertcopying} -next (@pxref{Document Permissions}): - -@example -@@insertcopying -@end example - -Follow the copying text by the publisher, ISBN numbers, cover art -credits, and other such information. - -Here is an example putting all this together: - -@example -@@titlepage -@dots{} -@@page -@@vskip 0pt plus 1filll -@@insertcopying - -Published by @dots{} - -Cover art by @dots{} -@@end titlepage -@end example - - -@node end titlepage -@subsection Heading Generation -@findex end titlepage -@cindex Headings, page, begin to appear -@cindex Titlepage end starts headings -@cindex End titlepage starts headings - -Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command -must be written at the beginning of a line by itself, with only one -space between the @code{@@end} and the @code{titlepage}. It not only -marks the end of the title and copyright pages, but also causes @TeX{} -to start generating page headings and page numbers. - -To repeat what is said elsewhere, Texinfo has two standard page heading -formats, one for documents which are printed on one side of each sheet of paper -(single-sided printing), and the other for documents which are printed on both -sides of each sheet (double-sided printing). -You can specify these formats in different ways: - -@itemize @bullet -@item -The conventional way is to write an @code{@@setchapternewpage} command -before the title page commands, and then have the @code{@@end -titlepage} command start generating page headings in the manner desired. -(@xref{setchapternewpage}.) - -@item -Alternatively, you can use the @code{@@headings} command to prevent page -headings from being generated or to start them for either single or -double-sided printing. (Write an @code{@@headings} command immediately -after the @code{@@end titlepage} command. @xref{headings on off, , The -@code{@@headings} Command}, for more information.)@refill - -@item -Or, you may specify your own page heading and footing format. -@xref{Headings, , Page Headings}, for detailed -information about page headings and footings. -@end itemize - -Most documents are formatted with the standard single-sided or -double-sided format, using @code{@@setchapternewpage odd} for -double-sided printing and no @code{@@setchapternewpage} command for -single-sided printing. - - -@node headings on off -@subsection The @code{@@headings} Command -@findex headings - -The @code{@@headings} command is rarely used. It specifies what kind of -page headings and footings to print on each page. Usually, this is -controlled by the @code{@@setchapternewpage} command. You need the -@code{@@headings} command only if the @code{@@setchapternewpage} command -does not do what you want, or if you want to turn off predefined page -headings prior to defining your own. Write an @code{@@headings} command -immediately after the @code{@@end titlepage} command. - -You can use @code{@@headings} as follows: - -@table @code -@item @@headings off -Turn off printing of page headings. - -@item @@headings single -Turn on page headings appropriate for single-sided printing. - -@item @@headings double -Turn on page headings appropriate for double-sided printing. - -@item @@headings singleafter -@itemx @@headings doubleafter -Turn on @code{single} or @code{double} headings, respectively, after the -current page is output. - -@item @@headings on -Turn on page headings: @code{single} if @samp{@@setchapternewpage -on}, @code{double} otherwise. -@end table - -For example, suppose you write @code{@@setchapternewpage off} before the -@code{@@titlepage} command to tell @TeX{} to start a new chapter on the -same page as the end of the last chapter. This command also causes -@TeX{} to typeset page headers for single-sided printing. To cause -@TeX{} to typeset for double sided printing, write @code{@@headings -double} after the @code{@@end titlepage} command. - -You can stop @TeX{} from generating any page headings at all by -writing @code{@@headings off} on a line of its own immediately after the -line containing the @code{@@end titlepage} command, like this: - -@example -@@end titlepage -@@headings off -@end example - -@noindent -The @code{@@headings off} command overrides the @code{@@end titlepage} -command, which would otherwise cause @TeX{} to print page headings. - -You can also specify your own style of page heading and footing. -@xref{Headings, , Page Headings}, for more information. - - -@node Contents -@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 -(@pxref{Structuring}) 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). - -@table @code -@item @@contents -Generates a table of contents in a printed manual, including all -chapters, sections, subsections, etc., as well as appendices and -unnumbered chapters. Headings generated by @code{@@majorheading}, -@code{@@chapheading}, and the other @code{@@@dots{}heading} commands -do not appear in the table of contents (@pxref{Structuring Command -Types}). - -@item @@shortcontents -@itemx @@summarycontents -(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.) - -Generates a short or summary table of contents that lists only the -chapters, appendices, and unnumbered chapters. Sections, subsections -and subsubsections are omitted. Only a long manual needs a short -table of contents in addition to the full table of contents. - -@end table - -Both contents commands should be written on a line by themselves, and -are best placed near the beginning of the file, after the @code{@@end -titlepage} (@pxref{titlepage}). 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. - -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}), unless @code{makeinfo} is writing its output to standard -output. - -When @code{makeinfo} writes a short table of contents while producing -HTML output, the links in the short table of contents point to -corresponding entries in the full table of contents rather than the text -of the document. The links in the full table of contents point to the -main text of the document. - -In the past, the contents commands were sometimes placed at the end of -the file, after any indices and just before the @code{@@bye}, but we -no longer recommend this. - -@findex setcontentsaftertitlepage -@findex setshortcontentsaftertitlepage -@cindex Contents, after title page -@cindex Table of contents, after title page -However, since many existing Texinfo documents still do have the -@code{@@contents} at the end of the manual, if you are a user printing -a manual, you may wish to force the contents to be printed after the -title page. 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, erroneously, 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). We recommend using @command{texi2dvi} (@pxref{Format with -texi2dvi}) to specify this without altering the source file at all. For -example: -@example -texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi -@end example - - -@node The Top Node -@section The `Top' Node and Master Menu -@cindex Top node -@cindex Node, `Top' - -The `Top' node is the node in which a reader enters an Info manual. -As such, it should begin with a brief description of the manual -(including the version number), and end with a master menu for the -whole manual. Of course you should include any other general -information you feel a reader would find helpful. - -@findex top -It is conventional and desirable to write an @code{@@top} sectioning -command line containing the title of the document immediately after -the @code{@@node Top} line (@pxref{makeinfo top command, , The -@code{@@top} Sectioning Command}). - -The contents of the `Top' node should appear only in the online output; -none of it should appear in printed output, so enclose it between -@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not -print either an @code{@@node} line or a menu; they appear only in Info; -strictly speaking, you are not required to enclose these parts between -@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do -so. @xref{Conditionals, , Conditionally Visible Text}.) - -@menu -* Top Node Example:: -* Master Menu Parts:: -@end menu - - -@node Top Node Example -@subsection Top Node Example - -@cindex Top node example - -Here is an example of a Top node. - -@example -@group -@@ifnottex -@@node Top -@@top Sample Title - -@@insertcopying -@@end ifnottex -@end group - -Additional general information. - -@group -@@menu -* First Chapter:: -* Second Chapter:: -@dots{} -* Index:: -@end group -@@end menu -@end example - - -@node Master Menu Parts -@subsection Parts of a Master Menu -@cindex Master menu -@cindex Menu, master -@cindex Parts of a master menu - -A @dfn{master menu} is a detailed main menu listing all the nodes in a -file. - -A master menu is enclosed in @code{@@menu} and @code{@@end menu} -commands and does not appear in the printed document. - -Generally, a master menu is divided into parts. - -@itemize @bullet -@item -The first part contains the major nodes in the Texinfo file: the nodes -for the chapters, chapter-like sections, and the appendices. - -@item -The second part contains nodes for the indices. - -@item -@findex detailmenu -@cindex Detailed menu -The third and subsequent parts contain a listing of the other, lower -level nodes, often ordered by chapter. This way, rather than go -through an intermediary menu, an inquirer can go directly to a -particular node when searching for specific information. These menu -items are not required; add them if you think they are a -convenience. If you do use them, put @code{@@detailmenu} before the -first one, and @code{@@end detailmenu} after the last; otherwise, -@code{makeinfo} will get confused. -@end itemize - -Each section in the menu can be introduced by a descriptive line. So -long as the line does not begin with an asterisk, it will not be -treated as a menu entry. (@xref{Writing a Menu}, for more -information.) - -For example, the master menu for this manual looks like the following -(but has many more entries): - -@example -@group -@@menu -* Copying Conditions:: Your rights. -* Overview:: Texinfo in brief. -@dots{} -@end group -@group -* Command and Variable Index:: -* General Index:: -@end group - -@group -@@detailmenu ---- The Detailed Node Listing --- - -Overview of Texinfo - -* Reporting Bugs:: @dots{} -@dots{} -@end group - -@group -Beginning a Texinfo File - -* Sample Beginning:: @dots{} -@dots{} -@@end detailmenu -@@end menu -@end group -@end example - - -@node Global Document Commands -@section Global Document Commands -@cindex Global Document Commands - -Besides the basic commands mentioned in the previous sections, here are -additional commands which affect the document as a whole. They are -generally all given before the Top node, if they are given at all. - -@menu -* documentdescription:: Document summary for the HTML output. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* firstparagraphindent:: Suppress indentation of the first paragraph. -* exampleindent:: Specify environment indentation. -@end menu - - -@node documentdescription -@subsection @code{@@documentdescription}: Summary Text -@cindex Document description -@cindex Description of document -@cindex Summary of document -@cindex Abstract of document -@cindex <meta> HTML tag, and document description -@findex documentdescription - -When producing HTML output for a document, @command{makeinfo} writes a -@samp{<meta>} element in the @samp{<head>} to give some idea of the -content of the document. By default, this @dfn{description} is the title -of the document, taken from the @code{@@settitle} command -(@pxref{settitle}). To change this, use the @code{@@documentdescription} -environment, as in: - -@example -@@documentdescription -descriptive text. -@@end documentdescription -@end example - -@noindent -This will produce the following output in the @samp{<head>} of the HTML: - -@example -<meta name=description content="descriptive text."> -@end example - -@code{@@documentdescription} must be specified before the first node of -the document. - - -@node setchapternewpage -@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 -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 -preceding chapter, after a small amount of vertical whitespace. - -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 -(single-sided or double-sided printing). - -Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument. - -For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page: - -@example -@@setchapternewpage odd -@end example - -You can specify one of three alternatives with the -@code{@@setchapternewpage} command: - -@table @asis - -@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 -format page headers for single-sided printing. - -@item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to format page -headers for single-sided printing. This is the form most often used for -short reports or personal printing. This is the default. - -@item @code{@@setchapternewpage odd} -Cause @TeX{} to start new chapters on new, odd-numbered pages -(right-handed pages) and to typeset for double-sided printing. This is -the form most often used for books and manuals. -@end table - -Texinfo does not have an @code{@@setchapternewpage even} command, -because there is no printing tradition of starting chapters or books on -an even-numbered page. - -If you don't like the default headers that @code{@@setchapternewpage} -sets, you can explicit control them with the @code{@@headings} command. -@xref{headings on off, , The @code{@@headings} Command}. - -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. By -convention, table of contents and frontmatter pages are numbered with -roman numerals and not in sequence with the rest of the document. - -Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it. - -We recommend not including any @code{@@setchapternewpage} command in -your manual sources at all, since the desired output is not intrinsic to -the document. For a particular hard copy run, 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. - - -@node paragraphindent -@subsection @code{@@paragraphindent}: Paragraph Indenting -@cindex Indenting paragraphs, control of -@cindex Paragraph indentation control -@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: - -@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{}). - -@item @code{none} -@itemx 0 -Omit all indentation. - -@item @var{n} -Indent by @var{n} space characters in Info output, by @var{n} ems in -@TeX{}. - -@end table - -The default value of @var{indent} is 3. @code{@@paragraphindent} is -ignored for HTML output. - -It is best to write the @code{@@paragraphindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - -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. - - -@node firstparagraphindent -@subsection @code{@@firstparagraphindent}: Indenting After Headings -@cindex First paragraph, suppressing indentation of -@cindex Suppressing first paragraph indentation -@cindex Preventing first paragraph indentation -@cindex Indenting, suppressing of first paragraph -@cindex Headings, indentation after -@findex firstparagraphindent - -As you can see in the present manual, the first paragraph in any -section is not indented by default. Typographically, indentation is a -paragraph separator, which means that it is unnecessary when a new -section begins. This indentation is controlled with the -@code{@@firstparagraphindent} command: - -@example -@@firstparagraphindent @var{word} -@end example - -The first paragraph after a heading is indented according to the value -of @var{word}: - -@table @asis -@item @code{none} -Prevents the first paragraph from being indented (default). -This option is ignored by @command{makeinfo} if -@code{@@paragraphindent asis} is in effect. - -@item @code{insert} -Include normal paragraph indentation. This respects the paragraph -indentation set by a @code{@@paragraphindent} command -(@pxref{paragraphindent}). -@end table - -For HTML and XML output, the @code{@@firstparagraphindent} setting is -ignored. - -It is best to write the @code{@@paragraphindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - - -@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 - -@code{@@exampleindent} is ignored for HTML output. Otherwise, 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 spaces in Info, and 0.4@dmn{in} -in @TeX{}, which is somewhat less. (The reduction is to help @TeX{} -fit more characters onto physical lines.) - -It is best to write the @code{@@exampleindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - - -@node Software Copying Permissions -@section Software Copying Permissions -@cindex Software copying permissions -@cindex Copying software -@cindex Distribution -@cindex License agreement - -If the Texinfo file has a section containing the ``General Public -License'' and the distribution information and a warranty disclaimer for -the software that is documented, we recommend placing this right after -the `Top' node. The General Public License is very important to Project -GNU software. It ensures that you and others will continue to have a -right to use and share the software. - -The copying and distribution information and the disclaimer are followed -by an introduction or else by the first chapter of the manual. - -@cindex Introduction, as part of file -Although an introduction is not a required part of a Texinfo file, it -is very helpful. Ideally, it should state clearly and concisely what -the file is about and who would be interested in reading it. In -general, an introduction would follow the licensing and distribution -information, although sometimes people put it earlier in the document. - - -@node Ending a File -@chapter Ending a Texinfo File -@cindex Ending a Texinfo file -@cindex Texinfo file ending -@cindex File ending -@findex bye - -The end of a Texinfo file should include commands to create indices, -and the @code{@@bye} command to mark the last line to be processed. - -For example: - -@example -@@node Index -@@unnumbered Index - -@@printindex cp - -@@bye -@end example - -@menu -* Printing Indices & Menus:: How to print an index in hardcopy and - generate index menus in Info. -* File End:: How to mark the end of a file. -@end menu - - -@node Printing Indices & Menus -@section Printing Indices and Menus -@cindex Printing an index -@cindex Indices, printing and menus -@cindex Generating menus with indices -@cindex Menus generated with indices - -To print an index means to include it as part of a manual or Info file. -This does not happen automatically just because you use @code{@@cindex} -or other index-entry generating commands in the Texinfo file; those just -cause the raw data for the index to be 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 index file. The sorted index file is what is actually used to -print the index. - -Texinfo offers six separate types of predefined index, which suffice -in most cases. @xref{Indices}, for information on this, as well -defining your own new indices, combining indices, and, most -importantly advice on writing the actual index entries. This section -focuses on printing indices, which is done with the -@code{@@printindex} command. - -@findex printindex -@code{@@printindex} takes one argument, a two-letter index -abbreviation. It reads the corresponding sorted index file (for -printed output), and formats it appropriately into an index. - -The @code{@@printindex} command does not generate a chapter heading -for the index, since different manuals have different needs. -Consequently, you should precede the @code{@@printindex} command with -a suitable section or chapter command (usually @code{@@appendix} or -@code{@@unnumbered}) to supply the chapter heading and put the index -into the table of contents. Precede the chapter heading with an -@code{@@node} line as usual. - -For example: - -@smallexample -@group -@@node Variable Index -@@unnumbered Variable Index - -@@printindex vr -@end group - -@group -@@node Concept Index -@@unnumbered Concept Index - -@@printindex cp -@end group -@end smallexample - -If you have more than one index, we recommend placing the concept index last. - -@itemize -@item -In printed output, @code{@@printindex} produces a traditional -two-column index, with dot leaders between the index terms and page -numbers. - -@item -In Info output, @code{@@printindex} produces a special menu containing -the line number of the entry, relative to the start of the node. Info -readers can use this to go to the exact line of an entry, not just the -containing node. (Older Info readers will just go to the node.) -Here's an example: - -@smallexample -* First index entry: Top. (line 7) -@end smallexample - -@noindent The actual number of spaces is variable, to right-justify -the line number; it's been reduced here to make the line fit in the -printed manual. - -@item -In plain text output, @code{@@printindex} produces the same menu, but -the line numbers are relative to the start of the file, since that's -more convenient for that format. - -@item -In HTML and Docbook output, @code{@@printindex} produces links -to the index entries. - -@item -In XML output, it simply records the index to be printed. -@end itemize - -It's not possible to generate an index when writing to standard -output; @command{makeinfo} generates a warning in this case. - - -@node File End -@section @code{@@bye} File Ending -@findex bye - -An @code{@@bye} command terminates Texinfo processing. None of the -formatters read anything following @code{@@bye}. The @code{@@bye} -command should be on a line by itself. - -If you wish, you may follow the @code{@@bye} line with notes. These -notes will not be formatted and will not appear in either Info or a -printed manual; it is as if text after @code{@@bye} were within -@code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the -@code{@@bye} line with a local variables list for Emacs. -@xref{Compile-Command, , Using Local Variables and the Compile Command}, -for more information. - - -@node Structuring -@chapter Chapter Structuring -@cindex Chapter structuring -@cindex Structuring of chapters - -The @dfn{chapter structuring} commands divide a document into a hierarchy of -chapters, sections, subsections, and subsubsections. These commands -generate large headings; they also provide information for the table -of contents of a printed manual (@pxref{Contents, , Generating a Table -of Contents}).@refill - -The chapter structuring commands do not create an Info node structure, -so normally you should put an @code{@@node} command immediately before -each chapter structuring command (@pxref{Nodes}). The only time you -are likely to use the chapter structuring commands without using the -node structuring commands is if you are writing a document that -contains no cross references and will never be transformed into Info -format.@refill - -It is unlikely that you will ever write a Texinfo file that is -intended only as an Info file and not as a printable document. If you -do, you might still use chapter structuring commands to create a -heading at the top of each node---but you don't need to.@refill - -@menu -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. -@end menu - - -@node Tree Structuring -@section Tree Structure of Sections -@cindex Tree structuring - -A Texinfo file is usually structured like a book with chapters, -sections, subsections, and the like. This structure can be visualized -as a tree (or rather as an upside-down tree) with the root at the top -and the levels corresponding to chapters, sections, subsection, and -subsubsections.@refill - -Here is a diagram that shows a Texinfo file with three chapters, -each of which has two sections.@refill - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | -Section Section Section Section Section Section - 1.1 1.2 2.1 2.2 3.1 3.2 - -@end group -@end example - -In a Texinfo file that has this structure, the beginning of Chapter 2 -looks like this:@refill - -@example -@group -@@node Chapter 2, Chapter 3, Chapter 1, top -@@chapter Chapter 2 -@end group -@end example - -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 - -The chapter structuring commands fall into four groups or series, each -of which contains structuring commands corresponding to the -hierarchical levels of chapters, sections, subsections, and -subsubsections.@refill - -The four groups are the @code{@@chapter} series, the -@code{@@unnumbered} series, the @code{@@appendix} series, and the -@code{@@heading} series.@refill - -Each command produces titles that have a different appearance on the -printed page or Info file; only some of the commands produce -titles that are listed in the table of contents of a printed book or -manual.@refill - -@itemize @bullet -@item -The @code{@@chapter} and @code{@@appendix} series of commands produce -numbered or lettered entries both in the body of a printed work and in -its table of contents.@refill - -@item -The @code{@@unnumbered} series of commands produce unnumbered entries -both in the body of a printed work and in its table of contents. The -@code{@@top} command, which has a special use, is a member of this -series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered} -section should be associated with a node and be a normal part of the -document structure. - -@item -The @code{@@heading} series of commands produce simple unnumbered -headings that do not appear in a table of contents, are not associated -with nodes, and cannot be cross-referenced. The heading commands -never start a new page. - -@item -The @code{@@majorheading} command is similar to @code{@@chapheading}, -except that it generates a larger vertical whitespace before the -heading. - -@item -When an @code{@@setchapternewpage} command says to do so, the -@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands -start new pages in the printed manual; the @code{@@heading} commands -do not.@refill -@end itemize - -Here are the four groups of chapter structuring commands: - -@tex -{\globaldefs = 1 \smallfonts} -@end tex - -@multitable @columnfractions .19 .30 .29 .22 -@item @tab @tab @tab No new page -@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{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 -@tex -{\globaldefs = 1 \textfonts} -@end tex - - -@node makeinfo top -@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 node 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{}. - - -@node chapter -@comment node-name, next, previous, up -@section @code{@@chapter} -@findex chapter - -@code{@@chapter} identifies a chapter in the document. Write the -command at the beginning of a line and follow it on the same line by -the title of the chapter.@refill - -For example, this chapter in this manual is entitled ``Chapter -Structuring''; the @code{@@chapter} line looks like this:@refill - -@example -@@chapter Chapter Structuring -@end example - -In @TeX{}, the @code{@@chapter} command creates a chapter in the -document, specifying the chapter title. The chapter is numbered -automatically.@refill - -In Info, the @code{@@chapter} command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath. Thus, -in Info, the above example produces the following output:@refill - -@example -Chapter Structuring -******************* -@end example - -@findex centerchap -Texinfo also provides a command @code{@@centerchap}, which is analogous -to @code{@@unnumbered}, but centers its argument in the printed output. -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} -@findex unnumbered -@findex appendix - -Use the @code{@@unnumbered} command to create a chapter that appears -in a printed manual without chapter numbers of any kind. Use the -@code{@@appendix} command to create an appendix in a printed manual -that is labelled by letter (`A', `B', @dots{}) instead of by number. - -Write an @code{@@appendix} or @code{@@unnumbered} command at the -beginning of a line and follow it on the same line by the title, as -you would if you were creating a chapter. - - -@node majorheading & chapheading -@section @code{@@majorheading}, @code{@@chapheading} -@findex majorheading -@findex chapheading - -The @code{@@majorheading} and @code{@@chapheading} commands put -chapter-like headings in the body of a document.@refill - -However, neither command causes @TeX{} to produce a numbered heading -or an entry in the table of contents; and neither command causes -@TeX{} to start a new page in a printed manual.@refill - -In @TeX{}, an @code{@@majorheading} command generates a larger vertical -whitespace before the heading than an @code{@@chapheading} command but -is otherwise the same. - -In Info, -the @code{@@majorheading} and -@code{@@chapheading} commands are equivalent to -@code{@@chapter}: the title is printed on a line by itself with a line -of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill - - -@node section -@section @code{@@section} -@findex section - -A @code{@@section} command identifies a section within a chapter unit, -whether created with @code{@@chapter}, @code{@@unnumbered}, or -@code{@@appendix}, following the numbering scheme of the chapter-level -command. Thus, within a @code{@@chapter} chapter numbered `1', the -section is numbered like `1.2'; within an @code{@@appendix} -``chapter'' labeled `A', the section is numbered like `A.2'; within an -@code{@@unnumbered} chapter, the section gets no number. - -For example, this section is headed with an @code{@@section} command -and looks like this in the Texinfo file: - -@example -@@section @@code@{@@@@section@} -@end example - -To create a section, write the @code{@@section} command at the -beginning of a line and follow it on the same line by the section -title. The output is underlined with @samp{=} in Info. - -Thus, - -@example -@@section This is a section -@end example - -@noindent -might produce the following in Info: - -@example -@group -5.7 This is a section -===================== -@end group -@end example - - -@node unnumberedsec appendixsec heading -@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} -@findex unnumberedsec -@findex appendixsec -@findex heading - -The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} -commands are, respectively, the unnumbered, appendix-like, and -heading-like equivalents of the @code{@@section} command, as described -in the previous section. - -@table @code -@item @@unnumberedsec -The @code{@@unnumberedsec} command may be used within an -unnumbered chapter or within a regular chapter or appendix to -provide an unnumbered section.@refill - -@item @@appendixsec -@itemx @@appendixsection -@code{@@appendixsection} is a longer spelling of the -@code{@@appendixsec} command; the two are synonymous.@refill -@findex appendixsection - -Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} -command is used only within appendices.@refill - -@item @@heading -You may use the @code{@@heading} command anywhere you wish for a -section-style heading that will not appear in the table of contents.@refill -@end table - -@code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used -in ordinary circumstances, because @code{@@section} may also be used -within @code{@@unnumbered} and @code{@@appendix} chapters; again, see -the previous section. - - -@node subsection -@section The @code{@@subsection} Command -@findex subsection - -Subsections are to sections as sections are to chapters. -(@xref{section, , @code{@@section}}.) In Info, subsection titles are -underlined with @samp{-}. For example, - -@example -@@subsection This is a subsection -@end example - -@noindent -produces - -@example -@group -1.2.3 This is a subsection --------------------------- -@end group -@end example - -In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep.@refill - - -@node unnumberedsubsec appendixsubsec subheading -@section The @code{@@subsection}-like Commands -@cindex Subsection-like commands -@findex unnumberedsubsec -@findex appendixsubsec -@findex subheading - -The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and -@code{@@subheading} commands are, respectively, the unnumbered, -appendix-like, and heading-like equivalents of the @code{@@subsection} -command. (@xref{subsection, , @code{@@subsection}}.) - -In Info, the @code{@@subsection}-like commands generate a title -underlined with hyphens. In a printed manual, an @code{@@subheading} -command produces a heading like that of a subsection except that it is -not numbered and does not appear in the table of contents. Similarly, -an @code{@@unnumberedsubsec} command produces an unnumbered heading like -that of a subsection and an @code{@@appendixsubsec} command produces a -subsection-like heading labelled with a letter and numbers; both of -these commands produce headings that appear in the table of -contents. - -@code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to -be used in ordinary circumstances, because @code{@@subsection} may -also be used within sections of @code{@@unnumbered} and -@code{@@appendix} chapters (@pxref{section,,@code{section}}). - - -@node subsubsection -@section The `subsub' Commands -@cindex Subsub commands -@findex subsubsection -@findex unnumberedsubsubsec -@findex appendixsubsubsec -@findex subsubheading - -The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are:@refill - -@table @code -@item @@subsubsection -Subsubsections are to subsections as subsections are to sections. -(@xref{subsection, , @code{@@subsection}}.) In a printed manual, -subsubsection titles appear in the table of contents and are numbered -four levels deep.@refill - -@item @@unnumberedsubsubsec -Unnumbered subsubsection titles appear in the table of contents of a -printed manual, but lack numbers. Otherwise, unnumbered -subsubsections are the same as subsubsections. In Info, unnumbered -subsubsections look exactly like ordinary subsubsections.@refill - -@item @@appendixsubsubsec -Conventionally, appendix commands are used only for appendices and are -lettered and numbered appropriately in a printed manual. They also -appear in the table of contents. In Info, appendix subsubsections look -exactly like ordinary subsubsections.@refill - -@item @@subsubheading -The @code{@@subsubheading} command may be used anywhere that you need -a small heading that will not appear in the table of contents. In -Info, subsubheadings look exactly like ordinary subsubsection -headings.@refill -@end table - -@code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec} do not -need to be used in ordinary circumstances, because -@code{@@subsubsection} may also be used within subsections of -@code{@@unnumbered} and @code{@@appendix} chapters -(@pxref{section,,@code{section}}). - - -In Info, `subsub' titles are underlined with periods. -For example,@refill - -@example -@@subsubsection This is a subsubsection -@end example - -@noindent -produces - -@example -@group -1.2.3.4 This is a subsubsection -............................... -@end group -@end example - - -@node Raise/lower sections -@section @code{@@raisesections} and @code{@@lowersections} -@findex raisesections -@findex lowersections -@cindex Raising and lowering sections -@cindex Lowering and raising sections -@cindex Sections, raising and lowering - -The @code{@@raisesections} and @code{@@lowersections} commands -implicitly raise and lower the hierarchical level of following -chapters, sections and the other sectioning commands. - -That is, the @code{@@raisesections} command changes sections to -chapters, subsections to sections, and so on. Conversely, the -@code{@@lowersections} command changes chapters to sections, sections -to subsections, and so on. Thus, an @code{@@lowersections} command -cancels an @code{@@raisesections} command, and vice versa. - -@cindex Include files, and section levels -You can use @code{@@lowersections} to include text written as an outer -or standalone Texinfo file in another Texinfo file as an inner, -included file. Typical usage looks like this: - -@example -@@lowersections -@@include somefile.texi -@@raisesections -@end example - -@noindent (Without the @code{@@raisesections}, all the subsequent -sections in the document would be lowered.) - -If the included file being lowered has a @code{@@top} node, you'll -need to conditionalize its inclusion with a flag (@pxref{set value}). - -Another difficulty can arise with documents that use the (recommended) -feature of @command{makeinfo} for implicitly determining node -pointers. Since @command{makeinfo} must assume a hierarchically -organized document to determine the pointers, you cannot just -arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections} -commands in the document. The final result has to have menus that -take the raising and lowering into account. Therefore, as a practical -matter, you generally only want to raise or lower large chunks, -usually in external files as shown above. - -Repeated use of the commands continue to raise or lower the -hierarchical level a step at a time. An attempt to raise above -`chapter' reproduces chapter commands; an attempt to lower below -`subsubsection' reproduces subsubsection commands. Also, lowered -subsubsections and raised chapters will not work with -@command{makeinfo}'s feature of implicitly determining node pointers, -since the menu structure won't be correct. - -Write each @code{@@raisesections} and @code{@@lowersections} command -on a line of its own. - - -@node Nodes -@chapter Nodes - -@dfn{Nodes} are the primary segments of a Texinfo file. They do not -in and of themselves impose a hierarchical 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 pointers and menus provide structure for Info files just as -chapters, sections, subsections, and the like, provide structure for -printed books. - -Because node names are used in cross-references, it is not desirable -to casually change them. Such name changes invalidate references from -other manuals, from mail archives, and so on. - -@menu -* 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. -@end menu - - -@node Two Paths -@section Two Paths - -The node and menu commands and the chapter structuring commands are -technically independent of each other: - -@itemize @bullet -@item -In Info, node and menu commands provide structure. The chapter -structuring commands generate headings with different kinds of -underlining---asterisks for chapters, hyphens for sections, and so on; -they do nothing else.@refill - -@item -In @TeX{}, the chapter structuring commands generate chapter and section -numbers and tables of contents. The node and menu commands provide -information for cross references; they do nothing else.@refill -@end itemize - -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 - -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 -@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 -called the `Top' node, and `Up' node pointers carry you closer to the -root.@refill - -@example -@group - Top - | - ------------------------------------- - | | | - Chapter 1 Chapter 2 Chapter 3 - | | | - -------- -------- -------- - | | | | | | -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: - -@example -@group -@@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. - -@quotation Note -@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 -@end quotation - -To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter -2. (@xref{Menus}.) You would write the menu just -before the beginning of Section 2.1, like this:@refill - -@example -@group - @@menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: - @@end menu -@end group -@end example - -Write the node for Sect. 2.1 like this:@refill - -@example -@group - @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 - @@comment node-name, next, previous, up -@end group -@end example - -In Info format, the `Next' and `Previous' pointers of a node usually -lead to other nodes at the same level---from chapter to chapter or from -section to section (sometimes, as shown, the `Previous' pointer points -up); an `Up' pointer usually leads to a node at the level above (closer -to the `Top' node); and a `Menu' leads to nodes at a level below (closer -to `leaves'). (A cross reference can point to a node at any level; -see @ref{Cross References}.)@refill - -Usually, an @code{@@node} command and a chapter structuring command are -used in sequence, along with indexing commands. (You may follow the -@code{@@node} line with a comment line that reminds you which pointer is -which.)@refill - -Here is the beginning of the chapter in this manual called ``Ending a -Texinfo File''. This shows an @code{@@node} line followed by a comment -line, an @code{@@chapter} line, and then by indexing lines.@refill - -@example -@group -@@node Ending a File, Structuring, Beginning a File, Top -@@comment node-name, next, previous, up -@@chapter Ending a Texinfo File -@@cindex Ending a Texinfo file -@@cindex Texinfo file ending -@@cindex File ending -@end group -@end example - - -@node node -@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 -chapter may contain sections and a section may contain subsections; -but a node cannot contain subnodes; the text of a node continues only -until the next @code{@@node} command in the file. A node usually -contains only one chapter structuring command, the one that follows -the @code{@@node} line. On the other hand, in printed output nodes -are used only for cross references, so a chapter or section may -contain any number of nodes. Indeed, a chapter usually contains -several nodes, one for each section, subsection, and -subsubsection. - -To specify 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 (for details of node names, @pxref{Node Line -Requirements}). 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}). - -@opindex accesskey@r{, in HTML output} -Whether the node pointers are specified implicitly or explicitly, the -HTML output from @command{makeinfo} for each node includes links to -the `Next', `Previous', and `Up' nodes. The HTML also uses the -@code{accesskey} attribute with the values @samp{n}, @samp{p}, and -@samp{u} respectively. This allows people using web browsers to -follow the nagivation using (typically) @kbd{M-@var{letter}}, e.g., -@kbd{M-n} for the `Next' node, from anywhere within the node. - -You may insert spaces before each name on the @code{@@node} line if -you wish; the spaces are ignored. You must write the name of the node -and (if present) 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.) - -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}.) - -@TeX{} uses @code{@@node} lines to identify the names to use for cross -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}.) - -@menu -* Node Names:: How to choose node and pointer names. -* Writing a Node:: How to write an @code{@@node} line. -* Node Line Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. -@end menu - - -@node Node Names -@subsection Choosing Node and Pointer Names - -@cindex Node names, choosing -The name of a node identifies the node (for details of node names, -@pxref{Node Line Requirements}). The pointers enable you to reach -other nodes and consist simply of the names of those nodes. - -Normally, a node's `Up' pointer contains the name of the node whose -menu mentions that node. The node's `Next' pointer contains the name -of the node that follows the present node in that menu and its -`Previous' pointer contains the name of the node that precedes it in -that menu. When a node's `Previous' node is the same as its `Up' -node, both node pointers name the same node. - -Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the @file{dir} file, which -contains the main menu for all of Info. - -The `Top' node itself contains the main or master menu for the manual. -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. - -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 output. - - -@node Writing a Node -@subsection How to Write an @code{@@node} Line -@cindex Writing an @code{@@node} line -@cindex @code{@@node} line writing -@cindex Node line writing - -The easiest way to write an @code{@@node} line is to write @code{@@node} -at the beginning of a line and then the name of the node, like -this: - -@example -@@node @var{node-name} -@end example - -If you are using GNU Emacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or you -can leave the pointers out of the Texinfo file and let @code{makeinfo} -insert node pointers into the Info file it creates. (@xref{Texinfo -Mode}, and @ref{makeinfo Pointer Creation}.) - -Alternatively, you can insert the `Next', `Previous', and `Up' -pointers yourself. If you do this, you may find it helpful to use the -Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts -@samp{@@node} and a comment line listing the names of the pointers in -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. - -The template for a fully-written-out node line with `Next', `Previous', -and `Up' pointers looks like this: - -@example -@@node @var{node-name}, @var{next}, @var{previous}, @var{up} -@end example - -The @var{node-name} argument must be present, but the others are -optional. If you wish to specify some but not others, just insert -commas as needed, as in: @samp{@@node mynode,,,uppernode}. However, -we recommend leaving off all the pointers and letting @code{makeinfo} -determine them, as described above. - -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. - -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. - - -@node Node Line Tips -@subsection @code{@@node} Line Tips - -Here are three suggestions: - -@itemize @bullet -@item -Try to pick node names that are informative but short.@refill - -In the Info file, the file name, node name, and pointer names are all -inserted on one line, which may run into the right edge of the window. -(This does not cause a problem with Info, but is ugly.)@refill - -@item -Try to pick node names that differ from each other near the beginnings -of their names. This way, it is easy to use automatic name completion in -Info.@refill - -@item -By convention, node names are capitalized just as they would be for -section or chapter titles---initial and significant words are -capitalized; others are not.@refill -@end itemize - - -@node Node Line Requirements -@subsection @code{@@node} Line Requirements - -@cindex Node line requirements -@cindex Restrictions on node names -Here are several requirements for @code{@@node} lines: - -@itemize @bullet -@cindex Unique nodename requirement -@cindex Node name must be unique -@item -All the node names for a single Info file must be unique. - -Duplicates confuse the Info movement commands. This means, for -example, that if you end every chapter with a summary, you must name -each summary node differently. You cannot just call each one -``Summary''. You may, however, duplicate the titles of chapters, sections, -and the like. Thus you can end each chapter in a book with a section -called ``Summary'', so long as the node names for those sections are all -different. - -@item -A pointer name must be the name of a node. - -The node to which a pointer points may come before or after the -node containing the pointer. - -@cindex @@-commands in nodename -@cindex Node name, should not contain @@-commands -@item -@@-commands in node names are not allowed. This includes punctuation -characters that are escaped with a @samp{@@}, such as @code{@@} and -@code{@{}, and accent commands such as @samp{@@'}. (For a few cases -when this is useful, Texinfo has limited support for using -@w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps -this limitation will be removed some day. - -@item -@cindex Colon in nodename -@cindex Comma in nodename -@cindex Parentheses in nodename -@cindex Period in nodename -@cindex Characters, invalid in node name -@cindex Invalid characters in node names -@cindex Node names, invalid characters in -Unfortunately, you cannot use periods, commas, colons or parentheses -within a node name; these confuse the Texinfo processors. Perhaps -this limitation will be removed some day, too. - -@need 700 -For example, the following is a section title in this manual: - -@smallexample -@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} -@end smallexample - -@noindent -But the corresponding node name lacks the commas and the @@'s: - -@smallexample -unnumberedsec appendixsec heading -@end smallexample - -@cindex Case in node name -@item -Case is significant in node names. - -@cindex White space in node name -@cindex Spaces in node name -Spaces before and after names on the @samp{@@node} line are ignored, -but spaces ``inside'' a name are significant. For example: - -@example -@@node foo bar, -@@node foo bar , -@@node foo bar , -@end example - -@noindent all define the same node, @samp{foo bar}. References to the -node should all use that name, without the leading or trailing spaces, -but with the internal spaces. -@end itemize - - -@node First Node -@subsection The First Node -@cindex Top node is first -@cindex First node - -The first node of a Texinfo file is the @dfn{Top} node, except in an -included file (@pxref{Include Files}). The Top node should contain a -short summary, copying permissions, and a master menu. @xref{The Top -Node}, for more information on the Top node contents and examples. - -Here is a description of the node pointers to be used in the Top node: - -@itemize @bullet - -@item -@cindex Up node of Top node -@cindex (dir) as Up node of Top node -The Top node (which must be named @samp{top} or @samp{Top}) should have -as its `Up' node the name of a node in another file, where there is a -menu that leads to this file. Specify the file name in parentheses. - -Usually, all Info files are installed in the same Info directory tree; -in this case, use @samp{(dir)} as the parent of the Top node; this is -short for @samp{(dir)top}, and specifies the Top node in the @file{dir} -file, which contains the main menu for the Info system as a whole. - -@item -@cindex Prev node of Top node -The `Prev' node of the Top node should also be your @samp{(dir)} file. - -@item -@cindex Next node of Top node -The `Next' node of the Top node should be the first chapter in your -document. - -@end itemize - -@xref{Installing an Info File}, for more information about installing -an Info file in the @file{info} directory. - -It is usually best to leave the pointers off entirely and let the -tools implicitly define them, with this simple result: - -@example -@@node Top -@end example - - -@node makeinfo top command -@subsection The @code{@@top} Sectioning Command -@findex top @r{(@@-command)} - -A special sectioning command, @code{@@top} should be used with the -@code{@@node Top} line. The @code{@@top} sectioning command tells -@code{makeinfo} that it marks the `Top' node in the file. It provides -the information that @code{makeinfo} needs to insert node pointers -automatically. Write the @code{@@top} command at the beginning of the -line immediately following the @code{@@node Top} line. Write the title -on the remaining part of the same line as the @code{@@top} command. - -In Info, the @code{@@top} sectioning command causes the title to appear -on a line by itself, with a line of asterisks inserted underneath, as -other sectioning commands do. - -In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -sectioning command is merely a synonym for @code{@@unnumbered}. -Neither of these formatters require an @code{@@top} command, and do -nothing special with it. You can use @code{@@chapter} or -@code{@@unnumbered} after the @code{@@node Top} line when you use -these formatters. Also, you can use @code{@@chapter} or -@code{@@unnumbered} when you use the Texinfo updating commands to -create or update pointers and menus. - -Thus, in practice, a Top node starts like this: - -@example -@@node Top -@@top Your Manual Title -@end example - - -@node makeinfo Pointer Creation -@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 -determining node pointers for a hierarchically organized document. We -highly recommend using it. - -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). - -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. - -@cindex Detail menu -@findex detailmenu -If you use a detailed menu in your master menu (@pxref{Master Menu -Parts}), mark it with the @code{@@detailmenu @@dots@{@} @@end -detailmenu} environment, or @command{makeinfo} will get confused, -typically about the last and/or first node in the document. - -This implicit node pointer creation 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}.) - -In most cases, you will want to take advantage of this feature and not -redundantly specify node pointers. However, Texinfo documents are not -required to be organized hierarchically or in fact to contain -sectioning commands at all (for example, if you never intend the -document to be printed). The special procedure for handling the short -text before a menu (@pxref{Menus}) also disables this -feature, for that group of nodes. In those cases, you will need to -explicitly specify all pointers. - -@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. -Whitespace (including newlines) is 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}.) - -Also like node names, anchor names cannot include some characters -(@pxref{Node Line Requirements}). - - -@node Menus -@chapter Menus -@cindex Menus -@findex menu - -@dfn{Menus} contain pointers to subordinate nodes. In online output, -you use menus to go to such nodes. Menus have no effect in printed -manuals and do not appear in them. - -A node with a menu should not contain much text. If you find yourself -writing a lot of text before a menu, we generally recommend moving -most of the text into a new subnode---all but a paragraph or two. -Otherwise, a reader with a terminal that displays only a few lines may -miss the menu and its associated text. As a practical matter, it is -best to locate a menu within 20 or so lines of the beginning of the -node. - -@menu -* Menu Location:: Menus go at the ends of short nodes. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part menu entries. -* Other Info Files:: How to refer to a different Info file. -@end menu - - -@node Menu Location -@section Menu Location -@cindex Menu location -@cindex Location of menus - -A menu must be located at the end of a node, without any regular text -or additional commands between the @code{@@end menu} and the beginning -of the next node. (As a consequence, there may be at most one menu in -a node.) - -@cindex Info format, and menus -This is actually a useful restriction, since a reader who uses the -menu could easily miss any such text. Technically, it is necessary -because in Info format, there is no marker for the end of a menu, so -Info-reading programs would have no way to know when the menu ends and -normal text resumes. - -@cindex Hierarchical documents, and menus -Technically, menus can carry you to any node, regardless of the -structure of the document; even to nodes in a different Info file. -However, we do not recommend ever making use of this, because the -@command{makeinfo} implicit pointer creation feature (@pxref{makeinfo -Pointer Creation}) and GNU Emacs Texinfo mode updating commands work -only to create menus of subordinate nodes in a hierarchically -structured document. Instead, use cross references to refer to -arbitrary nodes. - -In the past, we recommended using a @samp{@@heading} command within an -@code{@@ifinfo} conditional instead of the normal sectioning commands -after a very short node with a menu. This had the advantage of making -the printed output look better, because there was no very short text -between two headings on the page. But this also does not work with -@command{makeinfo}'s implicit pointer creation, and it also makes the -XML output incorrect, since it does not reflect the true document -structure. So, regrettably, we can no longer recommend this. - - -@node Writing a Menu -@section Writing a Menu -@cindex Writing a menu -@cindex Menu writing - -A menu consists of an @code{@@menu} command on a line by itself -followed by menu entry lines or menu comment lines and then by an -@code{@@end menu} command on a line by itself. - -A menu looks like this: - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@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. - -@opindex accesskey@r{, in HTML output} -In the HTML output from @command{makeinfo}, the @code{accesskey} -attribute is used with the values @samp{1}@dots{}@samp{9} for the -first nine entries. This allows people using web browsers to follow -the first menu entries using (typically) @kbd{M-@var{digit}}, e.g., -@kbd{M-1} for the first entry. - - -@node Menu Parts -@section The Parts of a Menu -@cindex Parts of a menu -@cindex Menu parts -@cindex @code{@@menu} parts - -A menu entry has three parts, only the second of which is required: - -@enumerate -@item -The menu entry name (optional). - -@item -The name of the node (required). - -@item -A description of the item (optional). -@end enumerate - -The template for a menu entry looks like this:@refill - -@example -* @var{menu-entry-name}: @var{node-name}. @var{description} -@end example - -Follow the menu entry name with a single colon and follow the node name -with tab, comma, period, or newline.@refill - -In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) -command. The menu entry name is what the user types after the @kbd{m} -command.@refill - -The third part of a menu entry is a descriptive phrase or sentence. -Menu entry names and node names are often short; the description -explains to the reader what the node is about. A useful description -complements the node name rather than repeats it. The description, -which is optional, can spread over two or more lines; if it does, some -authors prefer to indent the second line while others prefer to align it -with the first (and all others). It's up to you. - - -@node Less Cluttered Menu Entry -@comment node-name, next, previous, up -@section Less Cluttered Menu Entry -@cindex Two part menu entry -@cindex Double-colon menu entries -@cindex Menu entries with two colons -@cindex Less cluttered menu entry -@cindex Uncluttered menu entry - -When the menu entry name and node name are the same, you can write -the name immediately after the asterisk and space at the beginning of -the line and follow the name with two colons.@refill - -@need 800 -For example, write - -@example -* Name:: @var{description} -@end example - -@need 800 -@noindent -instead of - -@example -* Name: Name. @var{description} -@end example - -You should use the node name for the menu entry name whenever possible, -since it reduces visual clutter in the menu.@refill - -@node Menu Example -@comment node-name, next, previous, up -@section A Menu Example -@cindex Menu example -@cindex Example menu - -A menu looks like this in Texinfo:@refill - -@example -@group -@@menu -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: - -* menu entry name: Node name. A short description. -* Node name:: This form is preferred. -@end group -@end example - -@need 700 -Here is an example as you might see it in a Texinfo file:@refill - -@example -@group -@@menu -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@@end menu -@end group -@end example - -@need 800 -@noindent -This produces: - -@example -@group -* menu: -Larger Units of Text - -* Files:: All about handling files. -* Multiples: Buffers. Multiple buffers; editing - several files at once. -@end group -@end example - -In this example, the menu has two entries. @samp{Files} is both a menu -entry name and the name of the node referred to by that name. -@samp{Multiples} is the menu entry name; it refers to the node named -@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it -appears in the menu, but is not an entry.@refill - -Since no file name is specified with either @samp{Files} or -@samp{Buffers}, they must be the names of nodes in the same Info file -(@pxref{Other Info Files, , Referring to Other Info Files}).@refill - -@node Other Info Files -@comment node-name, next, previous, up -@section Referring to Other Info Files -@cindex Referring to other Info files -@cindex Nodes in other Info files -@cindex Other Info files' nodes -@cindex Going to other Info files' nodes -@cindex Info; other files' nodes - -You can create a menu entry that enables a reader in Info to go to a -node in another Info file by writing the file name in parentheses just -before the node name. In this case, you should use the three-part menu -entry format, which saves the reader from having to type the file -name.@refill - -@need 800 -The format looks like this:@refill - -@example -@group -@@menu -* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} -* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} -@@end menu -@end group -@end example - -For example, to refer directly to the @samp{Outlining} and -@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a -menu like this:@refill - -@example -@group -@@menu -* Outlining: (emacs)Outline Mode. The major mode for - editing outlines. -* Rebinding: (emacs)Rebinding. How to redefine the - meaning of a key. -@@end menu -@end group -@end example - -If you do not list the node name, but only name the file, then Info -presumes that you are referring to the `Top' node.@refill - -The @file{dir} file that contains the main menu for Info has menu -entries that list only file names. These take you directly to the `Top' -nodes of each Info document. (@xref{Installing an Info File}.) - -@need 700 -For example: - -@example -@group -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -@end group -@end example - -@noindent -(The @file{dir} top level directory for the Info system is an Info file, -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. - - -@node Cross References -@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. - -@menu -* References:: What cross references are for. -* Cross Reference Commands:: A summary of the different commands. -* Cross Reference Parts:: A cross reference has several parts. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. -@end menu - -@node References -@section What References Are For - -Often, but not always, a printed document should be designed so that -it can be read sequentially. People tire of flipping back and forth -to find information that should be presented to them as they need -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 -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 -references to help readers find other information that they may not -have read.@refill - -In a printed manual, a cross reference results in a page reference, -unless it is to another manual altogether, in which case the cross -reference names that manual.@refill - -In Info, a cross reference results in an entry that you can follow -using the Info @samp{f} command. (@inforef{Help-Xref, Following -cross-references, info}.) - -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 - -@need 800 -@node Cross Reference Commands -@comment node-name, next, previous, up -@section Different Cross Reference Commands -@cindex Different cross reference commands - -There are four different cross reference commands:@refill - -@table @code -@item @@xref -Used to start a sentence in the printed manual saying @w{`See @dots{}'} -or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}. - -@item @@ref -Used within or, more often, at the end of a sentence; same as -@code{@@xref} for Info; produces just the reference in the printed -manual without a preceding `See'.@refill - -@item @@pxref -Used within parentheses to make a reference that suits both an Info -file and a printed book. Starts with a lower case `see' within the -printed manual. (@samp{p} is for `parenthesis'.)@refill - -@item @@inforef -Used to make a reference to an Info file for which there is no printed -manual.@refill -@end table - -@noindent -(The @code{@@cite} command is used to make references to books and -manuals for which there is no corresponding Info file and, therefore, -no node to which to point. @xref{cite, , @code{@@cite}}.)@refill - -@node Cross Reference Parts -@comment node-name, next, previous, up -@section Parts of a Cross Reference -@cindex Cross reference parts -@cindex Parts of a cross reference - -A cross reference command requires only one argument, which is the -name of the node to which it refers. But a cross reference command -may contain up to four additional arguments. By using these -arguments, you can provide a cross reference name for Info, a topic -description or section title for the printed output, the name of a -different Info file, and the name of a different printed -manual.@refill - -Here is a simple cross reference example:@refill - -@example -@@xref@{Node name@}. -@end example - -@noindent -which produces - -@example -*Note Node name::. -@end example - -@noindent -and - -@quotation -See Section @var{nnn} [Node name], page @var{ppp}. -@end quotation - -@need 700 -Here is an example of a full five-part cross reference:@refill - -@example -@group -@@xref@{Node name, Cross Reference Name, Particular Topic, -info-file-name, A Printed Manual@}, for details. -@end group -@end example - -@noindent -which produces - -@example -*Note Cross Reference Name: (info-file-name)Node name, -for details. -@end example - -@noindent -in Info and - -@quotation -See section ``Particular Topic'' in @i{A Printed Manual}, for details. -@end quotation - -@noindent -in a printed book. - -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 -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 - -@item -The cross reference name for the Info reference, if it is to be -different from the node name or the topic description. If you -include this argument, it becomes the first part of the cross reference. -It is usually omitted; then the topic description (third argument) is -used if it was specified; if that was omitted as well, the node name -is used. - -@item -A topic description or section name. Often, this is the title of the -section. This is used as the name of the reference in the printed -manual. If omitted, the node name is used.@refill - -@item -The name of the Info file in which the reference is located, if it is -different from the current file. You need not include any @samp{.info} -suffix on the file name, since Info readers try appending it -automatically. - -@item -The name of a printed manual from a different Texinfo file.@refill -@end enumerate - -The template for a full five argument cross reference looks like -this:@refill - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -Cross references with one, two, three, four, and five arguments are -described separately following the description of @code{@@xref}.@refill - -Write a node name in a cross reference in exactly the same way as in -the @code{@@node} line, including the same capitalization; otherwise, the -formatters may not find the reference.@refill - -You can write cross reference commands within a paragraph, but note -how Info and @TeX{} format the output of each of the various commands: -write @code{@@xref} at the beginning of a sentence; write -@code{@@pxref} only within parentheses, and so on.@refill - -@node xref -@comment node-name, next, previous, up -@section @code{@@xref} -@findex xref -@cindex Cross references using @code{@@xref} -@cindex References using @code{@@xref} - -The @code{@@xref} command generates a cross reference for the -beginning of a sentence. The Info formatting commands convert it into -an Info cross reference, which the Info @samp{f} command can use to -bring you directly to another node. The @TeX{} typesetting commands -convert it into a page reference, or a reference to another book or -manual.@refill - -@menu -* Reference Syntax:: What a reference looks like and requires. -* One Argument:: @code{@@xref} with one argument. -* Two Arguments:: @code{@@xref} with two arguments. -* Three Arguments:: @code{@@xref} with three arguments. -* Four and Five Arguments:: @code{@@xref} with four and five arguments. -@end menu - -@node Reference Syntax -@subsection What a Reference Looks Like and Requires - -Most often, an Info cross reference looks like this:@refill - -@example -*Note @var{node-name}::. -@end example - -@noindent -or like this - -@example -*Note @var{cross-reference-name}: @var{node-name}. -@end example - -@noindent -In @TeX{}, a cross reference looks like this: - -@quotation -See Section @var{section-number} [@var{node-name}], page @var{page}. -@end quotation - -@noindent -or like this - -@quotation -See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end quotation - -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. -You must write that period or comma yourself; otherwise, Info will not -recognize the end of the reference. (The @code{@@pxref} command works -differently. @xref{pxref, , @code{@@pxref}}.)@refill - -@quotation Caution -A period or comma @strong{must} follow the closing -brace of an @code{@@xref}. It is required to terminate the cross -reference. This period or comma will appear in the output, both in -the Info file and in the printed manual.@refill -@end quotation - -@code{@@xref} must refer to an Info node by name. Use @code{@@node} -to define the node (@pxref{Writing a Node}).@refill - -@code{@@xref} is followed by several arguments inside braces, separated by -commas. Whitespace before and after these commas is ignored.@refill - -A cross reference requires only the name of a node; but it may contain -up to four additional arguments. Each of these variations produces a -cross reference that looks somewhat different.@refill - -@quotation Note -Commas separate arguments in a cross reference; -avoid including them in the title or other part lest the formatters -mistake them for separators.@refill -@end quotation - -@node One Argument -@subsection @code{@@xref} with One Argument - -The simplest form of @code{@@xref} takes one argument, the name of -another node in the same Info file. The Info formatters produce -output that the Info readers can use to jump to the reference; @TeX{} -produces output that specifies the page and section number for you.@refill - -@need 700 -@noindent -For example, - -@example -@@xref@{Tropical Storms@}. -@end example - -@noindent -produces - -@example -*Note Tropical Storms::. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Tropical Storms@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Tropical Storms::, for more info. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Two Arguments -@subsection @code{@@xref} with Two Arguments - -With two arguments, the second is used as the name of the Info cross -reference, while the first is still the name of the node to which the -cross reference points.@refill - -@need 750 -@noindent -The template is like this: - -@example -@@xref@{@var{node-name}, @var{cross-reference-name}@}. -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning@}. -@end example - -@noindent -produces: - -@example -*Note Lightning: Electrical Effects. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57. -@end quotation - -@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.) - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Electrical Effects, Lightning@}, for more info. -@end example - -@noindent -which produces -@example -*Note Lightning: Electrical Effects, for more info. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Three Arguments -@subsection @code{@@xref} with Three Arguments - -A third argument replaces the node name in the @TeX{} output. The third -argument should be the name of the section in the printed output, or -else state the topic discussed by that section. Often, you will want to -use initial upper case letters so it will be easier to read when the -reference is printed. Use a third argument when the node name is -unsuitable because of syntax or meaning.@refill - -Remember to avoid placing a comma within the title or topic section of -a cross reference, or within any other section. The formatters divide -cross references into arguments according to the commas; a comma -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 -@code{@@xref} to terminate the cross reference. In the following -examples, a clause follows a terminating comma.@refill - - -@need 750 -@noindent -The template is like this: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -If a third argument is given and the second one is empty, then the -third argument serves both. (Note how two commas, side by side, mark -the empty second argument.)@refill - -@example -@group -@@xref@{Electrical Effects, , Thunder and Lightning@}, -for details. -@end group -@end example - -@noindent -produces - -@example -*Note Thunder and Lightning: Electrical Effects, for details. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -As a practical matter, it is often best to write cross references with -just the first argument if the node name and the section title are the -same, and with the first and third arguments if the node name and title -are different.@refill - -Here are several examples from @cite{The GNU Awk User's Guide}:@refill - -@smallexample -@@xref@{Sample Program@}. -@@xref@{Glossary@}. -@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. -@@xref@{Close Output, , Closing Output Files and Pipes@}, - for more information. -@@xref@{Regexp, , Regular Expressions as Patterns@}. -@end smallexample - -@node Four and Five Arguments -@subsection @code{@@xref} with Four and Five Arguments - -In a cross reference, a fourth argument specifies the name of another -Info file, different from the file in which the reference appears, and -a fifth argument specifies its title as a printed manual.@refill - -Remember that a comma or period must follow the closing brace of an -@code{@@xref} command to terminate the cross reference. In the -following examples, a clause follows a terminating comma.@refill - -@need 800 -@noindent -The template is: - -@example -@group -@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, -@var{info-file-name}, @var{printed-manual-title}@}. -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, Lightning, Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -*Note Lightning: (weather)Electrical Effects, for details. -@end example - -@noindent -The name of the Info file is enclosed in parentheses and precedes -the name of the node. - -@noindent -In a printed manual, the reference looks like this:@refill - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -@noindent -The title of the printed manual is typeset in italics; and the -reference lacks a page number since @TeX{} cannot know to which page a -reference refers when that reference is to another manual.@refill - -Often, you will leave out the second argument when you use the long -version of @code{@@xref}. In this case, the third argument, the topic -description, will be used as the cross reference name in Info.@refill - -@noindent -The template looks like this: - -@example -@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, -@var{printed-manual-title}@}, for details. -@end example - -@noindent -which produces - -@example -*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. -@end example - -@noindent -and - -@quotation -See section @var{title-or-topic} in @var{printed-manual-title}, for details. -@end quotation - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, , Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -@group -*Note Thunder and Lightning: (weather)Electrical Effects, -for details. -@end group -@end example - -@noindent -and - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -On rare occasions, you may want to refer to another Info file that -is within a single printed manual---when multiple Texinfo files are -incorporated into the same @TeX{} run but make separate Info files. -In this case, you need to specify only the fourth argument, and not -the fifth.@refill - -@node Top Node Naming -@section Naming a `Top' Node -@cindex Naming a `Top' Node in references -@cindex @samp{@r{Top}} node naming for references - -In a cross reference, you must always name a node. This means that in -order to refer to a whole manual, you must identify the `Top' node by -writing it as the first argument to the @code{@@xref} command. (This -is different from the way you write a menu entry; see @ref{Other Info -Files, , Referring to Other Info Files}.) At the same time, to -provide a meaningful section topic or title in the printed cross -reference (instead of the word `Top'), you must write an appropriate -entry for the third argument to the @code{@@xref} command. -@refill - -@noindent -Thus, to make a cross reference to @cite{The GNU Make Manual}, -write:@refill - -@example -@@xref@{Top, , Overview, make, The GNU Make Manual@}. -@end example - -@noindent -which produces - -@example -*Note Overview: (make)Top. -@end example - -@noindent -and - -@quotation -See section ``Overview'' in @i{The GNU Make Manual}. -@end quotation - -@noindent -In this example, @samp{Top} is the name of the first node, and -@samp{Overview} is the name of the first section of the manual. - - -@node ref -@section @code{@@ref} -@cindex Cross references using @code{@@ref} -@cindex References using @code{@@ref} -@findex ref - -@code{@@ref} is nearly the same as @code{@@xref} except that it does -not generate a `See' in the printed output, just the reference itself. -This makes it useful as the last part of a sentence. - -@noindent For example, - -@cindex Hurricanes -@example -For more information, @@pxref@{This@}, and @@ref@{That@}. -@end example - -@noindent produces in Info: - -@example -For more information, *note This::, and *note That::. -@end example - -@noindent and in printed output: - -@quotation -For more information, see Section 1.1 [This], page 1, -and Section 1.2 [That], page 2. -@end quotation - -The @code{@@ref} command sometimes tempts writers to express -themselves in a manner that is suitable for a printed manual but looks -awkward in the Info format. Bear in mind that your audience will be -using both the printed and the Info format. For example: - -@cindex Sea surges -@example -Sea surges are described in @@ref@{Hurricanes@}. -@end example - -@noindent looks ok in the printed output: - -@quotation -Sea surges are described in Section 6.7 [Hurricanes], page 72. -@end quotation - -@noindent but is awkward to read in Info, ``note'' being a verb: - -@example -Sea surges are described in *note Hurricanes::. -@end example - -You should write a period or comma immediately after an @code{@@ref} -command with two or more arguments. If there is no such following -punctuation, @command{makeinfo} will generate a (grammatically -incorrect) period in the Info output; otherwise, the cross-reference -would fail completely, due to the current syntax of Info format. - -In general, it is best to use @code{@@ref} only when you need some -word other than ``see'' to precede the reference. When ``see'' (or -``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable. - - -@node pxref -@section @code{@@pxref} -@cindex Cross references using @code{@@pxref} -@cindex References using @code{@@pxref} -@findex pxref - -The parenthetical reference command, @code{@@pxref}, is nearly the -same as @code{@@xref}, but it is best used at the end of a sentence or -before a closing parenthesis. The command differs from @code{@@xref} -in two ways: - -@enumerate -@item -@TeX{} typesets the reference for the printed manual with a lower case -`see' rather than an upper case `See'. - -@item -The Info formatting commands automatically end the reference with a -closing colon or period, if necessary. -@end enumerate - -@code{@@pxref} is designed so that the output looks right and works -right at the end of a sentence or parenthetical phrase, both in -printed output and in an Info file. In a printed manual, a closing -comma or period should not follow a cross reference within -parentheses; such punctuation is wrong. But in an Info file, suitable -closing punctuation must follow the cross reference so Info can -recognize its end. @code{@@pxref} spares you the need to use -complicated methods to put a terminator into one form of the output -and not the other. - -@noindent -With one argument, a parenthetical cross reference looks like this: - -@cindex Flooding -@example -@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} -@end example - -@need 800 -@noindent -which produces - -@example -@group -@dots{} storms cause flooding (*note Hurricanes::) @dots{} -@end group -@end example - -@noindent -and - -@quotation -@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} -@end quotation - -With two arguments, a parenthetical cross reference has this template: - -@example -@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} -@end example - -@noindent -which produces - -@example -@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{} -@end example - -@noindent -and - -@quotation -@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} -@end quotation - -@code{@@pxref} can be used with up to five arguments, just like -@code{@@xref} (@pxref{xref, , @code{@@xref}}). - -In past versions of Texinfo, it was not allowed to write punctuation -after a @code{@@pxref}, so it could be used @emph{only} before a right -parenthesis. This is no longer the case, so now it can be used (for -example) at the end of a sentence, where a lowercase ``see'' works -best. For instance: - -@example -@dots{} For more information, @@pxref@{More@}. -@end example - -@noindent -which outputs (in Info): - -@example -@dots{} For more information, *note More::. -@end example - -@noindent -This works fine. @code{@@pxref} should only be followed by a comma, -period, or right parenthesis; in other cases, @command{makeinfo} has -to insert a period to make the cross-reference work correctly in Info, -and that period looks wrong. - -As a matter of general style, @code{@@pxref} is best used at the ends -of sentences. Although it technically works in the middle of a -sentence, that location breaks up the flow of reading. - - -@node inforef -@section @code{@@inforef} -@cindex Cross references using @code{@@inforef} -@cindex References using @code{@@inforef} -@findex inforef - -@code{@@inforef} is used for making cross references to Info -documents---even from a printed manual. This might be because you -want to refer to conditional @code{@@ifinfo} text -(@pxref{Conditionals}), or because printed output is not available -(perhaps because there is no Texinfo source), among other -possibilities. - -The command takes either two or three arguments, in the following -order:@refill - -@enumerate -@item -The node name. - -@item -The cross reference name (optional). - -@item -The Info file name. -@end enumerate - -@noindent -Separate the arguments with commas, as with @code{@@xref}. Also, you -must terminate the reference with a comma or period after the -@samp{@}}, as you do with @code{@@xref}.@refill - -@noindent -The template is: - -@example -@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, -@end example - -@need 800 -@noindent -For example, - -@example -@group -@@inforef@{Advanced, Advanced Info commands, info@}, -for more information. -@end group -@end example - -@need 800 -@noindent -produces (in Info): - -@example -@group -*Note Advanced Info commands: (info)Advanced, -for more information. -@end group -@end example - -@need 800 -@noindent -and (in the printed output): - -@quotation -See Info file @file{info}, node @samp{Advanced}, for more information. -@end quotation - -(This particular example is not realistic, since the Info manual is -written in Texinfo, so all formats are available.) - -The converse of @code{@@inforef} is @code{@@cite}, which is used to -refer to printed works for which no Info form exists. @xref{cite, , -@code{@@cite}}. - - -@node uref -@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} -@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. - -@code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url} -had the meaning of @code{@@indicateurl} -(@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it -was misused the vast majority of the time. So we've changed the -meaning. - -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, if specified, is the text to display, but in this -case 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. - -If the url is long enough to cause problems with line breaking, you -may find it useful to insert @code{@@/} at places where a line break -would be acceptable (after @samp{/} characters, for instance). This -tells @TeX{} to allow (but not force) a line break at those places. -@xref{Line Breaks}. - -Here is an example of the simple one argument form, where the url is -both the target and the text of the link: - -@example -The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}. -@end example - -@noindent produces: -@display -The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. -@end display - - -An example of the two-argument form: -@example -The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} -holds programs and texts. -@end example - -@noindent produces: -@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 <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> -holds programs and texts. -@end example - - -An example of the three-argument form: -@example -The @@uref@{/man.cgi/1/ls,,ls@} program @dots{} -@end example - -@noindent produces: -@display -The @uref{/man.cgi/1/ls,,ls} program @dots{} -@end display - -@noindent but with HTML: -@example -The <a href="/man.cgi/1/ls">ls</a> program @dots{} -@end example - -To merely indicate a url without creating a link people can follow, use -@code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}). - -Some people prefer to display url's in the unambiguous format: - -@display -<URL:http://@var{host}/@var{path}> -@end display - -@noindent -@cindex <URL: convention, not used -You can use this form in the input file if you wish. We feel it's not -necessary to include the @samp{<URL:} and @samp{>} in the output, -since any software that tries to detect url's in text already has to -detect them without the @samp{<URL:} to be useful. - - -@node Marking Text -@chapter Marking Words and Phrases -@cindex Paragraph, marking text within -@cindex Marking words and phrases -@cindex Words and phrases, marking them -@cindex Marking text within a paragraph -@cindex Text, marking up - -In Texinfo, you can mark words and phrases in a variety of ways. -The Texinfo formatters use this information to determine how to -highlight the text. -You can specify, for example, whether a word or phrase is a -defining occurrence, a metasyntactic variable, or a symbol used in a -program. Also, you can emphasize text, in several different ways. - -@menu -* Indicating:: How to indicate definitions, files, etc. -* Emphasis:: How to emphasize text. -@end menu - - -@node Indicating -@section Indicating Definitions, Commands, etc. -@cindex Highlighting text -@cindex Indicating commands, definitions, etc. - -Texinfo has commands for indicating just what kind of object a piece of -text refers to. For example, metasyntactic variables are marked by -@code{@@var}, and code by @code{@@code}. Since the pieces of text are -labelled by commands that tell what kind of object they are, it is easy -to change the way the Texinfo formatters prepare such text. (Texinfo is -an @emph{intentional} formatting language rather than a @emph{typesetting} -formatting language.)@refill - -For example, in a printed manual, -code is usually illustrated in a typewriter font; -@code{@@code} tells @TeX{} to typeset this text in this font. But it -would be easy to change the way @TeX{} highlights code to use another -font, and this change would not affect how keystroke examples are -highlighted. If straight typesetting commands were used in the body -of the file and you wanted to make a change, you would need to check -every single occurrence to make sure that you were changing code and -not something else that should not be changed.@refill - -@menu -* Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: Indicating a literal sequence of characters. -* verb:: Indicating a verbatim 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. -* abbr:: Indicating abbreviations. -* acronym:: Indicating acronyms. -* indicateurl:: Indicating an example URL. -* email:: Indicating an electronic mail address. -@end menu - - -@node Useful Highlighting -@subsection Highlighting Commands are Useful - -The highlighting commands can be used to extract useful information -from the file, such as lists of functions or file names. It is -possible, for example, to write a program in Emacs Lisp (or a keyboard -macro) to insert an index entry after every paragraph that contains -words or phrases marked by a specified command. You could do this to -construct an index of functions if you had not already made the -entries.@refill - -The commands serve a variety of purposes:@refill - -@table @code -@item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program. -@xref{code,,@code{@@code}}. - -@item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input. -@xref{kbd,,@code{@@kbd}}. - -@item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard. -@xref{key,,@code{@@key}}. - -@item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters. -@xref{samp,,@code{@@samp}}. - -@item @@verb@{@var{text}@} -Write a verbatim sequence of characters. -@xref{verb,,@code{@@verb}}. - -@item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable. -@xref{var,,@code{@@var}}. - -@item @@env@{@var{environment-variable}@} -Indicate an environment variable. -@xref{env,,@code{@@env}}. - -@item @@file@{@var{file-name}@} -Indicate the name of a file. -@xref{file,,@code{@@file}}. - -@item @@command@{@var{command-name}@} -Indicate the name of a command. -@xref{command,,@code{@@command}}. - -@item @@option@{@var{option}@} -Indicate a command-line option. -@xref{option,,@code{@@option}}. - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term. -@xref{dfn,,@code{@@dfn}}. - -@item @@cite@{@var{reference}@} -Indicate the name of a book. -@xref{cite,,@code{@@cite}}. - -@item @@abbr@{@var{abbreviation}@} -Indicate an abbreviation. - -@item @@acronym@{@var{acronym}@} -Indicate an acronym. -@xref{acronym,,@code{@@acronym}}. - -@item @@indicateurl@{@var{uniform-resource-locator}@} -Indicate an example (that is, nonfunctional) uniform resource locator. -@xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url} -(@pxref{uref,,@code{@@url}}) for live url's.) - -@item @@email@{@var{email-address}[, @var{displayed-text}]@} -Indicate an electronic mail address. -@xref{email,,@code{@@email}}. - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Use for an ASCII control character. -@end ignore -@end table - - -@node code -@subsection @code{@@code}@{@var{sample-code}@} -@findex code - -@cindex Syntactic tokens, indicating -Use the @code{@@code} command to indicate text that is a piece of a -program and which consists of entire syntactic tokens. Enclose the -text in braces. - -@cindex Expressions in a program, indicating -@cindex Keywords, indicating -@cindex Reserved words, indicating -Thus, you should use @code{@@code} for an expression in a program, for -the name of a variable or function used in a program, or for a -keyword in a programming language. - -Use @code{@@code} for command names in languages that resemble -programming languages, such as Texinfo. For example, @code{@@code} and -@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and -@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively. - -@cindex Case, not altering in @code{@@code} -It is incorrect to alter the case of a word inside an @code{@@code} -command when it appears at the beginning of a sentence. Most computer -languages are case sensitive. In C, for example, @code{Printf} is -different from the identifier @code{printf}, and most likely is a -misspelling of it. Even in languages which are not case sensitive, it -is confusing to a human reader to see identifiers spelled in different -ways. Pick one spelling and always use that. If you do not want to -start a sentence with a command name written all in lower case, you -should rearrange the sentence. - -In the printed manual, @code{@@code} causes @TeX{} to typeset the -argument in a typewriter face. In the Info file, it causes the Info -formatting commands to use single quotation marks around the text. -For example, - -@example -The function returns @@code@{nil@}. -@end example - -@noindent -produces this: - -@quotation -The function returns @code{nil}. -@end quotation - -@iftex -@noindent -and this in the Info file: -@example -The function returns `nil'. -@end example -@end iftex - -Here are some cases for which it is preferable @emph{not} to use @code{@@code}: - -@itemize @bullet -@item -For shell command names such as @command{ls} (use @code{@@command}). - -@item -For shell options such as @samp{-c} when such options stand alone (use -@code{@@option}). - -@item -Also, an entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format. - -@item -For environment variable such as @env{TEXINPUTS} (use @code{@@env}). - -@item -For a string of characters shorter than a syntactic token. For example, -if you are writing about @samp{goto-ch}, which is just a part of the -name for the @code{goto-char} Emacs Lisp function, you should use -@code{@@samp}. - -@item -In general, when writing about the characters used in a token; for -example, do not use @code{@@code} when you are explaining what letters -or printable symbols can be used in the names of functions. (Use -@code{@@samp}.) Also, you should not use @code{@@code} to mark text -that is considered input to programs unless the input is written in a -language that is like a programming language. For example, you should -not use @code{@@code} for the keystroke commands of GNU Emacs (use -@code{@@kbd} instead) although you may use @code{@@code} for the names -of the Emacs Lisp functions that the keystroke commands invoke. - -@end itemize - -Since @code{@@command}, @code{@@option}, and @code{@@env} were -introduced relatively recently, it is acceptable to use @code{@@code} or -@code{@@samp} for command names, options, and environment variables. -The new commands allow you to express the markup more precisely, but -there is no real harm in using the older commands, and of course the -long-standing manuals do so. - -Ordinarily, @TeX{} will consider breaking lines at @samp{-} and -@samp{_} characters within @code{@@code} and related commands. This -can be controlled with @code{@@allowcodebreaks} -(@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}). - - -@node kbd -@subsection @code{@@kbd}@{@var{keyboard-characters}@} -@findex kbd -@cindex Keyboard input - -Use the @code{@@kbd} command for characters of input to be typed by -users. For example, to refer to the characters @kbd{M-a}, write: - -@example -@@kbd@{M-a@} -@end example - -@noindent -and to refer to the characters @kbd{M-x shell}, write: - -@example -@@kbd@{M-x shell@} -@end example - -@cindex User input -@cindex Slanted typewriter font, for @code{@@kbd} -By default, the @code{@@kbd} command produces a different font -(slanted typewriter instead of normal typewriter) in the printed -manual, so users can distinguish the characters that they are supposed -to type from those that the computer outputs. - -In Info output, @code{@@kbd} is usually the same as @code{@@code}, -producing `quotes' around its argument. However, in typewriter-like -contexts such as the @code{@@example} environment (@pxref{example}) -and @code{@@code} command itself, the quotes are omitted, since Info -format cannot use distinguishing fonts. - -@findex kbdinputstyle -Since the usage of @code{@@kbd} varies from manual to manual, you can -control the font switching with the @code{@@kbdinputstyle} command. -This command has no effect on Info output. Write this command at the -beginning of a line with a single word as an argument, one of the -following: - -@vindex distinct@r{, value for @code{@@kbdinputstyle}} -@vindex example@r{, value for @code{@@kbdinputstyle}} -@vindex code@r{, value for @code{@@kbdinputstyle}} -@table @samp -@item code -Always use the same font for @code{@@kbd} as @code{@@code}. -@item example -Use the distinguishing font for @code{@@kbd} only in @code{@@example} -and similar environments. -@item distinct -(the default) Always use the distinguishing font for @code{@@kbd}. -@end table - -You can embed another @@-command inside the braces of an @code{@@kbd} -command. Here, for example, is the way to describe a command that -would be described more verbosely as ``press the @samp{r} key and then -press the @key{RETURN} key'': - -@example -@@kbd@{r @@key@{RET@}@} -@end example - -@noindent -This produces: @kbd{r @key{RET}}. (The present manual accepts the -default for @code{@@kbdinputstyle}.) - -You also use the @code{@@kbd} command if you are spelling out the letters -you type; for example: - -@example -To give the @@code@{logout@} command, -type the characters @@kbd@{l o g o u t @@key@{RET@}@}. -@end example - -@noindent -This produces: - -@quotation -To give the @code{logout} command, -type the characters @kbd{l o g o u t @key{RET}}. -@end quotation - -(Also, this example shows that you can add spaces for clarity. If you -explicitly want to mention a space character as one of the characters of -input, write @kbd{@@key@{SPC@}} for it.)@refill - - -@node key -@subsection @code{@@key}@{@var{key-name}@} -@findex key - -Use the @code{@@key} command for the conventional name for a key on a -keyboard, as in:@refill - -@example -@@key@{RET@} -@end example - -You can use the @code{@@key} command within the argument of an -@code{@@kbd} command when the sequence of characters to be typed -includes one or more keys that are described by name.@refill - -For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you -would type: - -@example -@@kbd@{C-x @@key@{ESC@}@} -@@kbd@{M-@@key@{TAB@}@} -@end example - -Here is a list of the recommended names for keys: -@cindex Recommended names for keys -@cindex Keys, recommended names -@cindex Names recommended for keys -@cindex Abbreviations for keys - -@quotation -@table @t -@item SPC -Space -@item RET -Return -@item LFD -Linefeed (however, since most keyboards nowadays do not have a Linefeed key, -it might be better to call this character @kbd{C-j}) -@item TAB -Tab -@item BS -Backspace -@item ESC -Escape -@item DELETE -Delete -@item SHIFT -Shift -@item CTRL -Control -@item META -Meta -@end table -@end quotation - -@cindex META key -There are subtleties to handling words like `meta' or `ctrl' that are -names of modifier keys. When mentioning a character in which the -modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command -alone; do not use the @code{@@key} command; but when you are referring -to the modifier key in isolation, use the @code{@@key} command. For -example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and -@samp{@@key@{META@}} to produce @key{META}. - -As a convention in GNU manuals, @code{@@key} should not be used in -index entries. - - -@node samp -@subsection @code{@@samp}@{@var{text}@} -@findex samp - -Use the @code{@@samp} command to indicate text that is a literal example -or `sample' of a sequence of characters in a file, string, pattern, etc. -Enclose the text in braces. The argument appears within single -quotation marks in both the Info file and the printed manual; in -addition, it is printed in a fixed-width font.@refill - -@example -To match @@samp@{foo@} at the end of the line, -use the regexp @@samp@{foo$@}. -@end example - -@noindent -produces - -@quotation -To match @samp{foo} at the end of the line, use the regexp -@samp{foo$}.@refill -@end quotation - -Any time you are referring to single characters, you should use -@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. -Also, you may use @code{@@samp} for entire statements in C and for entire -shell commands---in this case, @code{@@samp} often looks better than -@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is -not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill - -Only include punctuation marks within braces if they are part of the -string you are specifying. Write punctuation marks outside the braces -if those punctuation marks are part of the English text that surrounds -the string. In the following sentence, for example, the commas and -period are outside of the braces:@refill - -@example -@group -In English, the vowels are @@samp@{a@}, @@samp@{e@}, -@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes -@@samp@{y@}. -@end group -@end example - -@noindent -This produces: - -@quotation -In English, the vowels are @samp{a}, @samp{e}, -@samp{i}, @samp{o}, @samp{u}, and sometimes -@samp{y}. -@end quotation - - -@node verb -@subsection @code{@@verb}@{<char>@var{text}<char>@} -@findex verb -@cindex Verbatim in-line text - -@cindex Delimiter character, for verbatim -Use the @code{@@verb} command to print a verbatim sequence of -characters. - -Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using -any unique delimiter character. Enclose the verbatim text, including the -delimiters, in braces. Text is printed in a fixed-width font: - -@example -How many @@verb@{|@@|@}-escapes does one need to print this -@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this? -@end example - -@noindent -produces - -@example -How many @verb{|@|}-escapes does one need to print this -@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this? -@end example - -This is in contrast to @code{@@samp} (see the previous section), -@code{@@code}, and similar commands; in those cases, the argument is -normal Texinfo text, where the three characters @code{@@@{@}} are -special. With @code{@@verb}, nothing is special except the delimiter -character you choose. - -It is not reliable to use @code{@@verb} inside other Texinfo -constructs. In particular, it does not work to use @code{@@verb} in -anything related to cross-referencing, such as section titles or -figure captions. - - -@node var -@subsection @code{@@var}@{@var{metasyntactic-variable}@} -@findex var - -Use the @code{@@var} command to indicate metasyntactic variables. A -@dfn{metasyntactic variable} is something that stands for another piece of -text. For example, you should use a metasyntactic variable in the -documentation of a function to describe the arguments that are passed -to that function.@refill - -Do not use @code{@@var} for the names of particular variables in -programming languages. These are specific names from a program, so -@code{@@code} is correct for them (@pxref{code}). For example, the -Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic -variable; it is properly formatted using @code{@@code}. - -Do not use @code{@@var} for environment variables either; @code{@@env} -is correct for them (see the next section). - -The effect of @code{@@var} in the Info file is to change the case of the -argument to all upper case. In the printed manual and HTML output, the -argument is printed in slanted type. - -@need 700 -For example, - -@example -To delete file @@var@{filename@}, -type @@samp@{rm @@var@{filename@}@}. -@end example - -@noindent -produces - -@quotation -To delete file @var{filename}, type @samp{rm @var{filename}}. -@end quotation - -@noindent -(Note that @code{@@var} may appear inside @code{@@code}, -@code{@@samp}, @code{@@file}, etc.)@refill - -Write a metasyntactic variable all in lower case without spaces, and -use hyphens to make it more readable. Thus, the Texinfo source for -the illustration of how to begin a Texinfo manual looks like -this:@refill - -@example -@group -\input texinfo -@@@@setfilename @@var@{info-file-name@} -@@@@settitle @@var@{name-of-manual@} -@end group -@end example - -@noindent -This produces: - -@example -@group -\input texinfo -@@setfilename @var{info-file-name} -@@settitle @var{name-of-manual} -@end group -@end example - -In some documentation styles, metasyntactic variables are shown with -angle brackets, for example:@refill - -@example -@dots{}, type rm <filename> -@end example - -@noindent -However, that is not the style that Texinfo uses. (You can, of -course, modify the sources to @file{texinfo.tex} and the Info formatting commands -to output the @code{<@dots{}>} 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 @dots{} -@end example -@noindent produces -@quotation -The @env{PATH} environment variable @dots{} -@end quotation - - -@node file -@subsection @code{@@file}@{@var{file-name}@} -@findex file - -Use the @code{@@file} command to indicate text that is the name of a -file, buffer, or directory, or is the name of a node in Info. You can -also use the command for file name suffixes. Do not use @code{@@file} -for symbols in a programming language; use @code{@@code}. - -Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. -For example,@refill - -@example -The @@file@{.el@} files are in -the @@file@{/usr/local/emacs/lisp@} directory. -@end example - -@noindent -produces - -@quotation -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 -@comment node-name, next, previous, up -@subsection @code{@@dfn}@{@var{term}@} -@findex dfn - -Use the @code{@@dfn} command to identify the introductory or defining -use of a technical term. Use the command only in passages whose -purpose is to introduce a term which will be used again or which the -reader ought to know. Mere passing mention of a term for the first -time does not deserve @code{@@dfn}. The command generates italics in -the printed manual, and double quotation marks in the Info file. For -example:@refill - -@example -Getting rid of a file is called @@dfn@{deleting@} it. -@end example - -@noindent -produces - -@quotation -Getting rid of a file is called @dfn{deleting} it. -@end quotation - -As a general rule, a sentence containing the defining occurrence of a -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 -@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. - -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}}. - - -@ignore -@c node ctrl, , cite, Indicating -@comment node-name, next, previous, up -@c subsection @code{@@ctrl}@{@var{ctrl-char}@} -@findex ctrl - -The @code{@@ctrl} command is seldom used. It describes an ASCII -control character by inserting the actual character into the Info -file. - -Usually, in Texinfo, you talk what you type as keyboard entry by -describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for -@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control -character that is typed on the keyboard by the user. When talking -about a control character appearing in a file or a string, do not use -@code{@@kbd} since the control character is not typed. Also, do not -use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, -to make it easier for a reader to understand.@refill - -@code{@@ctrl} is an idea from the beginnings of Texinfo which may not -really fit in to the scheme of things. But there may be times when -you want to use the command. The pattern is -@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character -whose control-equivalent is wanted. For example, to specify -@samp{control-f}, you would enter@refill - -@example -@@ctrl@{f@} -@end example - -@noindent -produces - -@quotation -@ctrl{f} -@end quotation - -In the Info file, this generates the specified control character, output -literally into the file. This is done so a user can copy the specified -control character (along with whatever else he or she wants) into another -Emacs buffer and use it. Since the `control-h',`control-i', and -`control-j' characters are formatting characters, they should not be -indicated with @code{@@ctrl}.@refill - -In a printed manual, @code{@@ctrl} generates text to describe or -identify that control character: an uparrow followed by the character -@var{ch}.@refill -@end ignore - - -@node abbr -@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} -@findex abbr - -@cindex Abbreviations, tagging -You can use the @code{@@abbr} command for general abbreviations. The -abbreviation is given as the single argument in braces, as in -@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular -abbreviations, you may prefer to omit periods, as in -@samp{@@abbr@{Mr@} Stallman}. - -@code{@@abbr} accepts an optional second argument, intended to be used -for the meaning of the abbreviation. - -If the abbreviation ends with a lowercase letter and a period, and is -not at the end of a sentence, and has no second argument, remember to -use the @code{@@.} command (@pxref{Not Ending a -Sentence}) to get the correct spacing. However, you do not have to -use @code{@@.} within the abbreviation itself; Texinfo automatically -assumes periods within the abbreviation do not end a sentence. - -@cindex <abbr> tag -In @TeX{} and in the Info output, the first argument is printed as-is; -if the second argument is present, it is printed in parentheses after -the abbreviation. In HTML and XML, the @code{<abbr>} tag is -used; in Docbook, the @code{<abbrev>} tag is used. For instance: - -@example -@@abbr@{Comput. J., Computer Journal@} -@end example - -@noindent produces: - -@display -@abbr{Comput. J., Computer Journal} -@end display - -For abbreviations consisting of all capital letters, you may prefer to -use the @code{@@acronym} command instead. See the next section for -more on the usage of these two commands. - - -@node acronym -@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} -@findex acronym - -@cindex NASA, as acronym -@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 acronyms, you may prefer to -use periods, as in @samp{@@acronym@{N.A.S.A.@}}. - -@code{@@acronym} accepts an optional second argument, intended to be -used for the meaning of the acronym. - -If the acronym is at the end of a sentence, and if there is no second -argument, remember to use the @code{@@.} or similar command -(@pxref{Ending a Sentence}) to get the correct spacing. - -@cindex <acronym> tag -In @TeX{}, the acronym is printed in slightly smaller font. In the -Info output, the argument is printed as-is. In either format, if the -second argument is present, it is printed in parentheses after the -acronym. In HTML, Docbook, and XML, the @code{<acronym>} tag is -used. - -For instance (since GNU is a recursive acronym, we use -@code{@@acronym} recursively): - -@example -@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@} -@end example - -@noindent produces: - -@display -@acronym{GNU, @acronym{GNU}'s Not Unix} -@end display - -In some circumstances, it is conventional to print family names in all -capitals. Don't use @code{@@acronym} for this, since a name is not an -acronym. Use @code{@@sc} instead (@pxref{Smallcaps}). - -@code{@@abbr} and @code{@@acronym} are closely related commands: they -both signal to the reader that a shortened form is being used, and -possibly give a meaning. When choosing whether to use these two -commands, please bear the following in mind. - -@itemize @minus -@item -In standard English usage, acronyms are a subset of abbreviations: -they include pronounceable words like `@acronym{NATO}', `radar', and -`snafu', and some sources also include syllable acronyms like -`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable -initialisms like `@acronym{FBI}'. - -@item -In Texinfo, an acronym (but not an abbreviation) should consist only -of capital letters and periods, no lowercase. - -@item -In @TeX{}, an acronym (but not an abbreviation) is printed in a -slightly smaller font. - -@item -Some browsers place a dotted bottom border under abbreviations but not -acronyms. - -@item -It's not essential to use these commands for all abbreviations. Text -is perfectly readable without them. - -@end itemize - - -@node indicateurl -@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} -@findex indicateurl -@cindex Uniform resource locator, indicating -@cindex URL, indicating - -Use the @code{@@indicateurl} 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: - -@example -For example, the url might be @@indicateurl@{http://example.org/path@}. -@end example - -@noindent which produces: - -@display -For example, the url might be @indicateurl{http://example.org/path}. -@end display - - -@node email -@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} -@findex email - -Use the @code{@@email} command to indicate an electronic mail address. -It takes one mandatory argument, the address, and one optional argument, the -text to display (the default is the address itself). - -@cindex Mailto link -In Info, the address is shown in angle brackets, preceded by the text -to display if any. In @TeX{}, the angle brackets are omitted. In -HTML output, @code{@@email} produces a @samp{mailto} link that usually -brings up a mail composition window. For example: - -@example -Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, -suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. -@end example -@noindent produces -@display -Send bug reports to @email{bug-texinfo@@gnu.org}, -suggestions to the @email{bug-texinfo@@gnu.org, same place}. -@end display - - -@node Emphasis -@section Emphasizing Text -@cindex Emphasizing text - -Usually, Texinfo changes the font to mark words in the text according to -what category the words belong to; an example is the @code{@@code} command. -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, -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. -@end menu - -@node emph & strong -@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}. - -For example, - -@example -@group -@@strong@{Caution:@} @@samp@{rm * .[^.]*@} -removes @@emph@{all@} files in the directory. -@end group -@end example - -@noindent -produces the following in printed output and HTML: - -@quotation -@strong{Caution}: @samp{rm * .[^.]*} -removes @emph{all} files in the directory. -@end quotation - -@noindent -and the following in Info: - -@example -*Caution:* `rm * .[^.]*' removes _all_ -files in the directory. -@end example - -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. - -@quotation Caution -Do not use @code{@@strong} with the word @samp{Note}; Info will -mistake the combination for a cross reference. (It's usually -redundant, anyway.) Use a phrase such as @strong{Please notice} or -@strong{Caution} instead, or the optional argument to -@code{@@quotation}---@samp{Note} is allowable there. -@end quotation - - -@node Smallcaps -@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 @sc{a small caps font} -(where possible). Write the text you want to be in small caps between -braces in lower case, like this: - -@example -Richard @@sc@{Stallman@} founded @@acronym@{GNU@}. -@end example - -@noindent -This produces: - -@display -Richard @sc{Stallman} founded @acronym{GNU}. -@end display - -As shown here, we recommend using @code{@@acronym} for actual -acronyms (@pxref{acronym}), and reserving @code{@@sc} for special -cases where you want small caps. The output is not the same -(@code{@@acronym} prints in a smaller text font, not the small caps -font), but more importantly it describes the actual text more -accurately. - -Family names are one case where small capitals are sometimes desirable, -also as shown here. - -@cindex <small> tag -@TeX{} typesets any uppercase letters between the braces of an -@code{@@sc} command in full-size capitals; only lowercase letters are -printed in the small caps font. In the Info output, the argument to -@code{@@sc} is printed in all upper case. In HTML, the argument is -uppercased and the output marked with the @code{<small>} tag to reduce -the font size. - -Since it's redundant to mark all-uppercase text with @code{@@sc}, -@command{makeinfo} warns about such usage. - -We recommend using regular mixed case wherever possible. - - -@node Fonts -@subsection Fonts for Printing, Not Info -@cindex Fonts for printing, not Info - -@findex fonttextsize -@cindex Font size, reducing -@cindex Reducing font size -@cindex Smaller fonts -Texinfo provides one command to change the size of the main body font -in the @TeX{} output for a document: @code{@@fonttextsize}. It has no -effect at all in other output. It takes a single argument on the -remainder of the line, which must be either @samp{10} or @samp{11}. -For example: - -@example -@@fonttextsize 10 -@end example - -@cindex Printing cost, reducing -The effect is to reduce the body font to a 10@dmn{pt} size (the -default is 11@dmn{pt}). Fonts for other elements, such as sections -and chapters, are reduced accordingly. This should only be used in -conjunction with @code{@@smallbook} (@pxref{smallbook,,Printing -``Small'' Books}) or similar, since 10@dmn{pt} fonts on standard paper -(8.5x11 or A4) are too small. One reason to use this command is to -save pages, and hence printing cost, for physical books. - -Texinfo does not at present have commands to switch the font family -to use, or more general size-changing commands. - -@cindex Styles, font -Texinfo also provides a number of font commands that specify font changes -in the printed manual and (where possible) in the HTML output, but -have no effect in the Info file. All the commands apply to an -argument that follows, surrounded by braces. - -@table @code -@item @@b -@findex b @r{(bold font)} -@cindex Bold font -selects @b{bold} face; - -@item @@i -@findex i @r{(italic font)} -@cindex Italic font -selects an @i{italic} font; - -@item @@r -@findex r @r{(roman font)} -@cindex Roman font -@cindex Default font -selects a @r{roman} font, which is the usual font in which text is -printed. It may or may not be seriffed. - -@item @@sansserif -@findex sansserif @r{(sans serif font)} -@cindex Sans serif font -selects a @sansserif{sans serif} font; - -@item @@slanted -@findex slanted @r{(slanted font)} -@cindex Slanted font -@cindex Oblique font -selects a @slanted{slanted} font; - -@item @@t -@findex t @r{(typewriter font)} -@cindex Monospace font -@cindex Fixed-width font -@cindex Typewriter font -selects the @t{fixed-width}, typewriter-style font used by @code{@@code}; - -@end table - -(The commands with longer names were invented much later than the -others, at which time it did not seem desirable to use very short -names for such an infrequently needed feature.) - -@cindex <lineannotation> Docbook tag -Only the @code{@@r} command has much use: in example-like -environments, you can use the @code{@@r} command to write comments in -the standard roman font instead of the fixed-width font. This looks -better in printed output, and produces a @code{<lineannotation>} tag -in Docbook output. - -For example, - -@example -@group -@@lisp -(+ 2 2) ; @@r@{Add two plus two.@} -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -(+ 2 2) ; @r{Add two plus two.} -@end lisp - -In general, you should avoid using the other font commands. Some of -them are only useful when documenting functionality of specific font -effects, such as in @TeX{} and related packages. - - -@node Quotations and Examples -@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 in the output. - -@findex end -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, and with only one space between the @code{@@end} and the -@code{example}. - -@menu -* Block Enclosing Commands:: Different constructs for different purposes. -* quotation:: Writing a quotation. -* example:: Writing an example in a fixed-width font. -* verbatim:: Writing a verbatim example. -* verbatiminclude:: Including a file verbatim. -* lisp:: Illustrating Lisp code. -* small:: Examples in a smaller font. -* display:: Writing an example in the current font. -* format:: Writing an example without narrowed margins. -* exdent:: Undo indentation on a line. -* flushleft & flushright:: Pushing text flush left or flush right. -* noindent:: Preventing paragraph indentation. -* indent:: Forcing paragraph indentation. -* cartouche:: Drawing rounded rectangles around examples. -@end menu - - -@node Block Enclosing Commands -@section Block Enclosing Commands - -Here are commands for quotations and examples, explained further in the -following sections: - -@table @code -@item @@quotation -Indicate text that is quoted. The text is filled, indented (from both -margins), and printed in a roman font by default. - -@item @@example -Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled. - -@item @@verbatim -Mark a piece of text that is to be printed verbatim; no character -substitutions are made and all commands are ignored, until the next -@code{@@end verbatim}. The text is printed in a fixed-width font, -and not indented or filled. Extra spaces and blank lines are -significant, and tabs are expanded. - -@item @@smallexample -Same as @code{@@example}, except that in @TeX{} this command typesets -text in a smaller font. - -@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. - -@item @@smalllisp -Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}. - -@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 @@smalldisplay -Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}. - -@item @@format -Like @code{@@display} (the text is not filled and no font is selected), -but the text is not indented. - -@item @@smallformat -Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}. -@end table - -The @code{@@exdent} command is used within the above constructs to -undo the indentation of a line. - -The @code{@@flushleft} and @code{@@flushright} commands are used to line -up the left or right margins of unfilled text.@refill - -The @code{@@noindent} command may be used after one of the above -constructs to prevent the following text from being indented as a new -paragraph. - -You can use the @code{@@cartouche} environment around 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}. - - -@node quotation -@section @code{@@quotation}: Block quotations -@cindex Quotations -@findex quotation - -The text of a quotation is processed normally (regular font, text is -filled) except that: - -@itemize @bullet -@item -the margins are closer to the center of the page, so the whole of the -quotation is indented; - -@item -and the first lines of paragraphs are indented no more than other lines. - -@end itemize - -@quotation -This is an example of text written between an @code{@@quotation} -command and an @code{@@end quotation} command. An @code{@@quotation} -command is most often used to indicate text that is excerpted from -another (real or hypothetical) printed work. -@end quotation - -Write an @code{@@quotation} command as text on a line by itself. This -line will disappear from the output. Mark the end of the quotation -with a line beginning with and containing only @code{@@end quotation}. -The @code{@@end quotation} line will likewise disappear from the -output. - -@code{@@quotation} takes one optional argument, given on the remainder -of the line. This text, if present, is included at the beginning of -the quotation in bold or otherwise emphasized, and followed with a -@samp{:}. For example: - -@example -@@quotation Note -This is -a foo. -@@end quotation -@end example - -@noindent -produces - -@quotation Note -This is -a foo. -@end quotation - -If the @code{@@quotation} argument is exactly one of these words: - -@example -Caution Important Note Tip Warning -@end example - -@cindex <note> Docbook tag -@cindex <blockquote> HTML tag -@noindent then the Docbook output uses corresponding special tags -(@code{<note>}, etc.) instead of the default @code{<blockquote>}. -HTML output always uses @code{<blockquote>}. - - -@node example -@section @code{@@example}: Example Text -@cindex Examples, formatting them -@cindex Formatting examples -@findex example - -The @code{@@example} environment is used to indicate an example that -is not part of the running text, such as computer input or output. -Write an @code{@@example} command at the beginning of a line by -itself. Mark the end of the example with an @code{@@end example} -command, also written at the beginning of a line by itself. - -An @code{@@example} environment has the following characteristics: - -@itemize -@item Each line in the input file is a line in the output; that is, -the source text is not filled as it normally is. -@item Extra spaces and blank lines are significant. -@item The output is indented. -@item The output uses a fixed-width font. -@item Texinfo commands @emph{are} expanded; if you want the output to -be the input verbatim, use the @code{@@verbatim} environment instead -(@pxref{verbatim,,@code{@@verbatim}}). -@end itemize - -For example, - -@example -@@example -cp foo @@var@{dest1@}; \ - cp foo @@var@{dest2@} -@@end example -@end example - -@noindent -produces - -@example -cp foo @var{dest1}; \ - cp foo @var{dest2} -@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}. Blank lines inside the beginning -@code{@@example} and the ending @code{@@end example}, on the other -hand, do appear in the output. - -@quotation Caution -Do not use tabs in the lines of an example! (Or anywhere else in -Texinfo, except in verbatim environments.) @TeX{} treats tabs as -single spaces, and that is not what they look like. In Emacs, you can -use @kbd{M-x untabify} to convert tabs in a region to multiple spaces. -@end quotation - -Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text that continues afterwards should not be -indented, as in the example above. The @code{@@noindent} command -prevents a piece of text from being indented as if it were a new -paragraph (@pxref{noindent,,@code{@@noindent}}. - -If you want to embed code fragments within sentences, instead of -displaying them, use the @code{@@code} command or its relatives -(@pxref{code,,@code{@@code}}). - -If you wish to write a ``comment'' on a line of an example in the -normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). - - -@node verbatim -@section @code{@@verbatim}: Literal Text -@findex verbatim -@cindex Verbatim environment - -Use the @code{@@verbatim} environment for printing of text that may -contain special characters or commands that should not be interpreted, -such as computer input or output (@code{@@example} interprets its text -as regular Texinfo commands). This is especially useful for including automatically -generated files in a Texinfo manual. - -In general, the output will be just the same as the input. No -character substitutions are made, e.g., all spaces and blank lines are -significant, including tabs. In the printed manual, the text is -typeset in a fixed-width font, and not indented or filled. - -Write a @code{@@verbatim} command at the beginning of a line by itself. -This line will disappear from the output. Mark the end of the verbatim -block with a @code{@@end verbatim} command, also written at the -beginning of a line by itself. The @code{@@end verbatim} will also -disappear from the output. - -For example: -@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim - -@example -@exdent @t{@@verbatim} -@exdent @t{@{} -@exdent @key{TAB}@t{@@command with strange characters: @@'e} -@exdent @t{expand@key{TAB}me} -@exdent @t{@}} -@exdent @t{@@end verbatim} -@end example - -@noindent -This produces: - -@verbatim -{ - @command with strange characters: @'e -expand me -} -@end verbatim - -Since the lines containing @code{@@verbatim} and @code{@@end verbatim} -produce no output, typically you should put a blank line before the -@code{@@verbatim} and another blank line after the @code{@@end -verbatim}. Blank lines between the beginning @code{@@verbatim} and -the ending @code{@@end verbatim} will appear in the output. - -@cindex Verbatim, small -@cindex Small verbatim -You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in -an @code{@@smallformat} environment, as shown here: - -@c more cheating ... -@smallexample -@exdent @t{@@smallformat} -@exdent @t{@@verbatim} -@exdent @t{... still verbatim, but in a smaller font ...} -@exdent @t{@@end verbatim} -@exdent @t{@@end smallformat} -@end smallexample - -Finally, a word of warning: it is not reliable to use -@code{@@verbatim} inside other Texinfo constructs. - - -@node verbatiminclude -@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim -@cindex Verbatim, include file -@cindex Including a file verbatim -@findex verbatiminclude - -You can include the exact contents of a file in the document with the -@code{@@verbatiminclude} command: - -@example -@@verbatiminclude @var{filename} -@end example - -The contents of @var{filename} is printed in a verbatim environment -(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed -exactly as it is, with all special characters and white space -retained. No indentation is added; if you want indentation, enclose -the @code{@@verbatiminclude} within @code{@@example} -(@pxref{example,,@code{@@example}}). - -The name of the file is taken literally, with a single exception: -@code{@@value@{@var{var}@}} references are expanded. This makes it -possible to include files in other directories within a distribution, -for instance: - -@example -@@verbatiminclude @@value@{top_srcdir@}/NEWS -@end example - -@noindent (You still have to get @code{top_srcdir} defined in the -first place.) - -For a method on printing the file contents in a smaller font size, see -the end of the previous section on @code{@@verbatim}. - - -@node lisp -@section @code{@@lisp}: Marking a Lisp Example -@findex lisp -@cindex Lisp example - -The @code{@@lisp} command is used for Lisp code. It is synonymous -with the @code{@@example} command. - -@lisp -This is an example of text written between an -@code{@@lisp} command and an @code{@@end lisp} command. -@end lisp - -Use @code{@@lisp} instead of @code{@@example} to preserve information -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.} - -Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by -itself. - - -@node small -@section @code{@@small@dots{}} Block Commands -@cindex Small examples -@cindex Examples in smaller fonts -@cindex Lisp examples in smaller fonts -@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}. - -In Info, the @code{@@small@dots{}} commands are equivalent to their -non-small companion commands. - -In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in -a smaller font than the non-small example commands. Consequently, -many examples containing long lines fit on a page without needing to -be shortened. - -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}. - -Here is an example of the font used by the @code{@@small@dots{}} -commands (in Info, the output will be the same as usual): - -@smallexample -@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 smallexample - -The @code{@@small@dots{}} commands make it easier to prepare manuals -without forcing you to edit examples by hand to fit them onto narrower -pages. - -As a general rule, a printed document looks much better if you use -only one of (for instance) @code{@@example} or @code{@@smallexample} -consistently within a chapter. - - -@node display -@section @code{@@display} and @code{@@smalldisplay} -@cindex Display formatting -@findex display - -The @code{@@display} command begins a kind of example, where each line -of input produces a line of output, and the output is indented. It is -thus like the @code{@@example} command except that, in a printed -manual, @code{@@display} does not select the fixed-width font. In -fact, it does not specify the font at all, so that the text appears in -the same font it would have appeared in without the @code{@@display} -command. - -@display -This is an example of text written between an @code{@@display} command -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}. - -The @code{@@table} command (@pxref{table}) does not work inside -@code{@@display}. Since @code{@@display} is line-oriented, it doesn't -make sense to use them together. If you want to indent a table, try -@code{@@quotation} (@pxref{quotation}). - - -@node format -@section @code{@@format} and @code{@@smallformat} -@findex format - -The @code{@@format} command is similar to @code{@@example} except -that, in the printed manual, @code{@@format} does not select the -fixed-width font and does not narrow the margins.@refill - -@format -This is an example of text written between an @code{@@format} command -and an @code{@@end format} command. As you can see -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 -@section @code{@@exdent}: Undoing a Line's Indentation -@cindex Indentation undoing -@findex exdent - -The @code{@@exdent} command removes any indentation a line might have. -The command is written at the beginning of a line and applies only to -the text that follows the command that is on the same line. Do not use -braces around the text. In a printed manual, the text on an -@code{@@exdent} line is printed in the roman font.@refill - -@code{@@exdent} is usually used within examples. Thus,@refill - -@example -@group -@@example -This line follows an @@@@example command. -@@exdent This line is exdented. -This line follows the exdented line. -The @@@@end example comes on the next line. -@@end example -@end group -@end example - -@noindent -produces - -@example -@group -This line follows an @@example command. -@exdent This line is exdented. -This line follows the exdented line. -The @@end example comes on the next line. -@end group -@end example - -In practice, the @code{@@exdent} command is rarely used. -Usually, you un-indent text by ending the example and -returning the page to its normal width.@refill - - -@node flushleft & flushright -@section @code{@@flushleft} and @code{@@flushright} -@findex flushleft -@findex flushright -@cindex Ragged right -@cindex Ragged left - -The @code{@@flushleft} and @code{@@flushright} commands line up the -ends of lines on the left and right margins of a page, -but do not fill the text. The commands are written on lines of their -own, without braces. The @code{@@flushleft} and @code{@@flushright} -commands are ended by @code{@@end flushleft} and @code{@@end -flushright} commands on lines of their own.@refill - -@need 1500 -For example, - -@example -@group -@@flushleft -This text is -written flushleft. -@@end flushleft -@end group -@end example - -@noindent -produces - -@quotation -@flushleft -This text is -written flushleft. -@end flushleft -@end quotation - - -@code{@@flushright} produces the type of indentation often used in the -return address of letters. For example, - -@example -@group -@@flushright -Here is an example of text written -flushright. The @@code@{@@flushright@} command -right justifies every line but leaves the -left end ragged. -@@end flushright -@end group -@end example - -@noindent -produces - -@flushright -Here is an example of text written -flushright. The @code{@@flushright} command -right justifies every line but leaves the -left end ragged. -@end flushright - - -@node noindent -@section @code{@@noindent}: Omitting Indentation -@cindex Omitting indentation -@cindex Suppressing indentation -@cindex Indentation, omitting -@findex noindent - -An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. You can prevent this on a case-by-case basis by writing -@code{@@noindent} at the beginning of a line, preceding the continuation -text. You can also disable indentation for all paragraphs globally with -@code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}). - -It is best to write @code{@@noindent} on a line by itself, since in most -environments, spaces following the command will not be ignored. It's ok -to use it at the beginning of a line, with text following, outside of -any environment. - -@need 1500 -For example: - -@example -@group -@@example -This is an example -@@end example - -@@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@@code@{@@@@display@} and @@code@{@@@@end display@}.) -@end group -@end example - -@noindent produces: - -@display - -@example -This is an example -@end example - -@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@code{@@display} and @code{@@end display}.) - -@end display - -To adjust the number of blank lines properly in the Info file output, -remember that the line containing @code{@@noindent} does not generate a -blank line, and neither does the @code{@@end example} line. - -In the Texinfo source file for this manual, each line that says -`produces' is preceded by @code{@@noindent}. - -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}). - - -@node indent -@section @code{@@indent}: Forcing Indentation -@cindex Forcing indentation -@cindex Inserting indentation -@cindex Indentation, forcing -@findex indent - -@indent -To complement the @code{@@noindent} command (see the previous -section), Texinfo provides the @code{@@indent} command that forces a -paragraph to be indented. This paragraph, for instance, is indented -using an @code{@@indent} command. The first paragraph of a section is -the most likely place to use @code{@@indent}, to override the normal -behavior of no indentation there (@pxref{paragraphindent}). - -It is best to write @code{@@indent} on a line by itself, since in most -environments, spaces following the command will not be ignored. The -@code{@@indent} line will not generate a blank line in the Info output -within an environment. - -However, it is ok to use it at the beginning of a line, with text -following, outside of any environment. - -Do not put braces after an @code{@@indent} command; they are not -necessary, since @code{@@indent} is a command used outside of -paragraphs (@pxref{Command Syntax}). - - -@node cartouche -@section @code{@@cartouche}: Rounded Rectangles Around Examples -@findex cartouche -@cindex Box with rounded corners -@cindex Rounded rectangles, around examples - -In a printed manual, the @code{@@cartouche} command draws a box with -rounded corners around its contents. In HTML, a normal rectangle is -drawn (that's the best HTML can do). @code{@@cartouche} has no effect -in Info output. - -You can use this command to 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. - -For example, - -@example -@@cartouche -@@example -% pwd -/usr/local/share/emacs -@@end example -@@end cartouche -@end example - -@noindent -surrounds the two-line example with a box with rounded corners, in the -printed manual. - -The output from the example looks like this (if you're reading this in -Info, you'll see the @code{@@cartouche} had no effect): - -@cartouche -@example -% pwd -/usr/local/info -@end example -@end cartouche - -For proper output in HTML, it's necessary to put the -@code{@@cartouche} around the @code{@@example}, and not the other way -around. This limitation of @command{makeinfo} may be removed one day. - -@code{@@cartouche} also implies @code{@@group} (@pxref{group}). - -@node Lists and Tables -@chapter Lists and Tables -@cindex Making lists and tables -@cindex Lists and tables, making -@cindex Tables and lists, making - -Texinfo has several ways of making lists and tables. Lists can be -bulleted or numbered; two-column tables can highlight the items in -the first column; multi-column tables are also supported. - -@menu -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* enumerate:: How to construct a numbered list. -* Two-column Tables:: How to construct a two-column table. -* Multi-column Tables:: How to construct generalized tables. -@end menu - -@node Introducing Lists -@section Introducing Lists - -Texinfo automatically indents the text in lists or tables, and numbers -an enumerated list. This last feature is useful if you modify the -list, since you do not need to renumber it yourself.@refill - -Numbered lists and tables begin with the appropriate @@-command at the -beginning of a line, and end with the corresponding @code{@@end} -command on a line by itself. The table and itemized-list commands -also require that you write formatting information on the same line as -the beginning @@-command.@refill - -Begin an enumerated list, for example, with an @code{@@enumerate} -command and end the list with an @code{@@end enumerate} command. -Begin an itemized list with an @code{@@itemize} command, followed on -the same line by a formatting command such as @code{@@bullet}, and end -the list with an @code{@@end itemize} command.@refill -@findex end - -Precede each element of a list with an @code{@@item} or @code{@@itemx} -command.@refill - -@sp 1 -@noindent -Here is an itemized list of the different kinds of table and lists:@refill - -@itemize @bullet -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end itemize - -@sp 1 -@noindent -Here is an enumerated list with the same items:@refill - -@enumerate -@item -Itemized lists with and without bullets. - -@item -Enumerated lists, using numbers or letters. - -@item -Two-column tables with highlighting. -@end enumerate - -@sp 1 -@noindent -And here is a two-column table with the same items and their -@w{@@-commands}:@refill - -@table @code -@item @@itemize -Itemized lists with and without bullets. - -@item @@enumerate -Enumerated lists, using numbers or letters. - -@item @@table -@itemx @@ftable -@itemx @@vtable -Two-column tables, optionally with indexing. -@end table - - -@node itemize -@section @code{@@itemize}: Making an Itemized List -@cindex Itemization -@findex itemize - -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}. - -Write the text of the indented paragraphs themselves after the -@code{@@itemize}, up to another line that says @code{@@end -itemize}.@refill - -@findex item -At the beginning of each paragraph for which a mark in the margin is -desired, write a line that starts with @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 -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{}. - -@example -@group -@@itemize @@bullet -@@item -Some text for foo. - -@@item -Some text -for bar. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -Some text for foo. - -@item -Some text -for bar. -@end itemize -@end quotation - -Itemized lists may be embedded within other itemized lists. Here is a -list marked with dashes embedded in a list marked with bullets:@refill - -@example -@group -@@itemize @@bullet -@@item -First item. - -@@itemize @@minus -@@item -Inner item. - -@@item -Second inner item. -@@end itemize - -@@item -Second outer item. -@@end itemize -@end group -@end example - -@noindent -This produces: - -@quotation -@itemize @bullet -@item -First item. - -@itemize @minus -@item -Inner item. - -@item -Second inner item. -@end itemize - -@item -Second outer item. -@end itemize -@end quotation - - -@node enumerate -@section @code{@@enumerate}: Making a Numbered or Lettered List -@cindex Enumeration -@findex enumerate - -@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,, -@code{@@itemize}}), except that the labels on the items are -successive integers or letters instead of bullets. - -Write the @code{@@enumerate} command at the beginning of a line. The -command does not require an argument, but accepts either a number or a -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. - -Write the text of the enumerated list in the same way as an itemized -list: write a line starting with @code{@@item} at the beginning of -each paragraph that you want enumerated. It is ok to have text -following the @code{@@item}. - -You should put a blank line between entries in the list. -This generally makes it easier to read the Info file. - -@need 1500 -Here is an example of @code{@@enumerate} without an argument: - -@example -@group -@@enumerate -@@item -Underlying causes. - -@@item -Proximate causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate -@item -Underlying causes. - -@item -Proximate causes. -@end enumerate -@sp 1 -Here is an example with an argument of @kbd{3}:@refill -@sp 1 -@example -@group -@@enumerate 3 -@@item -Predisposing causes. - -@@item -Precipitating causes. - -@@item -Perpetuating causes. -@@end enumerate -@end group -@end example - -@noindent -This produces: - -@enumerate 3 -@item -Predisposing causes. - -@item -Precipitating causes. - -@item -Perpetuating causes. -@end enumerate -@sp 1 -Here is a brief summary of the alternatives. The summary is constructed -using @code{@@enumerate} with an argument of @kbd{a}.@refill -@sp 1 -@enumerate a -@item -@code{@@enumerate} - -Without an argument, produce a numbered list, starting with the number -1.@refill - -@item -@code{@@enumerate @var{positive-integer}} - -With a (positive) numeric argument, start a numbered list with that -number. You can use this to continue a list that you interrupted with -other text.@refill - -@item -@code{@@enumerate @var{upper-case-letter}} - -With an upper case letter as argument, start a list -in which each item is marked -by a letter, beginning with that upper case letter.@refill - -@item -@code{@@enumerate @var{lower-case-letter}} - -With a lower case letter as argument, start a list -in which each item is marked by -a letter, beginning with that lower case letter.@refill -@end enumerate - -You can also nest enumerated lists, as in an outline.@refill - -@node Two-column Tables -@section Making a Two-column Table -@cindex Tables, making two-column -@findex table - -@code{@@table} is similar to @code{@@itemize} (@pxref{itemize,, -@code{@@itemize}}), but allows you to specify a name or heading line for -each item. The @code{@@table} command is used to produce two-column -tables, and is especially useful for glossaries, explanatory -exhibits, and command-line option summaries. - -@menu -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. -@end menu - -@node table -@subsection Using the @code{@@table} Command - -@cindex Definition lists, typesetting -Use the @code{@@table} command to produce two-column tables. It is -usually listed for ``definition lists'' of various sorts, where you -have a list of terms and a brief text with each one. - -Write the @code{@@table} command at the beginning of a line, after a -blank line, and follow it on the same line with an argument that is a -Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp}, -@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}). - -This command will be applied to the text that goes into the first -column of each item and thus determines how it will be highlighted. -For example, @code{@@table @@code} will cause the text in the first -column to be output as if it @code{@@code} command. - -@findex asis -You may also use the @code{@@asis} command as an argument to -@code{@@table}. @code{@@asis} is a command that does nothing; if you -use this command after @code{@@table}, the first column entries are -output without added highlighting (``as is''). - -The @code{@@table} command works with other commands besides those -explicitly mentioned here. However, you can only use commands that -normally take arguments in braces. (In this case, however, you use -the command name without an argument, because the subsequent -@code{@@item}'s will supply the argument.) - -@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 -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 the text on the same line as the @code{@@item} -will be placed in the first column (including any footnotes). - -Normally, you should put a blank line before an @code{@@item} line. -This puts a blank line in the Info file. Except when the entries are -very brief, a blank line looks better. - -End the table with a line consisting of @code{@@end table}, followed -by a blank line. @TeX{} will always start a new paragraph after the -table, so the blank line is needed for the Info output to be analogous. - -@need 1500 -The following table, for example, highlights the text in the first -column with an @code{@@samp} command: - -@example -@group -@@table @@samp -@@item foo -This is the text for -@@samp@{foo@}. - -@@item bar -Text for @@samp@{bar@}. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @samp -@item foo -This is the text for -@samp{foo}. -@item bar -Text for @samp{bar}. -@end table - -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}}.) - - -@node ftable vtable -@subsection @code{@@ftable} and @code{@@vtable} -@cindex Tables with indexes -@cindex Indexing table entries automatically -@findex ftable -@findex vtable - -The @code{@@ftable} and @code{@@vtable} commands are the same as the -@code{@@table} command except that @code{@@ftable} automatically enters -each of the items in the first column of the table into the index of -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 - -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 -line by an argument that is a Texinfo command such as @code{@@code}, -exactly as you would for an @code{@@table} command; and end the table -with an @code{@@end ftable} or @code{@@end vtable} command on a line by -itself. - -See the example for @code{@@table} in the previous section. - -@node itemx -@subsection @code{@@itemx} -@cindex Two named items for @code{@@table} -@findex itemx - -Use the @code{@@itemx} command inside a table when you have two or more -first column entries for the same item, each of which should appear on a -line of its own. - -Use @code{@@item} for the first entry, and @code{@@itemx} for all -subsequent entries; @code{@@itemx} must always follow an @code{@@item} -command, with no blank line intervening. - -The @code{@@itemx} command works exactly like @code{@@item} except -that it does not generate extra vertical space above the first column -text. If you have multiple consecutive @code{@@itemx} commands, do -not insert any blank lines between them. - -For example, - -@example -@group -@@table @@code -@@item upcase -@@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding upper case (lower -case) character or string. -@@end table -@end group -@end example - -@noindent -This produces: - -@table @code -@item upcase -@itemx downcase -These two functions accept a character or a string as -argument, and return the corresponding upper case (lower -case) character or string.@refill -@end table - -@noindent -(Note also that this example illustrates multi-line supporting text in -a two-column table.)@refill - - -@node Multi-column Tables -@section @code{@@multitable}: Multi-column Tables -@cindex Tables, making multi-column -@findex multitable - -@code{@@multitable} allows you to construct tables with any number of -columns, with each column having any width you like. - -You define the column widths on the @code{@@multitable} line itself, and -write each row of the actual table following an @code{@@item} command, -with columns separated by an @code{@@tab} command. Finally, @code{@@end -multitable} completes the table. Details in the sections below. - -@menu -* Multitable Column Widths:: Defining multitable column widths. -* Multitable Rows:: Defining multitable rows, with examples. -@end menu - -@node Multitable Column Widths -@subsection Multitable Column Widths -@cindex Multitable column widths -@cindex Column widths, defining for multitables -@cindex Widths, defining multitable column - -You can define the column widths for a multitable in two ways: as -fractions of the line length; or with a prototype row. Mixing the two -methods is not supported. In either case, the widths are defined -entirely on the same line as the @code{@@multitable} command. - -@enumerate -@item -@findex columnfractions -@cindex Line length, column widths as fraction of -To specify column widths as fractions of the line length, write -@code{@@columnfractions} and the decimal numbers (presumably less than -1; a leading zero is allowed and ignored) after the -@code{@@multitable} command, as in: - -@example -@@multitable @@columnfractions .33 .33 .33 -@end example - -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. - -@item -@cindex Prototype row, column widths defined by -To specify a prototype row, write the longest entry for each column -enclosed in braces after the @code{@@multitable} command. For example: - -@example -@@multitable @{some text for column one@} @{for column two@} -@end example - -@noindent -The first column will then have the width of the typeset `some text for -column one', and the second column the width of `for column two'. - -The prototype entries need not appear in the table itself. - -Although we used simple text in this example, the prototype entries can -contain Texinfo commands; markup commands such as @code{@@code} are -particularly likely to be useful. - -@end enumerate - - -@node Multitable Rows -@subsection Multitable Rows -@cindex Multitable rows -@cindex Rows, of a multitable - -@findex item -@findex 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}. -Line breaks are not special within the table body, and you may break -input lines in your source file as necessary. - -@findex headitem -@cindex Heading row, in table -@cindex <thead> HTML tag -You can also use @code{@@headitem} instead of @code{@@item} to produce -a @dfn{heading row}. The @TeX{} output for such a row is in bold, and -the HTML, XML, and Docbook output uses the @code{<thead>} tag. In -Info, the heading row is followed by a separator line made of dashes -(@samp{-} characters). - -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}): - -@example -@@multitable @@columnfractions .15 .45 .4 -@@headitem Key @@tab Command @@tab Description -@@item C-x 2 -@@tab @@code@{split-window-vertically@} -@@tab Split the selected window into two windows, -with one above the other. -@@item C-x 3 -@@tab @@code@{split-window-horizontally@} -@@tab Split the selected window into two windows -positioned side by side. -@@item C-Mouse-2 -@@tab -@@tab In the mode line or scroll bar of a window, -split that window. -@@end multitable -@end example - -@noindent produces: - -@multitable @columnfractions .15 .45 .4 -@headitem Key @tab Command @tab Description -@item C-x 2 -@tab @code{split-window-vertically} -@tab Split the selected window into two windows, -with one above the other. -@item C-x 3 -@tab @code{split-window-horizontally} -@tab Split the selected window into two windows -positioned side by side. -@item C-Mouse-2 -@tab -@tab In the mode line or scroll bar of a window, -split that window. -@end multitable - - -@node Special Displays -@chapter Special Displays -@cindex Special displays - -The commands in this chapter allow you to write text that is specially -displayed (output format permitting), outside of the normal document -flow. - -One set of such commands is for creating ``floats'', that is, figures, -tables, and the like, set off from the main text, possibly numbered, -captioned, and/or referred to from elsewhere in the document. Images -are often included in these displays. - -Another group of commands is for creating footnotes in Texinfo. - -@menu -* Floats:: Figures, tables, and the like. -* Images:: Including graphics and images. -* Footnotes:: Writing footnotes. -@end menu - - -@node Floats -@section Floats -@cindex Floats, in general - -A @dfn{float} is a display which is set off from the main text. It is -typically labelled as being a ``Figure'', ``Table'', ``Example'', or -some similar type. - -@cindex Floating, not yet implemented -A float is so-named because, in principle, it can be moved to the -bottom or top of the current page, or to a following page, in the -printed output. (Floating does not make sense in other output -formats.) In the present version of Texinfo, however, this floating -is unfortunately not yet implemented. Instead, the floating material -is simply output at the current location, more or less as if it were -an @code{@@group} (@pxref{group,,@code{@@group}}). - -@menu -* float:: Producing floating material. -* caption shortcaption:: Specifying descriptions for floats. -* listoffloats:: A table of contents for floats. -@end menu - - -@node float -@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material -@findex float -@cindex Float environment - -To produce floating material, enclose the material you want to be -displayed separate between @code{@@float} and @code{@@end float} -commands, on lines by themselves. - -Floating material uses @code{@@image} to display an already-existing -graphic (@pxref{Images}), or @code{@@multitable} to display a table -(@pxref{Multi-column Tables}). However, the contents of the float can -be anything. Here's an example with simple text: - -@example -@@float Figure,fig:ex1 -This is an example float. -@@end float -@end example - -@noindent And the output: - -@float Figure,fig:ex1 -This is an example float. -@end float - -As shown in the example, @code{@@float} takes two arguments (separated -by a comma), @var{type} and @var{label}. Both are optional. - -@table @var -@item type -Specifies the sort of float this is; typically a word such as -``Figure'', ``Table'', etc. If not given, and @var{label} is, any -cross-referencing will simply use a bare number. - -@item label -Specifies a cross-reference label for this float. If given, this -float is automatically given a number, and will appear in any -@code{@@listoffloats} output (@pxref{listoffloats}). Cross-references -to @var{label} are allowed. - -@cindex Floats, making unnumbered -@cindex Unnumbered float, creating -On the other hand, if @var{label} is not given, then the float will -not be numbered and consequently will not appear in the -@code{@@listoffloats} output or be cross-referenceable. -@end table - -@noindent Normally, you specify both @var{type} and @var{label}, to get a -labeled and numbered float. - -@cindex Floats, numbering of -@cindex Numbering of floats -In Texinfo, all floats are numbered the same way: with the chapter -number (or appendix letter), a period, and the float number, which -simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each -float type is counted independently. - -Floats within an @code{@@unnumbered} are numbered, or outside of any -chapter, are simply numbered consecutively from 1. - -These numbering conventions are not, at present, changeable. - - -@node caption shortcaption -@subsection @code{@@caption} & @code{@@shortcaption} -@findex caption -@findex shortcaption -@cindex Captions, for floats -@cindex Short captions, for lists of floats - -You may write an @code{@@caption} anywhere within a @code{@@float} -environment, to define a caption for the float. It is not allowed in -any other context. @code{@@caption} takes a single argument, enclosed -in braces. Here's an example: - -@example -@@float -An example float, with caption. -@@caption@{Caption for example float.@} -@@end float -@end example - -@noindent The output is: - -@float -An example float, with caption. -@caption{Caption for example float.} -@end float - -@code{@@caption} can appear anywhere within the float; it is not -processed until the @code{@@end float}. The caption text is usually a -sentence or two, but may consist of several paragraphs if necessary. - -In the output, the caption always appears below the float; this is not -currently changeable. It is preceded by the float type and/or number, -as specified to the @code{@@float} command (see the previous section). - -The @code{@@shortcaption} command likewise may be used only within -@code{@@float}, and takes a single argument in braces. The short -caption text is used instead of the caption text in a list of floats -(see the next section). Thus, you can write a long caption for the -main document, and a short title to appear in the list of floats. For -example: - -@example -@@float -... as above ... -@@shortcaption@{Text for list of floats.@} -@@end float -@end example - -The text for @code{@@caption} and @code{@@shortcaption} may not -contain comments (@code{@@c}), verbatim text (@code{@@verb}), -environments such as @code{@@example}, or other complex constructs. - - -@node listoffloats -@subsection @code{@@listoffloats}: Tables of Contents for Floats -@findex listoffloats -@cindex List of floats -@cindex Floats, list of -@cindex Table of contents, for floats - -You can write a @code{@@listoffloats} command to generate a list of -floats for a given float type (@pxref{float}), analogous to the -document's overall table of contents. Typically, it is written in its -own @code{@@unnumbered} node to provide a heading and structure, -rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). - -@code{@@listoffloats} takes one optional argument, the float type. -Here's an example: - -@example -@@node List of Figures -@@unnumbered List of Figures -@@listoffloats Figure -@end example - -@noindent And the output from @code{@@listoffloats}: - -@display -@listoffloats Figure -@end display - -Without any argument, @code{@@listoffloats} generates a list of -floats for which no float type was specified, i.e., no first argument -to the @code{@@float} command (@pxref{float}). - -Each line in the list of floats contains the float type (if any), -the float number, and the caption, if any---the @code{@@shortcaption} -argument, if it was specified, else the @code{@@caption} argument. -In Info, the result is a menu where each float can be selected. In -HTML, each line is a link to the float. In printed output, the page -number is included. - -Unnumbered floats (those without cross-reference labels) are omitted -from the list of floats. - - -@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. Although images can be used anywhere, -including the middle of a paragraph, we describe them in this chapter -since they are most often part of a displayed figure or example. - -@menu -* Image Syntax:: -* Image Scaling:: -@end menu - - -@node Image Syntax -@subsection Image Syntax - -Here is the synopsis of the @code{@@image} command: - -@example -@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@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 -@pindex eps image format -@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript -format). -@item -@pindex pdftex@r{, and images} -@pindex png image format -@pindex jpeg image format -@pindex pdf image inclusions -pdf@TeX{} reads @file{@var{filename}.png}, @file{@var{filename}.jpg}, -@file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that -order). It also tries uppercase versions of the extensions. The PDF -format cannot support EPS images, so they must be converted first. -@item -@code{makeinfo} includes @file{@var{filename}.txt} verbatim for -Info output (more or less as if it was an @code{@@example}). -@item -@code{makeinfo} uses the optional fifth argument @var{extension} to -@code{@@image} for the filename extension, if it is specified. For example: - -@pindex XPM image format -@example -@@image@{foo,,,,.xpm@} -@end example - -@noindent -will cause @code{makeinfo} to look for @file{foo.xpm} before any others. - -@end itemize - -The @var{width} and @var{height} arguments are described in the next -section. - -For @TeX{} output, if an image is the only thing in a paragraph it -will ordinarily be displayed on a line by itself, respecting the -current environment indentation, but without the normal paragraph -indentation. If you want it centered, use @code{@@center} -(@pxref{titlefont center sp,,@code{@@titlefont @@center @@sp}}). - -@cindex Alt attribute for images -@cindex Images, alternate text for -@findex - (in image alt string) -For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for -inline images to the optional @var{alttext} (fourth) argument to -@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses -the full file name of the image being displayed. The @var{alttext} is -taken as Texinfo text, so special characters such as @samp{"} and -@samp{<} and @samp{&} are escaped in the HTML and XML output; also, -you can get an empty @code{alt} string with @code{@@-} (a command -that produces no output; @pxref{- and hyphenation}). - -For Info output, the @code{alt} string is also processed as Texinfo -text and output. In this case, @samp{\} is escaped as @samp{\\} and -@samp{"} as @samp{\"}; no other escapes are done. - -@cindex PNG image format -@cindex JPEG image format -If you do not supply the optional @var{extension} (fifth) argument, -@code{makeinfo} first tries @file{@var{filename}.png}; if that does -not exist, it tries @file{@var{filename}.jpg}. If that does not exist -either, it complains. - -In Info output, @code{makeinfo} writes a reference to the binary image -file (trying @var{filename} suffixed with @file{@var{extension}}, -@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) -if one exists. It also literally includes the @file{.txt} file if one -exists. This way, Info readers which can display images (such as the -Emacs Info browser, running under X) can do so, whereas Info readers -which can only use text (such as the standalone Info reader) can -display the textual version. - -@cindex @samp{^@@^H} for images in Info -The implementation of this is to put the following construct into the -Info output: - -@example -^@@^H[image src="@var{binaryfile}" text="@var{txtfile}" - alt="@var{alttext} ... ^@@^H] -@end example - -@noindent where @samp{^@@} and @samp{^H} stand for the actual null and -backspace control characters. If one of the files is not present, the -corresponding argument is omitted. - -The reason for mentioning this here is that older Info browsers (this -feature was introduced in Texinfo version 4.6) will display the above -literally, which, although not pretty, should not be harmful. - - -@node Image Scaling -@subsection Image Scaling - -@cindex Images, scaling -@cindex Scaling images -@cindex Width of images -@cindex Height of images -@cindex Aspect ratio of images -@cindex Distorting images -The optional @var{width} and @var{height} arguments to the -@code{@@image} command (see the previous section) 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 also available from -@uref{ftp://tug.org/tex/epsf.tex}, among other places. - -@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. - -Image scaling is presently implemented only in @TeX{}, not in HTML or -any other sort of output. - - -@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.} Footnotes are distracting; use them -sparingly, if at all. Standard bibliographical references are better -placed in a bibliography at the end of a document than in footnotes -throughout. - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu - - -@node Footnote Commands -@subsection 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 - -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. - -For example, this clause is followed by a sample footnote@footnote{Here -is the sample footnote.}; in the Texinfo source, it looks like -this: - -@example -@dots{}a sample footnote@@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -As you can see, the source includes two punctuation marks next to each -other; in this case, @samp{.@};} is the sequence. This is normal (the -first ends the footnote and the second belongs to the sentence being -footnoted), so don't worry that it looks odd. - -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. - -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. - -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}. - - -@node Footnote Styles -@subsection Footnote Styles - -Info has two footnote styles, which determine where the text of the -footnote is located: - -@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. - -@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. - -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. - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style: - -@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 - -Unless your document has long and important footnotes (as in, say, -Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end} -style, as it is simpler for readers to follow. - -@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. - - -@node Indices -@chapter Indices -@cindex Indices - -Using Texinfo, you can generate indices without having to sort and -collate entries manually. In an index, the entries are listed in -alphabetical order, together with information on how to find the -discussion of each entry. In a printed manual, this information -consists of page numbers. In an Info file, this information is a menu -entry leading to the first node referenced. - -Texinfo provides several predefined kinds of index: an index -for functions, an index for variables, an index for concepts, and so -on. You can combine indices or use them for other than their -canonical purpose. Lastly, you can define your own new indices. - -@xref{Printing Indices & Menus}, for information on how to print -indices. - -@menu -* Index Entries:: Choose different words for index entries. -* Predefined Indices:: Use different indices for different kinds - of entries. -* Indexing Commands:: How to make an index entry. -* Combining Indices:: How to combine indices. -* New Indices:: How to define your own indices. -@end menu - - -@node Index Entries -@section Making Index Entries -@cindex Index entries, making -@cindex Entries, making index - -When you are making index entries, it is good practice to think of the -different ways people may look for something. Different people -@emph{do not} think of the same words when they look something up. A -helpful index will have items indexed under all the different words -that people may use. For example, one reader may think it obvious that -the two-letter names for indices should be listed under ``Indices, -two-letter names'', since the word ``Index'' is the general concept. -But another reader may remember the specific concept of two-letter -names and search for the entry listed as ``Two letter names for -indices''. A good index will have both entries and will help both -readers.@refill - -Like typesetting, the construction of an index is a highly skilled, -professional art, the subtleties of which are not appreciated until you -need to do it yourself.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - - -@node Predefined Indices -@section Predefined Indices - -Texinfo provides six predefined indices. Here are their nominal -meanings, abbreviations, and the corresponding index entry commands: - -@table @samp -@item cp -@cindex @code{cp} (concept) index -(@code{@@cindex}) concept index, for general concepts. -@item fn -@cindex @code{fn} (function) index -(@code{@@findex}) function index, for function and function-like -names (such as entry points of libraries). -@item ky -@cindex @code{ky} (keystroke) index -(@code{@@kindex}) keystroke index, for keyboard commands. -@item pg -@cindex @code{pg} (program) index -(@code{@@pindex}) program index, for names of programs. -@item tp -@cindex @code{tp} (data type) index -(@code{@@tindex}) data type index, for type names (such as structures -defined in header files). -@item vr -@cindex @code{vr} (variable) index -(@code{@@vindex}) variable index, for variable names (such as global -variables of libraries). -@end table - -@noindent -Not every manual needs all of these, and most manuals use only two or -three at most. The present manual, for example, has two indices: a -concept index and an @@-command index (that is actually the function -index but is called a command index in the chapter heading). - -You are not required to use the predefined indices strictly for their -canonical purposes. For example, suppose you wish to index some C -preprocessor macros. You could put them in the function index along -with actual functions, just by writing @code{@@findex} commands for -them; then, when you print the ``Function Index'' as an unnumbered -chapter, you could give it the title `Function and Macro Index' and -all will be consistent for the reader. - -On the other hand, it is best not to stray too far from the meaning of -the predefined indices. Otherwise, in the event that your text is -combined with other text from other manuals, the index entries will -not match up. Instead, define your own new index (@pxref{New -Indices}). - -We recommend having a single index in the final document whenever -possible, however many source indices you use, since then readers have -only one place to look. Two or more source indices can be combined -into one output index using the @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Combining Indices}). - - -@node Indexing Commands -@section Defining the Entries of an Index -@cindex Defining indexing entries -@cindex Index entries -@cindex Entries for an index -@cindex Specifying index entries -@cindex Creating index entries - -The data to make an index come from many individual indexing commands -scattered throughout the Texinfo source file. Each command says to add -one entry to a particular index; after formatting, the index will give -the current page number or node name as the reference.@refill - -An index entry consists of an indexing command at the beginning of a -line followed, on the rest of the line, by the entry.@refill - -For example, this section begins with the following five entries for -the concept index:@refill - -@example -@@cindex Defining indexing entries -@@cindex Index entries, defining -@@cindex Entries for an index -@@cindex Specifying index entries -@@cindex Creating index entries -@end example - -Each predefined index has its own indexing command---@code{@@cindex} -for the concept index, @code{@@findex} for the function index, and so -on, as listed in the previous section. - -@cindex Writing index entries -@cindex Index entry writing -Concept index entries consist of text. The best way to write an index -is to choose entries that are terse yet clear. If you can do this, -the index often looks better if the entries are not capitalized, but -written just as they would appear in the middle of a sentence. -(Capitalize proper names and acronyms that always call for upper case -letters.) This is the case convention we use in most GNU manuals' -indices. - -If you don't see how to make an entry terse yet clear, make it longer -and clear---not terse and confusing. If many of the entries are several -words long, the index may look better if you use a different convention: -to capitalize the first word of each entry. But do not capitalize a -case-sensitive name such as a C or Lisp function name or a shell -command; that would be a spelling error. - -Whichever case convention you use, please use it consistently! - -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. - -@cindex Index font types -By default, entries for a concept index are printed in a small roman -font and entries for the other indices are printed in a small -@code{@@code} font. You may change the way part of an entry is -printed with the usual Texinfo commands, such as @code{@@file} for -file names (@pxref{Marking Text}), and @code{@@r} for the normal roman -font (@pxref{Fonts}). - -@quotation 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}, for more information about the -structure of a menu entry. -@end quotation - - -@node Combining Indices -@section Combining Indices -@cindex Combining indices -@cindex Indices, combining them - -Sometimes you will want to combine two disparate indices such as -functions and concepts, perhaps because you have few enough entries -that a separate index would look silly. - -You could put functions into the concept index by writing -@code{@@cindex} commands for them instead of @code{@@findex} commands, -and produce a consistent manual by printing the concept index with the -title `Function and Concept Index' and not printing the `Function -Index' at all; but this is not a robust procedure. It works only if -your document is never included as part of another document that is -designed to have a separate function index; if your document were to -be included with such a document, the functions from your document and -those from the other would not end up together. Also, to make your -function names appear in the right font in the concept index, you -would need to enclose every one of them between the braces of -@code{@@code}. - -@menu -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. -@end menu - -@node syncodeindex -@subsection @code{@@syncodeindex} -@findex syncodeindex - -When you want to combine functions and concepts into one index, you -should index the functions with @code{@@findex} and index the concepts -with @code{@@cindex}, and use the @code{@@syncodeindex} command to -redirect the function index entries into the concept index.@refill - -The @code{@@syncodeindex} command takes two arguments; they are the name -of the index to redirect, and the name of the index to redirect it to. -The template looks like this:@refill - -@example -@@syncodeindex @var{from} @var{to} -@end example - -@cindex Predefined names for indices -@cindex Two letter names for indices -@cindex Indices, two letter names -@cindex Names for indices -For this purpose, the indices are given two-letter names:@refill - -@table @samp -@item cp -concept index -@item fn -function index -@item vr -variable index -@item ky -key index -@item pg -program index -@item tp -data type index -@end table - -Write an @code{@@syncodeindex} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. For example, -to merge a function index with a concept index, write the -following:@refill - -@example -@@syncodeindex fn cp -@end example - -@noindent -This will cause all entries designated for the function index to merge -in with the concept index instead.@refill - -To merge both a variables index and a function index into a concept -index, write the following:@refill - -@example -@group -@@syncodeindex vr cp -@@syncodeindex fn cp -@end group -@end example - -@cindex Fonts for indices -The @code{@@syncodeindex} command puts all the entries from the `from' -index (the redirected index) into the @code{@@code} font, overriding -whatever default font is used by the index to which the entries are -now directed. This way, if you direct function names from a function -index into a concept index, all the function names are printed in the -@code{@@code} font as you would expect.@refill - -@node synindex -@subsection @code{@@synindex} -@findex synindex - -The @code{@@synindex} command is nearly the same as the -@code{@@syncodeindex} command, except that it does not put the -`from' index entries into the @code{@@code} font; rather it puts -them in the roman font. Thus, you use @code{@@synindex} when you -merge a concept index into a function index.@refill - -@xref{Printing Indices & Menus}, for information about printing an index -at the end of a book or creating an index menu in an Info file.@refill - - -@node New Indices -@section Defining New Indices -@cindex Defining new indices -@cindex Indices, defining new -@cindex New index defining -@findex defindex -@findex defcodeindex - -In addition to the predefined indices, you may use the -@code{@@defindex} and @code{@@defcodeindex} commands to define new -indices. These commands create new indexing @@-commands with which -you mark index entries. The @code{@@defindex} command is used like -this: - -@example -@@defindex @var{name} -@end example - -The name of an index should be a two letter word, such as @samp{au}. -For example: - -@example -@@defindex au -@end example - -This defines a new index, called the @samp{au} index. At the same -time, it creates a new indexing command, @code{@@auindex}, that you -can use to make index entries. Use this new indexing command just as -you would use a predefined indexing command. - -For example, here is a section heading followed by a concept index -entry and two @samp{au} index entries. - -@example -@@section Cognitive Semantics -@@cindex kinesthetic image schemas -@@auindex Johnson, Mark -@@auindex Lakoff, George -@end example - -@noindent -(Evidently, @samp{au} serves here as an abbreviation for ``author''.) - -In general, Texinfo constructs the new indexing command by -concatenating the name of the index with @samp{index}; thus, defining -an @samp{xy} index leads to the automatic creation of an -@code{@@xyindex} command. - -Use the @code{@@printindex} command to print the index, as you do with -the predefined indices. For example: - -@example -@group -@@node Author Index -@@unnumbered Author Index - -@@printindex au -@end group -@end example - -The @code{@@defcodeindex} is like the @code{@@defindex} command, -except that, in the printed output, it prints entries in an -@code{@@code} font by default instead of a roman font. - -You should define new indices before the end-of-header line of a -Texinfo file, and (of course) before any @code{@@synindex} or -@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). - - -@node Insertions -@chapter Special Insertions -@cindex Inserting special characters and symbols -@cindex Special insertions - -Texinfo provides several commands for inserting characters that have -special meaning in Texinfo, such as braces, and for other graphic -elements that do not correspond to simple characters you can type. - -@iftex -These are: - -@itemize @bullet -@item @samp{@@} and braces and commas. -@item Whitespace within and around a sentence. -@item Accents. -@item Dots and bullets. -@item The @TeX{} logo and the copyright symbol. -@item The euro and pounds currency symbols. -@item The degrees symbol. -@item The minus sign. -@item Mathematical expressions. -@item Glyphs for evaluation, macros, errors, etc. -@item Footnotes. -@item Images. -@end itemize -@end iftex - -@menu -* Atsign Braces Comma:: Inserting @@ and @{@} and ,. -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Inserting Quotation Marks:: How to insert quotation marks. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* euro:: How to insert the Euro currency symbol. -* pounds:: How to insert the pounds currency symbol. -* textdegree:: How to insert the degrees symbol. -* minus:: How to insert a minus sign. -* geq leq:: How to insert greater/less-than-or-equal signs. -* math:: How to format a mathematical expression. -* Click Sequences:: Inserting GUI usage sequences. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -@end menu - - -@node Atsign Braces Comma -@section Inserting @@ and @{@} and @comma{} -@cindex Special characters, inserting -@cindex Commands to insert special characters - -@samp{@@} and curly braces are special characters in Texinfo. To insert -these characters so they appear in text, you must put an @samp{@@} in -front of these characters to prevent Texinfo from misinterpreting -them. - -The comma `,' is a special character only in one uncommon context: -it separates arguments to commands that take multiple arguments. - -@menu -* Inserting an Atsign:: -* Inserting Braces:: -* Inserting a Comma:: -@end menu - - -@node Inserting an Atsign -@subsection Inserting `@@' with @code{@@@@} -@findex @@ @r{(literal @samp{@@})} -@cindex Inserting @@ @r{(literal @samp{@@})} - -@code{@@@@} stands for a single @samp{@@} in either printed or Info -output. - -Do not put braces after an @code{@@@@} command. - - -@node Inserting Braces -@subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}} -@cindex Braces, inserting -@findex @{ @r{(literal @samp{@{})} -@findex @} @r{(literal @samp{@}})} - -@code{@@@{} stands for a single @samp{@{} in either printed or Info -output. - -@code{@@@}} stands for a single @samp{@}} in either printed or Info -output. - -Do not put braces after either an @code{@@@{} or an @code{@@@}} -command. - - -@node Inserting a Comma -@subsection Inserting `,' with @code{@@comma@{@}} -@cindex Commas, inserting -@findex comma - -Ordinarily, a comma `,' is a normal character that can be simply typed -in your input where you need it. - -However, Texinfo uses the comma as a special character in one uncommon -context: some commands, such as @code{@@acronym} (@pxref{acronym}) and -@code{@@xref} (@pxref{Cross References}), as well as user-defined -macros (@pxref{Defining Macros}), can take more than one argument. In -these cases, the comma character is used to separate arguments. - -Since a comma character would confuse Texinfo's parsing for these -commands, you must use the command @samp{@@comma@{@}} instead if you want -to pass an actual comma. Here are some examples: - -@example -@@acronym@{ABC, A Bizarre @@comma@{@}@} -@@xref@{Comma,, The @@comma@{@} symbol@} -@@mymac@{One argument@@comma@{@} containing a comma@} -@end example - -Although @comma{} can be used nearly anywhere, there is no need for it -anywhere except in this unusual case. - - -@node Inserting Quote Characters -@section Inserting Quote Characters - -@cindex Inserting quote characters -@cindex Quote characters, inserting - -As explained in the early section on general Texinfo input conventions -(@pxref{Conventions}), Texinfo source files use the ASCII character -@code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'} -(39 decimal) to produce a right quote ('). Doubling these input -characters (@code{``} and @code{''}) produces double quotes (`` and -''). These are the conventions used by @TeX{}. - -This works all right for text. However, in examples of computer code, -readers are especially likely to cut and paste the text -verbatim---and, unfortunately, some document viewers will mangle these -characters. (The free PDF reader @command{xpdf} works fine, but other -PDF readers, both free and nonfree, have problems.) - -If this is a concern for your document, Texinfo provides two special -settings via @code{@@set}: - -@table @code -@item @@set txicodequoteundirected -causes the output for the @code{'} character to be the undirected -single quote, like this: -@set txicodequoteundirected -@code{'}. -@clear txicodequoteundirected - -@item @@set txicodequotebacktick -Cause the output for the @code{`} character to be the standalone grave -accent, like this: -@set txicodequotebacktick -@code{`}. -@clear txicodequotebacktick - -@end table - -@code{xyza`'bc} - -If you want these settings for only part of the document, -@code{@@clear} will restore the normal behavior, as in -@code{@@clear@tie{}txicodequoteundirected}. - -These settings affect @code{@@code}, @code{@@example}, and -@code{@@verbatim}; they do not affect @code{@@samp}. (@xref{Useful -Highlighting}.) - - -@node Inserting Space -@section Inserting Space - -@cindex Inserting space -@cindex Spacing, inserting -The following sections describe commands that control spacing of various -kinds within and after sentences. - -@menu -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* frenchspacing:: Specifying end-of-sentence spacing. -* dmn:: How to format a dimension. -@end menu - - -@node Not Ending a Sentence -@subsection Not Ending a Sentence - -@cindex Not ending a sentence -@cindex Sentence non-ending punctuation -@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 -in an abbreviation, special commands are needed in some circumstances. -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. - -@findex <colon> @r{(suppress end-of-sentence space)} -Use the @code{@@:}@: command after a period, question mark, -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. - -For example, - -@example -foo vs.@@: bar -foo vs. bar -@end example - -@noindent -@ifnottex -produces -@end ifnottex -@iftex -produces the following. If you look carefully at this printed output, -you will see a little extraneous space after @samp{vs.}@: in the second -line. -@end iftex - -@quotation -foo vs.@: bar @* -foo vs. bar -@end quotation - -@noindent -@code{@@:} has no effect on the Info and HTML output. In Docbook and -XML, the previous punctuation character (.?!:) is output as an entity -instead of as the normal character: @samp{. ? ! -:}. This gives further processors a chance to notice and not -add the usual extra space. - -Do not put braces after @code{@@:} (or any non-alphabetic command). - - -@node Ending a Sentence -@subsection Ending a Sentence - -@cindex Ending a Sentence -@cindex Sentence ending punctuation - -@findex . @r{(end of sentence)} -@findex ! @r{(end of sentence)} -@findex ? @r{(end of sentence)} -Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an -exclamation point, and @code{@@?}@: instead of a question mark at the end -of a sentence that ends with a capital letter. Otherwise, @TeX{} -will think the letter is an abbreviation and will not insert the correct -end-of-sentence spacing. Here is an example: - -@example -Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end example - -@noindent -@ifnottex -produces -@end ifnottex -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after the @samp{W} in the first -line. -@end iftex - -@quotation -Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* -Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. -@end quotation - -In the Info file output, @code{@@.}@: is equivalent to a simple -@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. - -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}). - -Do not put braces after any of these commands. - - -@node Multiple Spaces -@subsection Multiple Spaces - -@cindex Multiple spaces -@cindex Whitespace, inserting -@cindex Space, inserting horizontal -@findex <space> -@findex <tab> -@findex <newline> - -Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, -and newline) into a single space. Info output, on the other hand, -preserves whitespace as you type it, except for changing a newline into -a space; this is why it is important to put two spaces at the end of -sentences in Texinfo documents. - -Occasionally, you may want to actually insert several consecutive -spaces, either for purposes of example (what your program does with -multiple spaces as input), or merely for purposes of appearance in -headings or lists. Texinfo supports three commands: -@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of -which insert a single space into the output. (Here, -@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a -space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab -character and end-of-line, i.e., when @samp{@@} is the last character on -a line.) - -For example, -@example -Spacey@@ @@ @@ @@ -example. -@end example - -@noindent produces - -@example -Spacey@ @ @ @ -example. -@end example - -Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by -@code{@@multitable} (@pxref{Multi-column Tables}). - -Do not follow any of these commands with braces. - -To produce a non-breakable space, see @ref{tie, @code{@@tie}}. - - -@node frenchspacing -@subsection @code{@@frenchspacing} @var{val}: Control sentence spacing -@findex frenchspacing -@cindex French spacing -@cindex Sentences, spacing after -@cindex Space, after sentences - -In American typography, it is traditional and correct to put extra -space at the end of a sentence, after a semi-colon, and so on. This -is the default in Texinfo. In French typography (and many others), -this extra space is wrong; all spaces are uniform. - -Therefore Texinfo provides the @code{@@frenchspacing} command to -control the spacing after punctuation. It reads the rest of the line -as its argument, which must be the single word @samp{on} or @samp{off} -(always these words, regardless of the language) of the document. -Here is an example: - -@example -@@frenchspacing on -This is text. Two sentences. Three sentences. French spacing. - -@@frenchspacing off -This is text. Two sentences. Three sentences. Non-French spacing. -@end example - -@noindent produces (there will be no difference in Info): - -@frenchspacing on -This is text. Two sentences. Three sentences. French spacing. - -@frenchspacing off -This is text. Two sentences. Three sentences. Non-French spacing. - -@code{@@frenchspacing} mainly affects the printed output, including -the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending -a Sentence}). - -In Info, usually space characters in the input are written unaltered -to the output, and @code{@@frenchspacing} does not change this. It -does change the one case where @command{makeinfo} outputs a space on -its own: when a sentence ends at a newline in the source. Here's an -example: - -@example -Some sentence. -Next sentence. -@end example - -@noindent produces in Info output, with @code{@@frenchspacing off} -(the default), two spaces between the sentences: - -@example -Some sentence. Next sentence. -@end example - -@noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs -only a single space: - -@example -Some sentence. Next sentence. -@end example - -@code{@@frenchspacing} has no effect on the HTML or Docbook output; -for XML, it outputs a transliteration of itself (@pxref{Output -Formats}). - - -@node dmn -@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension -@cindex Thin space between number, dimension -@cindex Dimension formatting -@cindex Format a dimension -@findex dmn - -At times, you may want to write @samp{12@dmn{pt}} or -@samp{8.5@dmn{in}} with little or no space between the number and the -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. - -To use the @code{@@dmn} command, write the number and then follow it -immediately, with no intervening space, by @code{@@dmn}, and then by -the dimension within braces. For example, - -@example -A4 paper is 8.27@@dmn@{in@} wide. -@end example - -@noindent -produces - -@quotation -A4 paper is 8.27@dmn{in} wide. -@end quotation - -Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}} -or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file. -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}. - - -@node Inserting Accents -@section Inserting Accents - -@cindex Inserting accents -@cindex Accents, inserting -@cindex Floating accents, inserting - -Here is a table with the commands Texinfo provides for inserting -floating accents. The commands with non-alphabetic names do not take -braces around their argument (which is taken to be the next character). -(Exception: @code{@@,} @emph{does} take braces around its argument.) -This is so as to make the source as convenient to type and read as -possible, since accented characters are very common in some languages. - -@findex documentencoding -To get the true accented characters output in Info, and not just the -ASCII transliterations, it is necessary to specify -@code{@@documentencoding} with an encoding which supports the required -characters (@pxref{documentencoding,,@code{@@documentencoding}}). - -@findex " @r{(umlaut accent)} -@cindex Umlaut accent -@findex ' @r{(umlaut accent)} -@cindex Acute accent -@findex = @r{(macron accent)} -@cindex Macron accent -@findex ^ @r{(circumflex accent)} -@cindex Circumflex accent -@findex ` @r{(grave accent)} -@cindex Grave accent -@findex ~ @r{(tilde accent)} -@cindex Tilde accent -@findex , @r{(cedilla accent)} -@cindex Cedilla accent -@findex dotaccent -@cindex Dot accent -@findex H @r{(Hungarian umlaut accent)} -@cindex Hungarian umlaut accent -@findex ringaccent -@cindex Ring accent -@findex tieaccent -@cindex Tie-after accent -@findex u @r{(breve accent)} -@cindex Breve accent -@findex ubaraccent -@cindex Underbar accent -@findex udotaccent -@cindex Underdot accent -@findex v @r{(check accent)} -@cindex Hacek accent -@cindex Check accent -@cindex Caron accent -@multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent} -@headitem Command @tab Output @tab What -@item @t{@@"o} @tab @"o @tab umlaut accent -@item @t{@@'o} @tab @'o @tab acute accent -@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent -@item @t{@@=o} @tab @=o @tab macron/overbar accent -@item @t{@@^o} @tab @^o @tab circumflex accent -@item @t{@@`o} @tab @`o @tab grave accent -@item @t{@@~o} @tab @~o @tab tilde accent -@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent -@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut -@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent -@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent -@item @t{@@u@{o@}} @tab @u{o} @tab breve accent -@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent -@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent -@item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent -@end multitable - -This table lists the Texinfo commands for inserting other characters -commonly used in languages other than English. - -@findex questiondown -@cindex @questiondown{} -@findex exclamdown -@cindex @exclamdown{} -@findex aa -@cindex @aa{} -@findex AA -@cindex @AA{} -@findex ae -@cindex @ae{} -@findex AE -@cindex @AE{} -@findex dotless -@cindex @dotless{i} (dotless i) -@cindex @dotless{j} (dotless j) -@cindex Dotless i, j -@findex l -@cindex @l{} -@findex L -@cindex @L{} -@findex o -@cindex @o{} -@findex O -@cindex @O{} -@findex oe -@cindex @oe{} -@findex OE -@cindex @OE{} -@cindex Romance ordinals -@cindex Ordinals, Romance -@cindex Feminine ordinal -@findex ordf -@cindex @ordf{} -@cindex Masculine ordinal -@findex ordm -@cindex @ordm{} -@findex ss -@cindex @ss{} -@cindex Es-zet -@cindex Sharp S -@cindex German S -@multitable {@t{@@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{@@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{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals -@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S -@end multitable - - -@node Inserting Quotation Marks -@section Inserting Quotation Marks -@cindex Inserting quotation marks -@cindex Quotation marks, inserting - -@cindex Quotation characters (`'), in source -Use doubled single-quote characters to begin and end quotations: -@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to -left- and right-hand doubled quotation marks, -@c this comes out as "like this" in Info, which is just confusing. -@iftex -``like this'', -@end iftex -and Info converts doubled single-quote characters to ASCII -double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. - -You may occasionally need to produce two consecutive single quotes; -for example, in documenting a computer language such as Maxima where -@t{'@w{}'} is a valid command. You can do this with the input -@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into -the double-quote characters. - -@cindex Unicode quotation characters -@cindex Grave accent, vs. left quote -The left quote character (@t{`}, ASCII code 96) used in Texinfo is a -grave accent in ANSI and ISO character set standards. We use it as a -quote character because that is how @TeX{} is set up, by default. - -Texinfo supports several other quotation marks used in languages other -than English. Below is a table with the commands Texinfo provides for -inserting quotation marks. - -@findex documentencoding -@cindex UTF-8 -@cindex ISO 8859-15 -@cindex Latin 9 -@cindex ISO 8859-1 -@cindex Latin 1 -In order to get the symbols for the quotation marks in encoded Info -output, it is necessary to specify @code{@@documentencoding UTF-8}. -(@xref{documentencoding,,@code{@@documentencoding}}.) Double -guillemets are also present in ISO 8859-1 (aka Latin@tie{}1) and ISO -8859-15 (aka Latin@tie{}9). - -@cindex European Computer Modern fonts -@cindex EC fonts -The standard @TeX{} fonts support the usual quotation marks used in -English (the ones produced with single and doubled ASCII -single-quotes). For the other quotation marks, @TeX{} uses European -Computer Modern (EC) fonts (@file{ecrm1000} and other variants). -These fonts are freely available, of course; you can download them -from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other -places. - -@cindex CM-Super fonts -The free EC fonts are bitmap fonts created with Metafont. Especially -for on-line viewing, Type@tie{}1 (vector) versions of the fonts are -preferable; these are available in the CM-Super font package -(@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}). - -Both distributions include installation instructions. - -@cindex Single quotation marks -@cindex Double quotation marks -@cindex Left quotation marks -@cindex Right quotation marks -@findex quotedblleft -@cindex `` -@findex quoteleft -@cindex ` -@findex quotedblright -@cindex '' -@findex quoteright -@cindex ' -@cindex Double low-9 quotation mark -@cindex Single low-9 quotation mark -@findex quotedblbase -@cindex @quotedblbase{} (double low-9 quotation mark) -@findex quotesinglbase -@cindex @quotesinglbase{} (single low-9 quotation mark) -@cindex Angle quotation marks -@cindex Guillemets -@cindex Guillemots -@cindex French quotation marks -@cindex Quotation marks, French -@cindex German quotation marks -@cindex Quotation marks, German -@cindex Double guillemets -@cindex Single guillemets -@cindex Double angle quotation marks -@cindex Single angle quotation marks -@cindex Left-pointing angle quotation marks -@cindex Right-pointing angle quotation marks -@cindex Double left-pointing angle quotation mark -@cindex Double right-pointing angle quotation mark -@cindex Single left-pointing angle quotation mark -@cindex Single right-pointing angle quotation mark -@findex guillemetleft -@findex guillemotleft -@cindex @guillemetleft{} -@findex guillemetright -@findex guillemotright -@cindex @guillemetright{} -@findex guilsinglleft -@cindex @guilsinglleft{} -@findex guilsinglright -@cindex @guilsinglright{} -@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)} -@headitem Command @tab Glyph @tab Unicode name (point) -@item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C) -@item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D) -@item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018) -@item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019) -@item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E) -@item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A) -@item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB) -@item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB) -@item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039) -@item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A) -@end multitable - -For the double angle quotation marks, Adobe and @LaTeX{} glyph names -are also supported: @code{@@guillemotleft} and -@code{@@guillemotright}. These names are actually incorrect; a -``guillemot'' is a bird species (a type of auk). - -Traditions for quotation mark usage vary to a great extent between -languages (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}). -Texinfo does not provide commands for typesetting quotation marks -according to the numerous traditions. Therefore, you have to choose -the commands appropriate for the language of your manual. Sometimes -aliases (@pxref{alias,,@code{@@alias}}) can simplify the usage and -make the source code more readable. For example, in German, -@code{@@quotedblbase} is used for the left double quote, and the right -double quote is actually @code{@@quotedblleft}, which is -counter-intuitive. Thus, in this case the following aliases would be -convenient: - -@example -@@alias lgqq = quotedblbase -@@alias rgqq = quotedblleft -@end example - - -@node Dots Bullets -@section Inserting Ellipsis and Bullets -@cindex Dots, inserting -@cindex Bullets, inserting -@cindex Ellipsis, inserting -@cindex Inserting ellipsis -@cindex Inserting dots -@cindex Special typesetting commands -@cindex Typesetting commands for dots, etc. - -An @dfn{ellipsis} (a line of dots) is not typeset as a string of -periods, so a special command is used for ellipsis in Texinfo. The -@code{@@bullet} command is special, too. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. (You need to use braces -with these commands because you can use them next to other text; without -the braces, the formatters would be confused. @xref{Command Syntax, , -@@-Command Syntax}, for further information.)@refill - -@menu -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. -@end menu - - -@node dots -@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{}) -@findex dots -@findex enddots -@cindex Inserting dots -@cindex Dots, inserting - -Use the @code{@@dots@{@}} command to generate an ellipsis, which is -three dots in a row, appropriately spaced @dots{} like so. Do -not simply write three periods in the input file; that would work for -the Info file output, but would produce the wrong amount of space -between the periods in the printed manual. - -Similarly, the @code{@@enddots@{@}} command generates an -end-of-sentence ellipsis, which has different spacing afterwards, -@enddots{} Look closely to see the difference. - -@iftex -Here is an ellipsis: @dots{} -Here are three periods in a row: ... - -In printed output, the three periods in a row are much closer together than -the dots in the ellipsis. -@end iftex - - -@node bullet -@subsection @code{@@bullet}@{@} (@bullet{}) -@findex bullet - -Use the @code{@@bullet@{@}} command to generate a large round dot, or -the closest possible thing to one. In Info, an asterisk is used.@refill - -Here is a bullet: @bullet{} - -When you use @code{@@bullet} in @code{@@itemize}, you do not need to -type the braces, because @code{@@itemize} supplies them. -(@xref{itemize, , @code{@@itemize}}.)@refill - - -@node TeX and copyright -@section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} - -The logo `@TeX{}' is typeset in a special fashion and it needs an -@@-command. The copyright and registered symbols, `@copyright{}' and -`@registeredsymbol{}', is also special. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. - -@menu -* tex:: The @TeX{} logos. -* copyright symbol:: The copyright symbol (c in a circle). -* registered symbol:: The registered symbol (R in a circle). -@end menu - - -@node tex -@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) -@findex TeX -@findex LaTeX -@cindex Logos, @TeX{} -@cindex @TeX{} logo -@cindex @LaTeX{} logo - -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}. - -Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}', -which is even more special in printed manuals (and different from the -incorrect @code{La@@TeX@{@}}. In Info, the result is just -@samp{LaTeX}. (@LaTeX{} is another macro package built on top of -@TeX{}, very loosely analogous to Texinfo in that it emphasizes -logical structure, but much (much) larger.) - -The spelling of these commands are unusual among Texinfo commands in -that they use both uppercase and lowercase letters. - - -@node copyright symbol -@subsection @code{@@copyright@{@}} (@copyright{}) -@findex copyright -@cindex Copyright symbol - -Use the @code{@@copyright@{@}} command to generate the copyright -symbol, `@copyright{}'. Where possible, this is a @samp{c} -inside a circle; in Info, this is @samp{(C)}. - - -@node registered symbol -@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) -@findex registeredsymbol -@cindex Registered symbol - -Use the @code{@@registeredsymbol@{@}} command to generate the -registered symbol, `@registeredsymbol{}'. Where possible, this is an -@samp{R} inside a circle; in Info, this is @samp{(R)}. - - -@node euro -@section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol -@findex euro -@cindex Euro symbol - -Use the @code{@@euro@{@}} command to generate `@euro{}'. Where -possible, this is the symbol for the Euro currency, invented as part -of the European economic unification. In plain Info, it is the word -@samp{Euro }. A trailing space is included in the text -transliteration since typically no space is desired after the symbol, -so it would be inappropriate to have a space in the source document. - -Texinfo cannot magically synthesize support for the Euro symbol where -the underlying system (fonts, software, whatever) does not support -it. Therefore, in many cases it is preferable to use the word -``Euro''. (In banking circles, the abbreviation for the Euro is EUR.) - -@cindex ISO 8859-15 -@cindex Latin 9 -In order to get the Euro symbol in encoded Info output, for example, -it is necessary to specify @code{@@documentencoding ISO-8859-15}. -(@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol -is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more -widely-used and supported ISO 8859-1 (Latin@tie{}1). - -@pindex feymr10 -@cindex Euro font -The Euro symbol does not exist in the standard @TeX{} fonts (which -were designed before the Euro was legislated into existence). -Therefore, @TeX{} uses an additional font, named @code{feymr10} (along -with other variables). It is freely available, of course; you can -download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym}, -among other places. The distribution includes installation -instructions. - - -@node pounds -@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling -@findex pounds -@cindex Pounds symbol - -Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where -possible, this is the symbol for the currency pounds sterling. In -Info, it is a @samp{#}. - - -@node textdegree -@section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol -@findex textdegree -@cindex Degree symbol - -Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. -Where possible, this is the normal symbol for degrees. In plain text -and Info output, it is an @samp{o}. - - -@node minus -@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign -@findex minus -@cindex Minus sign - -@cindex Em dash, compared to minus sign -@cindex Hyphen, compared to minus -Use the @code{@@minus@{@}} command to generate a minus sign. In a -fixed-width font, this is a single hyphen, but in a proportional font, -the symbol is the customary length for a minus sign---a little longer -than a hyphen, shorter than an em-dash: - -@display -@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, - -`-' is a hyphen generated with the character @samp{-}, - -`---' is an em-dash for text. -@end display - -@noindent -In the fixed-width font used by Info, @code{@@minus@{@}} is the same -as a hyphen. - -You should not use @code{@@minus@{@}} inside @code{@@code} or -@code{@@example} because the width distinction is not made in the -fixed-width font they use. - -When you use @code{@@minus} to specify the mark beginning each entry in -an itemized list, you do not need to type the braces -(@pxref{itemize, , @code{@@itemize}}). - - -@node geq leq -@section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations -@findex geq -@findex leq - -Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate -greater-than-or-equal and less-than-equal-signs, `@geq{}' and -`@leq{}'. In plain text and Info output, these are the ASCII -sequences @samp{>=} and @samp{<=}. - - -@node math -@section @code{@@math}: Inserting Mathematical Expressions -@findex math -@cindex Mathematical expressions -@cindex Formulas, mathematical - -You can write a short mathematical expression with the @code{@@math} -command. Write the mathematical expression between braces, like this: - -@example -@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} -@end example - -@iftex -@noindent This produces the following in @TeX{}: - -@display -@math{(a + b)(a + b) = a^2 + 2ab + b^2} -@end display - -@noindent and the following in other formats: -@end iftex -@ifnottex -@noindent This produces the following in Info and HTML: -@end ifnottex - -@example -(a + b)(a + b) = a^2 + 2ab + b^2 -@end example - -The @code{@@math} command has no special effect on the Info and HTML -output. @command{makeinfo} expands any @code{@@}-commands as usual, -but it does not try to produce good mathematical formatting in any -way. - -However, as far as the @TeX{} output is concerned, plain @TeX{} -mathematical commands are allowed in @code{@@math}, starting with -@samp{\}, and the plain @TeX{} math characters like @samp{^} and -@samp{_} are also recognized. In essence, @code{@@math} drops you -into plain @TeX{} math mode. - -This allows you to conveniently write superscripts and subscripts (as -in the above example), and also to use all the plain @TeX{} math -control sequences for symbols, functions, and so on, and thus get -proper formatting in the @TeX{} output, at least. - -It's best to use @samp{\} instead of @samp{@@} for any such -mathematical commands; otherwise, @command{makeinfo} will complain. -On the other hand, input with matching (but unescaped) braces, such as -@samp{k_@{75@}}, is allowed inside @code{@@math}, although -@command{makeinfo} would complain about the bare braces in regular -input. - -Here's an example: - -@example -@@math@{\sin 2\pi \equiv \cos 3\pi@} -@end example - -@iftex -@noindent which looks like this in @TeX{}: -@display -@math{\sin 2\pi \equiv \cos 3\pi} -@end display - -@noindent and -@end iftex -@noindent which looks like the input in Info and HTML: -@example -\sin 2\pi \equiv \cos 3\pi -@end example - -@findex \ @r{(literal \ in @code{@@math})} -Since @samp{\} is an escape character inside @code{@@math}, you can use -@code{@@\} to get a literal backslash (@code{\\} will work in @TeX{}, -but you'd get the literal @samp{\\} in Info). @code{@@\} is not -defined outside of @code{@@math}, since a @samp{\} ordinarily produces a -literal @samp{\}. - -@cindex Displayed equations -@cindex Equations, displayed -For displayed equations, you must at present use @TeX{} directly -(@pxref{Raw Formatter Commands}). - - -@node Click Sequences -@section Click Sequences -@cindex Click sequences -@cindex Sequence of clicks -@cindex GUI click sequence - -@findex clicksequence -When documenting graphical interfaces, it is necessary to describe -sequences such as `Click on @samp{File}, then choose @samp{Open}, then -@dots{}'. Texinfo offers commands @code{@@clicksequence} and -@code{click} to represent this, typically used like this: - -@example -@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} -@end example - -@noindent -which produces: - -@display -@dots{} @clicksequence{File @click{} Open} @dots{} -@end display - -@findex click -@findex arrow -The @code{@@click} command produces a simple right arrow (@samp{->} in -Info) by default; this glyph is also available independently via the -command @code{@@arrow@{@}}. - -@findex clickstyle -You can change the glyph produced by @code{@@click} with the command -@code{@@clickstyle}, which takes a command name as its single argument -on the rest of the line, much like @code{@@itemize} and friends -(@pxref{itemize,,@code{@@itemize}}). The command should produce a -glyph, and the usual empty braces @samp{@{@}} are omitted. Here's an -example: - -@example -@@clickstyle @@result -@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} -@end example - -@noindent -now produces: - -@display -@clickstyle @result -@dots{} @clicksequence{File @click{} Open} @dots{} -@end display - - -@node Glyphs -@section Glyphs for Examples -@cindex Glyphs -@cindex Examples, glyphs for - -In Texinfo, code is often illustrated in examples that are delimited -by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and -@code{@@end lisp}. In such examples, you can indicate the results of -evaluation or an expansion using @samp{@result{}} or -@samp{@expansion{}}. Likewise, there are commands to insert glyphs -to indicate -printed output, error messages, equivalence of expressions, and the -location of point. - -The glyph-insertion commands do not need to be used within an example, but -most often they are. Every glyph-insertion command is followed by a pair of -left- and right-hand braces.@refill - -@menu -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. -@end menu - - -@node Glyphs Summary -@subsection Glyphs Summary - -Here are the different glyph commands:@refill - -@table @asis -@item @result{} -@code{@@result@{@}} points to the result of an expression.@refill - -@item @expansion{} -@code{@@expansion@{@}} shows the results of a macro expansion.@refill - -@item @print{} -@code{@@print@{@}} indicates printed output.@refill - -@item @error{} -@code{@@error@{@}} indicates that the following text is an error -message.@refill - -@item @equiv{} -@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill - -@item @point{} -@code{@@point@{@}} shows the location of point.@refill -@end table - -@menu -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: -@end menu - - -@node result -@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation -@cindex Result of an expression -@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 - -@iftex -The @code{@@result@{@}} command is displayed as @samp{@result{}} in -the printed output and as @samp{=>} in other formats. -@end iftex -@ifnottex -The @code{@@result@{@}} command is displayed as @samp{@result{}} in -Info and HTML and as a true double stemmed arrow in the printed output. -@end ifnottex - -Thus, the following, - -@lisp -(cdr '(1 2 3)) - @result{} (2 3) -@end lisp - -@noindent -may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. - - -@node expansion -@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion -@cindex Expansion, indicating -@cindex Macro expansion, indicating -@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 -@code{@@expansion@{@}} command.@refill - -@iftex -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in the printed output and as @samp{==>} in other formats. -@end iftex -@ifnottex -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in Info and HTML, and as a long arrow with a flat base in the printed -output. -@end ifnottex - -@need 700 -For example, the following - -@example -@group -@@lisp -(third '(a b c)) - @@expansion@{@} (car (cdr (cdr '(a b c)))) - @@result@{@} c -@@end lisp -@end group -@end example - -@noindent -produces - -@lisp -@group -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end group -@end lisp - -@noindent -which may be read as: - -@quotation -@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; -the result of evaluating the expression is @code{c}. -@end quotation - -@noindent -Often, as in this case, an example looks better if the -@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. - - -@node Print Glyph -@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output -@cindex Printed output, indicating -@findex print - -Sometimes an expression will print output during its execution. You -can indicate the printed output with the @code{@@print@{@}} command.@refill - -@iftex -The @code{@@print@{@}} command is displayed as @samp{-|} in Info and -HTML and as @samp{@print{}} in the printed output. -@end iftex -@ifnottex -The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info -and HTML and (similarly) as a horizontal dash butting against a -vertical bar in the printed output. -@end ifnottex - -In the following example, the printed text is indicated with -@samp{@print{}}, and the value of the expression follows on the -last line. - -@lisp -@group -(progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end lisp - -@noindent -In a Texinfo source file, this example is written as follows: - -@lisp -@group -@@lisp -(progn (print 'foo) (print 'bar)) - @@print@{@} foo - @@print@{@} bar - @@result@{@} bar -@@end lisp -@end group -@end lisp - - -@node Error Glyph -@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message -@cindex Error message, indicating -@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 - -@iftex -The @code{@@error@{@}} command is displayed as @samp{error-->} in Info -and HTML and as @samp{@error{}} in the printed output. -@end iftex -@ifnottex -The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info -and HTML and as the word `error' in a box in the printed output. -@end ifnottex - -@need 700 -Thus, - -@example -@@lisp -(+ 23 'x) -@@error@{@} Wrong type argument: integer-or-marker-p, x -@@end lisp -@end example - -@noindent -produces - -@lisp -(+ 23 'x) -@error{} Wrong type argument: integer-or-marker-p, x -@end lisp - -@noindent -This indicates that the following error message is printed -when you evaluate the expression: - -@lisp -Wrong type argument: integer-or-marker-p, x -@end lisp - -@samp{@error{}} itself is not part of the error message. - - -@node Equivalence -@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence -@cindex Equivalence, indicating -@findex equiv - -Sometimes two expressions produce identical results. You can indicate the -exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill - -@iftex -The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and -HTML and as @samp{@equiv{}} in the printed output. -@end iftex -@ifnottex -The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info -and HTML and as a standard mathematical equivalence sign (three -parallel horizontal lines) in the printed output. -@end ifnottex - -Thus, - -@example -@@lisp -(make-sparse-keymap) @@equiv@{@} (list 'keymap) -@@end lisp -@end example - -@noindent -produces - -@lisp -(make-sparse-keymap) @equiv{} (list 'keymap) -@end lisp - -@noindent -This indicates that evaluating @code{(make-sparse-keymap)} produces -identical results to evaluating @code{(list 'keymap)}. - - -@node Point Glyph -@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer -@cindex Point, indicating in a buffer -@findex point - -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 -buffer in question between two lines of dashes containing the buffer -name.@refill - -You can use the @samp{@@point@{@}} command to show the location of point -in the text in the buffer. (The symbol for point, of course, is not -part of the text in the buffer; it indicates the place @emph{between} -two characters where point is located.)@refill - -@iftex -The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and -HTML and as @samp{@point{}} in the printed output. -@end iftex -@ifnottex -The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info -and HTML and as a small five pointed star in the printed -output. -@end ifnottex - -The following example shows the contents of buffer @file{foo} before -and after evaluating a Lisp command to insert the word @code{changed}.@refill - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -@example -@group -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- - -@end group -@end example - -In a Texinfo source file, the example is written like this:@refill - -@example -@@example ----------- Buffer: foo ---------- -This is the @@point@{@}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @@result@{@} nil ----------- Buffer: foo ---------- -This is the changed @@point@{@}contents of foo. ----------- Buffer: foo ---------- -@@end example -@end example - - -@node Breaks -@chapter Forcing and Preventing Breaks -@cindex Forcing line and page breaks -@cindex Making line and page breaks -@cindex Preventing line and page breaks - -@cindex Line 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. - -@cindex White space, excessive -@cindex Page breaks -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. - -@menu -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* - and hyphenation:: Helping @TeX{} with hyphenation points. -* allowcodebreaks:: Controlling line breaks within @@code text. -* w:: Preventing unwanted line breaks in text. -* tie:: Inserting an unbreakable but varying space. -* sp:: Inserting blank lines. -* page:: Forcing the start of a new page. -* group:: Preventing unwanted page breaks. -* need:: Another way to prevent unwanted page breaks. -@end menu - - -@node Break Commands -@section Break Commands - -The break commands create or allow line and paragraph breaks: - -@table @code -@item @@* -Force a line break. - -@item @@sp @var{n} -Skip @var{n} blank lines. - -@item @@- -Insert a discretionary hyphen. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Define hyphen points in @var{hy-phen-a-ted words}. -@end table - -These commands hold text together on a single line: - -@table @code -@item @@w@{@var{text}@} -Prevent @var{text} from being split and hyphenated across two lines. -@item @@tie@{@} -Insert a normal interword space at which a line break may not occur. -@end table -@iftex -@sp 1 -@end iftex - -The pagination commands apply only to printed output, since Info -files do not have pages. - -@table @code -@item @@page -Start a new page in the printed manual. - -@item @@group -Hold text together that must appear on one printed page. - -@item @@need @var{mils} -Start a new printed page if not enough space on this one. -@end table - - -@node Line Breaks -@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks -@findex * @r{(force line break)} -@findex / @r{(allow line break)} -@cindex Line breaks -@cindex Breaks in a line -@cindex Force line break -@cindex Allow line break - -The @code{@@*} command forces a line break in both the printed manual and -in Info. The @code{@@/} command allows a line break (printed manual only). - -Here is an example with @code{@@*}: - -@example -This line @@* is broken @@*in two places. -@end example - -@noindent produces - -@example -@group -This line -is broken -in two places. -@end group -@end example - -The @code{@@/} command can be useful within a url -(@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise -unbreakable. For example: - -@example -The official Texinfo home page is on the GNU web site: -@@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}. -@end example - -@noindent produces - -@display -The official Texinfo home page is on the GNU web site: -@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. -@end display - -@noindent Without the @code{@@/} commands, @TeX{} would have nowhere to -break the line. @code{@@/} has no effect in the online output. - - -@node - and hyphenation -@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate - -@findex - @r{(discretionary hyphen)} -@findex hyphenation -@cindex Hyphenation, helping @TeX{} do -@cindex Fine-tuning, and hyphenation - -Although @TeX{}'s hyphenation algorithm is generally pretty good, it -does miss useful hyphenation points from time to time. (Or, far more -rarely, insert an incorrect hyphenation.) So, for documents with an -unusual vocabulary or when fine-tuning for a printed edition, you may -wish to help @TeX{} out. Texinfo supports two commands for this: - -@table @code -@item @@- -Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does -not have to) hyphenate. This is especially useful when you notice an -overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull -hboxes}). @TeX{} will not insert any hyphenation points itself into a -word containing @code{@@-}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you -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 -words match exactly, so give all necessary variants, such as plurals. -@end table - -Info, HTML, and other non-@TeX{} output is not hyphenated, so none of -these commands have any effect there. - - -@node allowcodebreaks -@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} - -@findex allowcodebreaks -@cindex Breaks, within @code{@@code} -@cindex -, breakpoint within @code{@@code} -@cindex Hyphen, breakpoint within @code{@@code} -@cindex Dash, breakpoint within @code{@@code} -@cindex _, breakpoint within @code{@@code} -@cindex Underscore, breakpoint within @code{@@code} - -Ordinarily, @TeX{} will consider breaking lines at @samp{-} and -@samp{_} characters within @code{@@code} and related commands -(@pxref{code,,@code{@@code}}), more or less as if they were ``empty'' -hyphenation points. - -This is necessary as many manuals, especially for Lisp-family -languages, must document very long identifiers. On the other hand, -other manuals don't have this problems, and you may not wish to allow -a line break at the underscore in, for example, @code{SIZE_MAX}, or -even worse, after any of the four underscores in @code{__typeof__}. - -So Texinfo provides this command: - -@example -@@allowcodebreaks false -@end example - -@noindent to prevent @TeX{} from breaking at @samp{-} or @samp{_} within -@code{@@code}. You can go back to allowing such breaks with -@code{@@allowcodebreaks true}. Write these commands on lines by -themselves. - -These commands can be given anywhere in the document. For example, -you may have just one problematic paragraph where you need to turn off -the breaks, but want them in general, or vice versa. - -This command has no effect in Info, HTML, and other non-@TeX{} output. - - -@node w -@section @code{@@w}@{@var{text}@}: Prevent Line Breaks -@findex w @r{(prevent line break)} -@cindex Line breaks, preventing - -@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks -within @var{text}, for both @TeX{} and @command{makeinfo}. - -@cindex Non-breakable space, fixed -@cindex Unbreakable space, fixed -Thus, you can use @code{@@w} to produce a non-breakable space, fixed at -the width of a normal interword space: - -@example -@@w@{ @} @@w@{ @} @@w@{ @} indentation. -@end example - -@noindent produces: - -@display -@w{ } @w{ } @w{ } indentation. -@end display - -The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, -also will not stretch or shrink. Sometimes that is what you want, for -instance if you're doing manual indenting. However, usually you want -a normal interword space that does stretch and shrink (in the printed -output); see the @code{@@tie} command in the next section. - -@cindex Hyphenation, preventing -You can also 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. @command{makeinfo} does not ever hyphenate -words. - -@cindex Keyword expansion, preventing -@cindex Version control keywords, preventing expansion of -@cindex $Id expansion, preventing -You can also use @code{@@w} to avoid unwanted keyword expansion in -source control systems. For example, to literally write @t{@w{$}Id$} -in your document, use @code{@@w@{$@}Id$}. - - -@node tie -@section @code{@@tie@{@}}: Inserting an Unbreakable Space -@findex tie @r{(unbreakable interword space)} -@cindex Tied space -@cindex Non-breakable space, variable -@cindex Unbreakable space, variable - -The @code{@@tie@{@}} command produces a normal interword space at which -a line break may not occur. Always write it with following (empty) -braces, as usual for commands used within a paragraph. Here's an -example: - -@example -@@TeX@{@} was written by Donald E.@@tie@{@}Knuth. -@end example - -@noindent produces: - -@display -@TeX{} was written by Donald E.@tie{}Knuth. -@end display - -There are two important differences between @code{@@tie@{@}} and -@code{@@w@{@w{ }@}}: - -@itemize -@item -The space produced by @code{@@tie@{@}} will stretch and shrink slightly -along with the normal interword spaces in the paragraph; the space -produced by @code{@@w@{@w{ }@}} will not vary. - -@item -@code{@@tie@{@}} allows hyphenation of the surrounding words, while -@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical -reasons, namely that it produces an @samp{\hbox}). - -@end itemize - - -@node sp -@section @code{@@sp} @var{n}: Insert Blank Lines -@findex sp @r{(line spacing)} -@cindex Space, inserting vertical -@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 -@@sp 2 -@end example - -@noindent -generates two blank lines. - -The @code{@@sp} command is most often used in the title page.@refill - -@ignore -@c node br, page, sp, Breaks -@comment node-name, next, previous, up -@c section @code{@@br}: Generate Paragraph Breaks -@findex br @r{(paragraph breaks)} -@cindex Paragraph breaks -@cindex Breaks in a paragraph - -The @code{@@br} command forces a paragraph break. It inserts a blank -line. You can use the command within or at the end of a line. If -used within a line, the @code{@@br@{@}} command must be followed by -left and right braces (as shown here) to mark the end of the -command.@refill - -@need 700 -For example, - -@example -@group -This line @@br@{@}contains and is ended by paragraph breaks@@br -and is followed by another line. -@end group -@end example - -@noindent -produces - -@example -@group -This line - -contains and is ended by paragraph breaks - -and is followed by another line. -@end group -@end example - -The @code{@@br} command is seldom used. -@end ignore - - -@node page -@section @code{@@page}: Start a New Page -@cindex Page breaks -@findex page - -A line containing only @code{@@page} starts a new page in a printed -manual. The command has no effect on Info files since they are not -paginated. An @code{@@page} command is often used in the @code{@@titlepage} -section of a Texinfo file to start the copyright page. - - -@node group -@comment node-name, next, previous, up -@section @code{@@group}: Prevent Page Breaks -@cindex Group (hold text together vertically) -@cindex Holding text together vertically -@cindex Vertically holding text together -@findex group - -The @code{@@group} command (on a line by itself) is used inside an -@code{@@example} or similar construct to begin an unsplittable vertical -group, which will appear entirely on one page in the printed output. -The group is terminated by a line containing only @code{@@end group}. -These two lines produce no output of their own, and in the Info file -output they have no effect at all.@refill - -@c Once said that these environments -@c turn off vertical spacing between ``paragraphs''. -@c Also, quotation used to work, but doesn't in texinfo-2.72 -Although @code{@@group} would make sense conceptually in a wide -variety of contexts, its current implementation works reliably only -within @code{@@example} and variants, and within @code{@@display}, -@code{@@format}, @code{@@flushleft} and @code{@@flushright}. -@xref{Quotations and Examples}. (What all these commands have in -common is that each line of input produces a line of output.) In -other contexts, @code{@@group} can cause anomalous vertical -spacing.@refill - -@need 750 -This formatting requirement means that you should write: - -@example -@group -@@example -@@group -@dots{} -@@end group -@@end example -@end group -@end example - -@noindent -with the @code{@@group} and @code{@@end group} commands inside the -@code{@@example} and @code{@@end example} commands. - -The @code{@@group} command is most often used to hold an example -together on one page. In this Texinfo manual, more than 100 examples -contain text that is enclosed between @code{@@group} and @code{@@end -group}. - -If you forget to end a group, you may get strange and unfathomable -error messages when you run @TeX{}. This is because @TeX{} keeps -trying to put the rest of the Texinfo file onto the one page and does -not start to generate error messages until it has processed -considerable text. It is a good rule of thumb to look for a missing -@code{@@end group} if you get incomprehensible error messages in -@TeX{}.@refill - -@node need -@comment node-name, next, previous, up -@section @code{@@need @var{mils}}: Prevent Page Breaks -@cindex Need space at page bottom -@findex need - -A line containing only @code{@@need @var{n}} starts -a new page in a printed manual if fewer than @var{n} mils (thousandths -of an inch) remain on the current page. Do not use -braces around the argument @var{n}. The @code{@@need} command has no -effect on Info files since they are not paginated.@refill - -@need 800 -This paragraph is preceded by an @code{@@need} command that tells -@TeX{} to start a new page if fewer than 800 mils (eight-tenths -inch) remain on the page. It looks like this:@refill - -@example -@group -@@need 800 -This paragraph is preceded by @dots{} -@end group -@end example - -The @code{@@need} command is useful for preventing orphans (single -lines at the bottoms of printed pages).@refill - - -@node Definition Commands -@chapter Definition Commands -@cindex Definition commands - -The @code{@@deffn} command and the other @dfn{definition commands} -enable you to describe functions, variables, macros, commands, user -options, special forms and other such artifacts in a uniform -format.@refill - -In the Info file, a definition causes the entity -category---`Function', `Variable', or whatever---to appear at the -beginning of the first line of the definition, followed by the -entity's name and arguments. In the printed manual, the command -causes @TeX{} to print the entity's name and its arguments on the left -margin and print the category next to the right margin. In both -output formats, the body of the definition is indented. Also, the -name of the entity is entered into the appropriate index: -@code{@@deffn} enters the name into the index of functions, -@code{@@defvr} enters it into the index of variables, and so -on (@pxref{Predefined Indices}). - -A manual need not and should not contain more than one definition for -a given name. An appendix containing a summary should use -@code{@@table} rather than the definition commands.@refill - -@menu -* Def Cmd Template:: Writing descriptions using definition commands. -* Def Cmd Continuation Lines:: Continuing the heading over source lines. -* Optional Arguments:: Handling optional and repeated arguments. -* deffnx:: Group two or more `first' lines. -* Def Cmds in Detail:: Reference for all the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: An example. -@end menu - - -@node Def Cmd Template -@section The Template for a Definition -@cindex Definition template -@cindex Template for a definition - -The @code{@@deffn} command is used for definitions of entities that -resemble functions. To write a definition using the @code{@@deffn} -command, write the @code{@@deffn} command at the beginning of a line -and follow it on the same line by the category of the entity, the name -of the entity itself, and its arguments (if any). Then write the body -of the definition on succeeding lines. (You may embed examples in the -body.) Finally, end the definition with an @code{@@end deffn} command -written on a line of its own. - -The other definition commands follow the same format: a line with the -@code{@@def@dots{}} command and whatever arguments are appropriate for -that command; the body of the definition; and a corresponding -@code{@@end} line. - -The template for a definition looks like this: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@need 700 -@noindent -For example, - -@example -@group -@@deffn Command forward-word count -This command moves point forward @@var@{count@} words -(or backward if @@var@{count@} is negative). @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@quotation -@deffn Command forward-word count -This command moves point forward @var{count} words -(or backward if @var{count} is negative). @dots{} -@end deffn -@end quotation - -Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', -enclose it in braces. For example: - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@dots{} -@@end deffn -@end group -@end example - -@noindent -Otherwise, the second word will be mistaken for the name of the -entity. As a general rule, when any of the arguments in the heading -line @emph{except} the last one are more than one word, you need to -enclose them in braces. This may also be necessary if the text -contains commands, for example, @samp{@{declaraci@@'on@}} if you are -writing in Spanish. - -Some of the definition commands are more general than others. The -@code{@@deffn} command, for example, is the general definition command -for functions and the like---for entities that may take arguments. -When you use this command, you specify the category to which the -entity belongs. Three predefined, specialized variations -(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the -category for you: ``Function'', ``Macro'', and ``Special Form'' -respectively. (In Lisp, a special form is an entity much like a -function.) Similarly, the general @code{@@defvr} command is -accompanied by several specialized variations for describing -particular kinds of variables. - -@xref{Sample Function Definition}, for a detailed example of a -function definition, including the use of @code{@@example} inside the -definition. - -@cindex Macros in definition commands -Unfortunately, due to implementation difficulties, macros are not expanded -in @code{@@deffn} and all the other definition commands. - - -@node Def Cmd Continuation Lines -@section Definition Command Continuation Lines -@cindex Continuation lines in definition commands -@cindex Definition command headings, continuing -@cindex @samp{@@} as continuation in definition commands - -The heading line of a definition command can get very long. -Therefore, Texinfo has a special syntax allowing them to be continued -over multiple lines of the source file: a lone @samp{@@} at the end of -each line to be continued. Here's an example: - -@example -@@defun fn-name @@ - arg1 arg2 arg3 -This is the basic continued defun. -@@end defun -@end example - -@noindent produces: - -@defun fn-name @ - arg1 arg2 arg3 -This is the basic continued defun. -@end defun - -@noindent -As you can see, the continued lines are combined, as if they had been -typed on one source line. - -Although this example only shows a one-line continuation, -continuations may extend over any number of lines; simply put an -@code{@@} at the end of each line to be continued. - -The @code{@@} character does not have to be the last character on the -physical line: whitespace is allowed (and ignored) afterwards. - -@cindex Whitespace, collapsed around continuations -@cindex Collapsing whitespace around continuations -In general, any number of spaces or tabs around the @code{@@} -continuation character, both on the line with the @code{@@} and on the -continued line, are collapsed into a single space. There is one -exception: the Texinfo processors will not fully collapse whitespace -around a continuation inside braces. For example: - -@example -@@deffn @{Category @@ - Name@} @dots{} -@end example - -@noindent The output (not shown) has excess space between `Category' -and `Name'. In this case, simply elide any unwanted whitespace in -your input, or put the continuation @code{@@} outside braces. - -@code{@@} does not (currently) function as a continuation character in -@emph{any} other context. Ordinarily, @samp{@@} followed by a -whitespace character (space, tab, newline) produces a normal interword -space (@pxref{Multiple Spaces}). - - -@node Optional Arguments -@section Optional and Repeated Arguments -@cindex Optional and repeated arguments -@cindex Repeated and optional arguments -@cindex Arguments, repeated and optional -@cindex Syntax, optional & repeated arguments -@cindex Meta-syntactic chars for arguments - -Some entities take optional or repeated arguments, which may be -specified by a distinctive glyph that uses square brackets and -ellipses. For @w{example}, a special form often breaks its argument list -into separate arguments in more complicated ways than a -straightforward function. - -@c This is consistent with Emacs Lisp Reference manual -An argument enclosed within square brackets is optional. -Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more -arguments. Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. - -Here is the @code{@@defspec} line of an example of an imaginary -special form: - -@quotation -@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -@end defspec -@tex -\vskip \parskip -@end tex -@end quotation - -@noindent -In this example, the arguments @var{from} and @var{to} are optional, -but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the -form.@refill - -In a Texinfo source file, this @code{@@defspec} line is written like -this (except it would not be split over two lines, as it is in this -example).@refill - -@example -@group -@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} - [@@var@{inc@}]]) @@var@{body@}@@dots@{@} -@end group -@end example - -@noindent -The function is listed in the Command and Variable Index under -@samp{foobar}.@refill - - -@node deffnx -@section Two or More `First' Lines -@cindex Two `First' Lines for @code{@@deffn} -@cindex Grouping two definitions together -@cindex Definitions grouped together -@findex deffnx - -To create two or more `first' or header lines for a definition, follow -the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. -The @code{@@deffnx} command works exactly like @code{@@deffn} -except that it does not generate extra vertical white space between it -and the preceding line.@refill - -@need 1000 -For example, - -@example -@group -@@deffn @{Interactive Command@} isearch-forward -@@deffnx @{Interactive Command@} isearch-backward -These two search commands are similar except @dots{} -@@end deffn -@end group -@end example - -@noindent -produces - -@deffn {Interactive Command} isearch-forward -@deffnx {Interactive Command} isearch-backward -These two search commands are similar except @dots{} -@end deffn - -Each definition command has an `x' form: @code{@@defunx}, -@code{@@defvrx}, @code{@@deftypefunx}, etc. - -The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}). - - -@node Def Cmds in Detail -@section The Definition Commands - -Texinfo provides more than a dozen definition commands, all of which -are described in this section.@refill - -The definition commands automatically enter the name of the entity in -the appropriate index: for example, @code{@@deffn}, @code{@@defun}, -and @code{@@defmac} enter function names in the index of functions; -@code{@@defvr} and @code{@@defvar} enter variable names in the index -of variables.@refill - -Although the examples that follow mostly illustrate Lisp, the commands -can be used for other programming languages.@refill - -@menu -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Data Types:: The definition command for data types. -* Abstract Objects:: Commands for object-oriented programming. -@end menu - -@node Functions Commands -@subsection Functions and Similar Entities - -This section describes the commands for describing functions and similar -entities:@refill - -@table @code -@findex deffn -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -The @code{@@deffn} command is the general definition command for -functions, interactive commands, and similar entities that may take -arguments. You must choose a term to describe the category of entity -being defined; for example, ``Function'' could be used if the entity is -a function. The @code{@@deffn} command is written at the beginning of a -line and is followed on the same line by the category of entity being -described, the name of this particular entity, and its arguments, if -any. Terminate the definition with @code{@@end deffn} on a line of its -own.@refill - -@need 750 -For example, here is a definition: - -@example -@group -@@deffn Command forward-char nchars -Move point forward @@var@{nchars@} characters. -@@end deffn -@end group -@end example - -@noindent -This shows a rather terse definition for a ``command'' named -@code{forward-char} with one argument, @var{nchars}. - -@code{@@deffn} and prints argument names such as @var{nchars} in slanted -type in the printed output, because we think of these names as -metasyntactic variables---they stand for the actual argument values. -Within the text of the description, however, write an argument name -explicitly with @code{@@var} to refer to the value of the argument. -In the example above, we used @samp{@@var@{nchars@}} in this way. - -In the unusual case when an argument name contains @samp{--}, or -another character sequence which is treated specially -(@pxref{Conventions}), use @code{@@var} around the argument. This -causes the name to be printed in slanted typewriter, instead of the -regular slanted font, exactly as input. -@c except for ?` and !`, but we won't explain that. - -The template for @code{@@deffn} is: - -@example -@group -@@deffn @var{category} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end deffn -@end group -@end example - -@findex defun -@item @@defun @var{name} @var{arguments}@dots{} -The @code{@@defun} command is the definition command for functions. -@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}. -Terminate the definition with @code{@@end defun} on a line of its own. -Thus, the template is: - -@example -@group -@@defun @var{function-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example - -@findex defmac -@item @@defmac @var{name} @var{arguments}@dots{} -The @code{@@defmac} command is the definition command for macros. -@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and -works like @code{@@defun}. - -@findex defspec -@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}.) -@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} -@dots{}} and works like @code{@@defun}. -@end table - -All these commands create entries in the index of functions. - - -@node Variables Commands -@subsection Variables and Similar Entities - -Here are the commands for defining variables and similar -entities:@refill - -@table @code -@findex defvr -@item @@defvr @var{category} @var{name} -The @code{@@defvr} command is a general definition command for -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. - -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. -Otherwise, the second word will be mistaken for the name of the entity. -For example, - -@example -@group -@@defvr @{User Option@} fill-column -This buffer-local variable specifies -the maximum width of filled lines. -@dots{} -@@end defvr -@end group -@end example - -Terminate the definition with @code{@@end defvr} on a line of its -own.@refill - -The template is: - -@example -@group -@@defvr @var{category} @var{name} -@var{body-of-definition} -@@end defvr -@end group -@end example - -@code{@@defvr} creates an entry in the index of variables for @var{name}. - -@findex defvar -@item @@defvar @var{name} -The @code{@@defvar} command is the definition command for variables. -@code{@@defvar} is equivalent to @samp{@@defvr Variable -@dots{}}.@refill - -@need 750 -For example: - -@example -@group -@@defvar kill-ring -@dots{} -@@end defvar -@end group -@end example - -The template is: - -@example -@group -@@defvar @var{name} -@var{body-of-definition} -@@end defvar -@end group -@end example - -@code{@@defvar} creates an entry in the index of variables for -@var{name}.@refill - -@findex defopt -@item @@defopt @var{name} -@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 -Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}. It creates an entry -in the index of variables. -@end table - - -@node Typed Functions -@subsection Functions in Typed Languages - -The @code{@@deftypefn} command and its variations are for describing -functions in languages in which you must declare types of variables and -functions, such as C and C++. - -@table @code -@findex deftypefn -@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypefn} command is the general definition command for -functions and similar entities that may take arguments and that are -typed. The @code{@@deftypefn} command is written at the beginning of -a line and is followed on the same line by the category of entity -being described, the type of the returned value, the name of this -particular entity, and its arguments, if any.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@deftypefn @{Library Function@} int foobar - (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefn -@end group -@end example - -@need 1000 -@noindent -(where the text before the ``@dots{}'', shown above as two lines, would -actually be a single line in a real Texinfo file) produces the following -in Info: - -@smallexample -@group --- Library Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end smallexample -@iftex - -In a printed manual, it produces: - -@quotation -@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefn -@end quotation -@end iftex - -This means that @code{foobar} is a ``library function'' that returns an -@code{int}, and its arguments are @var{foo} (an @code{int}) and -@var{bar} (a @code{float}).@refill - -Since in typed languages, the actual names of the arguments are -typically scattered among data type names and keywords, Texinfo cannot -find them without help. You can either (a)@tie{}write everything -as straight text, and it will be printed in slanted type; (b)@tie{}use -@code{@@var} for the variable names, which will uppercase the -variable names in Info and use the slanted typewriter font in printed -output; (c)@tie{}use @code{@@var} for the variable names and -@code{@@code} for the type names and keywords, which will be dutifully -obeyed. - -The template for @code{@@deftypefn} is:@refill - -@example -@group -@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} -@var{body-of-description} -@@end deftypefn -@end group -@end example - -@noindent -Note that if the @var{category} or @var{data type} is more than one -word then it must be enclosed in braces to make it a single argument.@refill - -If you are describing a procedure in a language that has packages, -such as Ada, you might consider using @code{@@deftypefn} in a manner -somewhat contrary to the convention described in the preceding -paragraphs. For example: - -@example -@group -@@deftypefn stacks private push @@ - (@@var@{s@}:in out stack; @@ - @@var@{n@}:in integer) -@dots{} -@@end deftypefn -@end group -@end example - -@noindent -(The @code{@@deftypefn} arguments are shown using continuations -(@pxref{Def Cmd Continuation Lines}), but could be on a single line in -a real Texinfo file.) - -In this instance, the procedure is classified as belonging to the -package @code{stacks} rather than classified as a `procedure' and its -data type is described as @code{private}. (The name of the procedure -is @code{push}, and its arguments are @var{s} and @var{n}.)@refill - -@code{@@deftypefn} creates an entry in the index of functions for -@var{name}. - -@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} -@findex deftypefun -The @code{@@deftypefun} command is the specialized definition command -for functions in typed languages. The command is equivalent to -@samp{@@deftypefn Function @dots{}}. The template is: - -@example -@group -@@deftypefun @var{type} @var{name} @var{arguments}@dots{} -@var{body-of-description} -@@end deftypefun -@end group -@end example - -@code{@@deftypefun} creates an entry in the index of functions for -@var{name}. - -@end table - - -@node Typed Variables -@subsection Variables in Typed Languages - -Variables in typed languages are handled in a manner similar to -functions in typed languages. @xref{Typed Functions}. The general -definition command @code{@@deftypevr} corresponds to -@code{@@deftypefn} and the specialized definition command -@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill - -@table @code -@findex deftypevr -@item @@deftypevr @var{category} @var{data-type} @var{name} -The @code{@@deftypevr} command is the general definition command for -something like a variable in a typed language---an entity that records -a value. You must choose a term to describe the category of the -entity being defined; for example, ``Variable'' could be used if the -entity is a variable.@refill - -The @code{@@deftypevr} command is written at the beginning of a line -and is followed on the same line by the category of the entity -being described, the data type, and the name of this particular -entity.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevr @{Global Flag@} int enable -@dots{} -@@end deftypevr -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Global Flag: int enable -@dots{} -@end group -@end example -@iftex - -@noindent -and the following in a printed manual: - -@quotation -@deftypevr {Global Flag} int enable -@dots{} -@end deftypevr -@end quotation -@end iftex - -@need 800 -The template is: - -@example -@@deftypevr @var{category} @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevr -@end example - -@findex deftypevar -@item @@deftypevar @var{data-type} @var{name} -The @code{@@deftypevar} command is the specialized definition command -for variables in typed languages. @code{@@deftypevar} is equivalent -to @samp{@@deftypevr Variable @dots{}}. The template is: - -@example -@group -@@deftypevar @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevar -@end group -@end example -@end table - -These commands create entries in the index of variables. - -@node Data Types -@subsection Data Types - -Here is the command for data types:@refill - -@table @code -@findex deftp -@item @@deftp @var{category} @var{name} @var{attributes}@dots{} -The @code{@@deftp} command is the generic definition command for data -types. The command is written at the beginning of a line and is -followed on the same line by the category, by the name of the type -(which is a word like @code{int} or @code{float}), and then by names of -attributes of objects of that type. Thus, you could use this command -for describing @code{int} or @code{float}, in which case you could use -@code{data type} as the category. (A data type is a category of -certain objects for purposes of deciding which operations can be -performed on them.)@refill - -In Lisp, for example, @dfn{pair} names a particular data -type, and an object of that type has two slots called the -@sc{car} and the @sc{cdr}. Here is how you would write the first line -of a definition of @code{pair}.@refill - -@example -@group -@@deftp @{Data type@} pair car cdr -@dots{} -@@end deftp -@end group -@end example - -@need 950 -The template is: - -@example -@group -@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@var{body-of-definition} -@@end deftp -@end group -@end example - -@code{@@deftp} creates an entry in the index of data types. -@end table - - -@node Abstract Objects -@subsection Object-Oriented Programming - -@cindex Object-oriented programming - -Here are the commands for formatting descriptions about abstract -objects, such as are used in object-oriented programming. A class is -a defined type of abstract object. An instance of a class is a -particular object that has the type of the class. An instance -variable is a variable that belongs to the class but for which each -instance has its own value. - -@menu -* Variables: Object-Oriented Variables. -* Methods: Object-Oriented Methods. -@end menu - - -@node Object-Oriented Variables -@subsubsection Object-Oriented Variables - -@cindex Variables, object-oriented - -These commands allow you to define different sorts of variables in -object-oriented programming languages. - -@table @code -@item @@defcv @var{category} @var{class} @var{name} -@findex defcv -The @code{@@defcv} command is the general definition command for -variables associated with classes in object-oriented programming. The -@code{@@defcv} command is followed by three arguments: the category of -thing being defined, the class to which it belongs, and its -name. For instance: - -@example -@group -@@defcv @{Class Option@} Window border-pattern -@dots{} -@@end defcv -@end group -@end example - -@noindent produces: -@defcv {Class Option} Window border-pattern -@dots{} -@end defcv - -@code{@@defcv} creates an entry in the index of variables. - -@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} -@findex deftypecv -The @code{@@deftypecv} command is the definition command for typed -class variables in object-oriented programming. It is analogous to -@code{@@defcv} with the addition of the @var{data-type} parameter to -specify the type of the instance variable. Ordinarily, the data type -is a programming language construct that should be marked with -@code{@@code}. For instance: - -@example -@group -@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern -@dots{} -@@end deftypecv -@end group -@end example - -@noindent produces: - -@deftypecv {Class Option} Window @code{int} border-pattern -@dots{} -@end deftypecv - -@code{@@deftypecv} creates an entry in the index of variables. - -@item @@defivar @var{class} @var{name} -@findex defivar -The @code{@@defivar} command is the definition command for instance -variables in object-oriented programming. @code{@@defivar} is -equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For -instance: - -@example -@group -@@defivar Window border-pattern -@dots{} -@@end defivar -@end group -@end example - -@noindent produces: - -@defivar Window border-pattern -@dots{} -@end defivar - -@code{@@defivar} creates an entry in the index of variables. - -@item @@deftypeivar @var{class} @var{data-type} @var{name} -@findex deftypeivar -The @code{@@deftypeivar} command is the definition command for typed -instance variables in object-oriented programming. It is analogous to -@code{@@defivar} with the addition of the @var{data-type} parameter to -specify the type of the instance variable. Ordinarily, the data type -is a programming language construct that should be marked with -@code{@@code}. For instance: - -@example -@group -@@deftypeivar Window @@code@{int@} border-pattern -@dots{} -@@end deftypeivar -@end group -@end example - -@noindent produces: - -@deftypeivar Window @code{int} border-pattern -@dots{} -@end deftypeivar - -@code{@@deftypeivar} creates an entry in the index of variables. - -@end table - -@node Object-Oriented Methods -@subsubsection Object-Oriented Methods - -@cindex Methods, object-oriented - -These commands allow you to define different sorts of function-like -entities resembling methods in object-oriented programming languages. -These entities take arguments, as functions do, but are associated with -particular classes of objects. - -@table @code - -@findex defop -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defop} command is the general definition command for these -method-like entities. - -For example, some systems have constructs called @dfn{wrappers} that -are associated with classes as methods are, but that act more like -macros than like functions. You could use @code{@@defop Wrapper} to -describe one of these.@refill - -Sometimes it is useful to distinguish methods and @dfn{operations}. -You can think of an operation as the specification for a method. -Thus, a window system might specify that all window classes have a -method named @code{expose}; we would say that this window system -defines an @code{expose} operation on windows in general. Typically, -the operation has a name and also specifies the pattern of arguments; -all methods that implement the operation must accept the same -arguments, since applications that use the operation do so without -knowing which method will implement it.@refill - -Often it makes more sense to document operations than methods. For -example, window application developers need to know about the -@code{expose} operation, but need not be concerned with whether a -given class of windows has its own method to implement this operation. -To describe this operation, you would write:@refill - -@example -@@defop Operation windows expose -@end example - -The @code{@@defop} command is written at the beginning of a line and -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 - -The template is: -@example -@group -@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defop -@end group -@end example - -@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 -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 - -@noindent -For example: -@example -@group -@@defmethod @code{bar-class} bar-method argument -@dots{} -@@end defmethod -@end group -@end example - -@noindent -illustrates the definition for a method called @code{bar-method} of -the class @code{bar-class}. The method takes an argument. - -@code{@@defmethod} creates an entry in the index of functions. - -@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -@findex defmethod -The @code{@@deftypemethod} command is the definition command for methods -in object-oriented typed languages, such as C++ and Java. It is similar -to the @code{@@defmethod} command with the addition of the -@var{data-type} parameter to specify the return type of the method. -@code{@@deftypemethod} creates an entry in the index of functions. - -@end table - - -@node Def Cmd Conventions -@section Conventions for Writing Definitions -@cindex Definition conventions -@cindex Conventions for writing definitions - -When you write a definition using @code{@@deffn}, @code{@@defun}, or -one of the other definition commands, please take care to use -arguments that indicate the meaning, as with the @var{count} argument -to the @code{forward-word} function. Also, if the name of an argument -contains the name of a type, such as @var{integer}, take care that the -argument actually is of that type.@refill - - -@node Sample Function Definition -@section A Sample Function Definition -@cindex Function definitions -@cindex Command definitions -@cindex Macro definitions -@cindex Sample function definition - -A function definition uses the @code{@@defun} and @code{@@end defun} -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}. - -@quotation -@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 arguments to give to -@var{function}, rather than a single argument. We also say -that this list is @dfn{appended} to the other arguments. - -@code{apply} returns the result of calling @var{function}. -As with @code{funcall}, @var{function} must either be a Lisp -function or a primitive function; special forms and macros -do not make sense in @code{apply}. - -@example -(setq f 'list) - @result{} list -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @result{} 10 -(apply '+ '(1 2 3 4)) - @result{} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end example - -An interesting example of using @code{apply} is found in the description -of @code{mapcar}.@refill -@end defun -@end quotation - -@need 1200 -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 -arguments to give to @@var@{function@}, rather than a single -argument. We also say that this list is @@dfn@{appended@} -to the other arguments. -@end group - -@group -@@code@{apply@} returns the result of calling -@@var@{function@}. As with @@code@{funcall@}, -@@var@{function@} must either be a Lisp function or a -primitive function; special forms and macros do not make -sense in @@code@{apply@}. -@end group - -@group -@@example -(setq f 'list) - @@result@{@} list -(apply f 'x 'y 'z) -@@error@{@} Wrong type argument: listp, z -(apply '+ 1 2 '(3 4)) - @@result@{@} 10 -(apply '+ '(1 2 3 4)) - @@result@{@} 10 - -(apply 'append '((a b c) nil (x y z) nil)) - @@result@{@} (a b c x y z) -@@end example -@end group - -@group -An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}. -@@end defun -@end group -@end example - -@noindent -In this manual, this function is listed in the Command and Variable -Index under @code{apply}.@refill - -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 - -The @dfn{conditional commands} allow you to use different text for -different output formats, or for general conditions that you define. -For example, you can use them to specify different text for the -printed manual and the Info output. - -The conditional commands comprise the following categories. - -@itemize @bullet -@item -Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). - -@item -Commands specific to any output format @emph{other} than a given -one (not Info, not @TeX{}, @dots{}). - -@item -`Raw' formatter text for any output format, passed straight -through with no interpretation of @@-commands. - -@item -Format-independent variable substitutions, and testing if a variable -is set or clear. - -@end itemize - -@menu -* Conditional Commands:: Text for a given format. -* Conditional Not Commands:: Text for any format other than a given one. -* Raw Formatter Commands:: Using raw formatter commands. -* set clear value:: Variable tests and substitutions. -* Conditional Nesting:: Using conditionals inside conditionals. -@end menu - - -@node Conditional Commands -@section Conditional Commands - -Texinfo has an @code{@@if@var{format}} environment for each output -format, to allow conditional inclusion of text for a particular output -format. - -@findex ifinfo -@code{@@ifinfo} begins segments of text that should be ignored by -@TeX{} when it typesets the printed manual, and by @command{makeinfo} -when not producing Info output. The segment of text appears only in -the Info file and, for historical compatibility, the plain text -output. - -@findex ifdocbook -@findex ifhtml -@findex ifplaintext -@findex iftex -@findex ifxml -The environments for the other formats are analogous: - -@table @code -@item @@ifdocbook @dots{} @@end ifdocbook -Text to appear only in the Docbook output. - -@item @@ifhtml @dots{} @@end ifhtml -Text to appear only in the HTML output. - -@item @@ifplaintext @dots{} @@end ifplaintext -Text to appear only in the plain text output. - -@item @@iftex @dots{} @@end iftex -Text to appear only in the printed manual. - -@item @@ifxml @dots{} @@end ifxml -Text to appear only in the XML output. -@end table - -The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear -on lines by themselves in your source file. - -Here is an example showing all these conditionals: - -@example -@@iftex -This text will appear only in the printed manual. -@@end iftex -@@ifinfo -However, this text will appear only in Info and plain text. -@@end ifinfo -@@ifhtml -And this text will only appear in HTML. -@@end ifhtml -@@ifplaintext -Whereas this text will only appear in plain text. -@@end ifplaintext -@@ifxml -Notwithstanding that this will only appear in XML. -@@end ifxml -@@ifdocbook -Nevertheless, this will only appear in Docbook. -@@end ifdocbook -@end example - -@noindent -The preceding example produces the following line: - -@iftex -This text will appear only in the printed manual. -@end iftex -@ifinfo -However, this text will appear only in Info and plain text. -@end ifinfo -@ifhtml -And this text will only appear in HTML. -@end ifhtml -@ifplaintext -Whereas this text will only appear in plain text. -@end ifplaintext -@ifxml -Notwithstanding that this will only appear in XML. -@end ifxml -@ifdocbook -Nevertheless, this will only appear in Docbook. -@end ifdocbook - -@noindent -Notice that you only see one of the input lines, depending on which -version of the manual you are reading. - - -@node Conditional Not Commands -@section Conditional Not Commands -@findex ifnotdocbook -@findex ifnothtml -@findex ifnotinfo -@findex ifnotplaintext -@findex ifnottex -@findex ifnotxml - -You can specify text to be included in any output format @emph{other} -than a given one with the @code{@@ifnot@dots{}} environments: - -@example -@@ifnotdocbook @dots{} @@end ifnotdocbook -@@ifnothtml @dots{} @@end ifnothtml -@@ifnotinfo @dots{} @@end ifnotinfo -@@ifnotplaintext @dots{} @@end ifnotplaintext -@@ifnottex @dots{} @@end ifnottex -@@ifnotxml @dots{} @@end ifnotxml -@end example - -@noindent -The @code{@@ifnot@dots{}} command and the @code{@@end} command must -appear on lines by themselves in your actual source file. - -If the output file is being made in the given format, the -region is @emph{ignored}. Otherwise, it is included. - -There is one exception (for historical compatibility): -@code{@@ifnotinfo} text is omitted for both Info and plain text -output, not just Info. To specify text which appears only in Info and -not in plain text, use @code{@@ifnotplaintext}, like this: - -@example -@@ifinfo -@@ifnotplaintext -This will be in Info, but not plain text. -@@end ifnotplaintext -@@end ifinfo -@end example - -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}). - - -@node Raw Formatter Commands -@section Raw Formatter Commands -@cindex Raw formatter commands -@cindex @TeX{} commands, using ordinary -@cindex Ordinary @TeX{} commands, using -@cindex Commands using raw @TeX{} -@cindex Docbook, including raw -@cindex HTML, including raw -@cindex XML, including raw -@cindex Plain @TeX{} - -Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, -you can embed some raw @TeX{} commands. The Texinfo processors will -ignore such a region unless @TeX{} output is being produced. You can -write the @TeX{} commands as you would write them in a normal @TeX{} -file, except that you must replace the @samp{\} used by @TeX{} with an -@samp{@@}. For example, in the @code{@@titlepage} section of a -Texinfo file, you can use the @TeX{} command @code{@@vskip} to format -the copyright page. (The @code{@@titlepage} command causes Info to -ignore the region automatically, as it does with the @code{@@iftex} -command.) - -However, most features of plain @TeX{} will not work within -@code{@@iftex}, as they are overridden by Texinfo features. The -purpose of @code{@@iftex} is to provide conditional processing for the -Texinfo source, not provide access to underlying formatting features. - -@findex tex -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. All plain @TeX{} commands and category codes are -restored within an @code{@@tex} region. The sole exception is that the -@code{@@} character still introduces a command, so that @code{@@end tex} -can be recognized properly. As with @code{@@iftex}, Texinfo -processors will ignore such a region unless @TeX{} output is being produced. - -@findex \gdef @r{within @code{@@tex}} -In complex cases, you may wish to define new @TeX{} macros within -@code{@@tex}. You must use @code{\gdef} to do this, not @code{\def}, -because @code{@@tex} regions are processed in a @TeX{} group. - -@cindex Mathematical expressions -As an example, here is a mathematical expression written in plain @TeX{}: - -@example -@@tex -$$ \chi^2 = \sum_@{i=1@}^N - \left (y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@@end tex -@end example - -@noindent -The output of this example will appear only in a printed manual. If -you are reading this in Info, you will not see the equation that appears -in the printed manual. -@iftex -In a printed manual, the above expression looks like -this: -@end iftex - -@tex -$$ \chi^2 = \sum_{i=1}^N - \left(y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@end tex - -@findex ifhtml -@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. - -@findex ifxml -@findex xml -Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit -a region to be included in XML output only, and @code{@@xml @dots{} -@@end xml} for a region of raw XML. - -@findex ifdocbook -@findex docbook -Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} -to delimit a region to be included in Docbook output only, and -@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. - -In all cases, the exception to the raw processing is that @code{@@} is -still an escape character, so the @code{@@end} command can be -recognized. - - -@node set clear value -@section @code{@@set}, @code{@@clear}, and @code{@@value} - -You can direct the Texinfo formatting commands to format or ignore parts -of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, -and @code{@@ifclear} commands. - -Here are brief descriptions of these commands, see the following -sections for more details: - -@table @code -@item @@set @var{flag} [@var{value}] -Set the variable @var{flag}, to the optional @var{value} if specified. - -@item @@clear @var{flag} -Undefine the variable @var{flag}, whether or not it was previously defined. - -@item @@ifset @var{flag} -If @var{flag} is set, text through the next @code{@@end ifset} command -is formatted. If @var{flag} is clear, text through the following -@code{@@end ifset} command is ignored. - -@item @@ifclear @var{flag} -If @var{flag} is set, text through the next @code{@@end ifclear} command -is ignored. If @var{flag} is clear, text through the following -@code{@@end ifclear} command is formatted. -@end table - -@menu -* set value:: Expand a flag variable to a string. -* ifset ifclear:: Format a region if a flag is set. -* value Example:: An easy way to update edition information. -@end menu - - -@node set value -@subsection @code{@@set} and @code{@@value} -@findex set -@findex value -@findex clear - -You use the @code{@@set} command to specify a value for a flag, which -is later expanded by the @code{@@value} command. - -A @dfn{flag} (aka @dfn{variable}) is an identifier. It is best to 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 the remainder of the input line, and can contain anything. - -Write the @code{@@set} command like this: - -@example -@@set foo This is a string. -@end example - -@noindent -This sets the value of the flag @code{foo} to ``This is a string.''. - -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 this: - -@example -@group -@@value@{foo@} -@exdent @r{to this:} -This is a string. -@end group -@end example - -You can write an @code{@@value} command within a paragraph; but you -must write an @code{@@set} command on a line of its own. - -If you write the @code{@@set} command like this: - -@example -@@set foo -@end example - -@noindent -without specifying a string, the value of @code{foo} is the empty string. - -If you clear a previously set flag with @code{@@clear @var{flag}}, a -subsequent @code{@@value@{flag@}} command will report an error. - -For example, if you set @code{foo} as follows: - -@example -@@set howmuch very, very, very -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{howmuch@} wet day. -@exdent @r{into} -It is a very, very, very wet day. -@end group -@end example - -If you write - -@example -@@clear howmuch -@end example - -@noindent -then the formatters transform - -@example -@group -It is a @@value@{howmuch@} wet day. -@exdent @r{into} -It is a @{No value for "howmuch"@} wet day. -@end group -@end example - - -@node ifset ifclear -@subsection @code{@@ifset} and @code{@@ifclear} - -@findex ifset -When a @var{flag} is set, the Texinfo formatting commands format text -between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end -ifset} commands. When the @var{flag} is cleared, the Texinfo formatting -commands do @emph{not} format the text. @code{@@ifclear} operates -analogously. - -Write the conditionally formatted text between @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, like this: - -@example -@group -@@ifset @var{flag} -@var{conditional-text} -@@end ifset -@end group -@end example - -For example, you can create one document that has two variants, such as -a manual for a `large' and `small' model: - -@cindex Shrubbery -@example -You can use this machine to dig up shrubs -without hurting them. - -@@set large - -@@ifset large -It can also dig up fully grown trees. -@@end ifset - -Remember to replant promptly @dots{} -@end example - -@noindent -In the example, the formatting commands will format the text between -@code{@@ifset large} and @code{@@end ifset} because the @code{large} -flag is set. - -When @var{flag} is cleared, the Texinfo formatting commands do -@emph{not} format the text between @code{@@ifset @var{flag}} and -@code{@@end ifset}; that text is ignored and does not appear in either -printed or Info output. - -For example, if you clear the flag of the preceding example by writing -an @code{@@clear large} command after the @code{@@set large} command -(but before the conditional text), then the Texinfo formatting commands -ignore the text between the @code{@@ifset large} and @code{@@end ifset} -commands. In the formatted output, that text does not appear; in both -printed and Info output, you see only the lines that say, ``You can use -this machine to dig up shrubs without hurting them. Remember to replant -promptly @dots{}''. - -@findex ifclear -If a flag is cleared with an @code{@@clear @var{flag}} command, then -the formatting commands format text between subsequent pairs of -@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag -is set with @code{@@set @var{flag}}, then the formatting commands do -@emph{not} format text between an @code{@@ifclear} and an @code{@@end -ifclear} command; rather, they ignore that text. An @code{@@ifclear} -command looks like this: - -@example -@@ifclear @var{flag} -@end example - - -@node value Example -@subsection @code{@@value} Example - -You can use the @code{@@value} command to minimize the number of -places you need to change when you record an update to a manual. -@xref{GNU Sample Texts}, for the full text of an example of using this -to work with Automake distributions. - -This example is adapted from @ref{Top,, Overview, make, The GNU Make -Manual}. - -@enumerate -@item -Set the flags: - -@example -@group -@@set EDITION 0.35 Beta -@@set VERSION 3.63 Beta -@@set UPDATED 14 August 1992 -@@set UPDATE-MONTH August 1992 -@end group -@end example - -@item -Write text for the @code{@@copying} section (@pxref{copying}): - -@example -@group -@@copying -This is Edition @@value@{EDITION@}, -last updated @@value@{UPDATED@}, -of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, version @@value@{VERSION@}. - -Copyright @dots{} - -Permission is granted @dots{} -@@end copying -@end group -@end example - -@item -Write text for the title page, for people reading the printed manual: - -@example -@group -@@titlepage -@@title GNU Make -@@subtitle A Program for Directing Recompilation -@@subtitle Edition @@value@{EDITION@}, @dots{} -@@subtitle @@value@{UPDATE-MONTH@} -@@page -@@insertcopying -@dots{} -@@end titlepage -@end group -@end example - -@noindent -(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 -Write text for the Top node, for people reading the Info file: - -@example -@group -@@ifnottex -@@node Top -@@top Make - -@@insertcopying -@dots{} -@@end ifnottex -@end group -@end example - -After you format the manual, the @code{@@value} constructs have been -expanded, so the output contains text like this: - -@example -@group -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, you change only the values of the flags; you -do not need to edit the three sections. - - -@node Conditional Nesting -@section Conditional Nesting -@cindex Conditionals, nested -@cindex Nesting conditionals - -Conditionals can be nested; however, the details are a little tricky. -The difficulty comes with failing conditionals, such as -@code{@@ifhtml} when HTML is not being produced, where the included -text is to be ignored. However, it is not to be @emph{completely} -ignored, since it is useful to have one @code{@@ifset} inside another, -for example---that is a way to include text only if two conditions are -met. Here's an example: - -@example -@@ifset somevar -@@ifset anothervar -Both somevar and anothervar are set. -@@end ifset -@@ifclear anothervar -Somevar is set, anothervar is not. -@@end ifclear -@@end ifset -@end example - -Technically, Texinfo requires that for a failing conditional, the -ignored text must be properly nested with respect to that failing -conditional. Unfortunately, it's not always feasible to check that -@emph{all} conditionals are properly nested, because then the -processors could have to fully interpret the ignored text, which -defeats the purpose of the command. Here's an example illustrating -these rules: - -@example -@@ifset a -@@ifset b -@@ifclear ok - ok, ignored -@@end junky - ok, ignored -@@end ifset -@@c WRONG - missing @@end ifset. -@end example - -Finally, as mentioned above, all conditional commands must be on lines -by themselves, with no text (even spaces) before or after. Otherwise, -the processors cannot reliably determine which commands to consider -for nesting purposes. - - -@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{ll}[_@var{cc}]}: Set the Document Language - -@findex documentlanguage -@cindex Language, declaring -@cindex Locale, declaring -@cindex Document language, declaring - -The @code{@@documentlanguage} command declares the current document -locale. Write it on a line by itself, near the beginning of the -file, but after @code{@@setfilename} -(@pxref{setfilename,,@code{@@setfilename}}). - -Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following -the command name, optionally followed by a two-letter ISO@tie{}3166 -two-letter country code (@var{cc}). 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_US} for US English. - -As with GNU Gettext (@pxref{Top,,,gettext, Gettext}), if the country -code is omitted, the main dialect is assumed where possible. For -example, @code{de} is equivalent to @code{de_DE} (German as spoken in -Germany). - -@cindex Document strings, translation of -For Info and other online output, this command changes the translation -of various @dfn{document strings} such as ``see'' in cross-references -(@pxref{Cross References}), ``Function' in defuns (@pxref{Definition -Commands}), and so on. Some strings, such as ``Node:'', ``Next:'', -``Menu:'', etc., are keywords in Info output, so are not translated -there; they are translated in other output formats. - -@cindex @file{txi-@var{cc}.tex} -For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to -be read (if it exists). If @code{@@setdocumentlanguage} argument -contains the optional @samp{_@var{cc}} suffix, this is tried first. -For example, with @code{@@setdocumentlanguage de_DE}, @TeX{} first -looks for @file{txi-de_DE.tex}, then @file{txi-de.tex}. - -Such a @file{txi-*} file is intended to redefine the various English -words used in @TeX{} output, such as `Chapter', `See', and so on. We -are aware that individual words like these cannot always be translated -in isolation, and that a very different strategy would be required for -ideographic (among other) scripts. Help in improving Texinfo's -language support is welcome. - -@cindex Hyphenation patterns, language-dependent -It would also be desirable for this command to also change @TeX{}'s -ideas of the current hyphenation patterns (via the @TeX{} primitive -@code{\language}), but this is unfortunately not currently -implemented. - -In September 2006, the W3C Internationalization Activity released a -new recommendation for specifying tags identifying language: -@example -@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt} -@end example -When Gettext supports this new scheme, Texinfo will too. - -@cindex ISO 639-2 language codes -@cindex ISO 3166 country codes -@cindex Language codes -@cindex Country codes -Since the lists of language codes and country codes are quite dynamic, -we don't attempt to list them here. The valid language codes are on -the official home page for ISO@tie{}639, -@url{http://www.loc.gov/standards/iso639-2/}. The country codes and -the official web site for ISO@tie{}3166 can be found via -@url{http://en.wikipedia.org/wiki/ISO_3166}. - - -@node documentencoding -@section @code{@@documentencoding @var{enc}}: Set Input Encoding - -@findex documentencoding -@cindex Encoding, declaring -@cindex Input encoding, declaring -@cindex Character set, 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, near the beginning of the file but after -@code{@@setfilename} (@pxref{setfilename,,@code{@@setfilename}}). - -At present, Texinfo supports only these encodings: - -@table @code -@item US-ASCII -This has no particular effect, but it's included for completeness. - -@itemx UTF-8 -The vast global character encoding, expressed in 8-bit bytes. -The Texinfo processors have no deep knowledge of Unicode; for the most -part, they just pass along the input they are given to the output. - -@itemx ISO-8859-1 -@itemx ISO-8859-15 -@item ISO-8859-2 -These specify the standard encodings for Western European (the first -two) and Eastern European languages (the third), respectively. ISO -8859-15 replaces some little-used characters from 8859-1 (e.g., -precomposed fractions) with more commonly needed ones, such as the -Euro symbol (@euro{}). - -A full description of the encodings is beyond our scope here; -one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. - -@item koi8-r -This is the commonly used encoding for the Russian language. - -@item koi8-u -This is the commonly used encoding for the Ukrainian language. - -@end table - -Specifying an encoding @var{enc} has the following effects: - -@opindex --enable-encoding -@cindex Local Variables: section, for encoding -@cindex Info output, and encoding -In Info output, unless the option @option{--disable-encoding} is given -to @command{makeinfo}, a so-called `Local Variables' section -(@pxref{File Variables,,,emacs,The GNU Emacs Manual}) is output -including @var{enc}. This allows Info readers to set the encoding -appropriately. - -@example -Local Variables: -coding: @var{enc} -End: -@end example - -Also, in Info and plain text output (barring -@option{--disable-encoding}), accent constructs and special -characters, such as @code{@@'e}, are output as the actual 8-bit -character in the given encoding. - -@cindex HTML output, and encodings -@cindex @code{http-equiv}, and charset specification -@cindex @code{<meta>} HTML tag, and charset specification -In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} -section of the HTML, that specifies @var{enc}. Web servers and -browsers cooperate to use this information so the correct encoding is -used to display the page, if supported by the system. - -@example -<meta http-equiv="Content-Type" content="text/html; - charset=@var{enc}"> -@end example - -In split HTML output, if @option{--transliterate-file-names} is -given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML -files are formed by transliteration of the corresponding node names, -using the specified encoding. - -In XML and Docbook output, the given document encoding is written in -the output file as usual with those formats. - -In @TeX{} output, the characters which are supported in the standard -Computer Modern fonts are output accordingly. (For example, this -means using constructed accents rather than precomposed glyphs.) -Using a missing character generates a warning message, as does -specifying an unimplemented encoding. - - -@node Defining New Texinfo Commands -@chapter 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 - -@menu -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. -@end menu - - -@node Defining Macros -@section Defining Macros -@cindex Defining macros -@cindex Macro definitions - -@findex macro -You use the Texinfo @code{@@macro} command to define a macro, like this: - -@example -@@macro @var{macroname}@{@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). - -@cindex Macro names, valid characters in -@cindex Names of macros, valid characters of -For a macro to work consistently with @TeX{}, @var{macroname} must -consist entirely of letters: no digits, hyphens, underscores, or other -special characters. So, we recommend using only letters. However, -@command{makeinfo} will accept anything except @samp{@{@}_^=}; -@samp{_} and @samp{^} are excluded so that macros can be called in -@code{@@math} mode without a following space -(@pxref{math,,@code{@@math}}). - -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 -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 @{arg@} -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. - -@findex unmacro -@cindex Macros, undefining -@cindex Undefining macros -You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. -It is not an error to undefine a macro that is already undefined. -For example: - -@example -@@unmacro foo -@end example - - -@node Invoking 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{}@} -@end example - -@noindent and the result will be just as if you typed the body of -@var{macroname} at that spot. For example: - -@example -@@macro foo @{p, q@} -Together: \p\ & \q\. -@@end macro -@@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 - -@cindex Comma, in macro arguments -Passing strings containing commas as macro arguments requires special -care, since they should be properly @dfn{quoted} to prevent -@command{makeinfo} from confusing them with argument separators. To -manually quote a comma, prepend it with a backslash character, like -this: @code{\,}. Alternatively, use the @code{@@comma} command -(@pxref{Inserting a Comma}). However, to facilitate use of macros, -@command{makeinfo} implements a set of rules called @dfn{automatic -quoting}: - -@enumerate 1 -@item If a macro takes only one argument, all commas in its invocation -are quoted by default. For example: - -@example -@group -@@macro FIXME@{text@} -@@strong@{FIXME: \text\@} -@@end macro - -@@FIXME@{A nice feature, though it can be dangerous.@} -@end group -@end example - -@noindent -will produce the following output - -@example -@strong{FIXME: A nice feature, though it can be dangerous.} -@end example - -And indeed, it can. Namely, @command{makeinfo} -does not control number of arguments passed to one-argument -macros, so be careful when you invoke them. - -@item If a macro invocation includes another command (including a -recursive invocation of itself), any commas in the nested command -invocation(s) are quoted by default. For example, in - -@example -@@say@{@@strong@{Yes, I do@}, person one@} -@end example - -the comma after @samp{Yes} is implicitly quoted. Here's another -example, with a recursive macro: - -@example -@group -@@rmacro cat@{a,b@} -\a\\b\ -@@end rmacro - -@@cat@{@@cat@{foo, bar@}, baz@} -@end group -@end example - -@noindent -will produce the string @samp{foobarbaz}. - -@item Otherwise, a comma should be explicitly quoted, as above, to be -treated as a part of an argument. -@end enumerate - -@cindex Braces, in macro arguments -Other characters that need to be quoted in macro arguments are -curly braces and backslash. For example - -@example -@@@var{macname} @{\\\@{\@}\,@} -@end example - -@noindent -will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macname}. However, commas in parameters, even -if escaped by a backslash, might cause trouble in @TeX{}. - -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: - -@display -Twice: a,b & a,b. -@end display - - -@node Macro Details -@section Macro Details and Caveats -@cindex Macro details -@cindex Details of macro usage -@cindex Caveats for macro usage - -Due to unavoidable limitations, certain macro-related constructs cause -problems with @TeX{}. If you get macro-related errors when producing -the printed version of a manual, try expanding the macros with -@command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E} -option (@pxref{Format with texi2dvi}). - -@itemize @bullet -@item -As mentioned earlier, macro names must consist entirely of letters. - -@item -It is not advisable to redefine any @TeX{} primitive, plain, or -Texinfo command name as a macro. Unfortunately this is a very large -set of names, and the possible resulting errors are unpredictable. - -@item -All macros are expanded inside at least one @TeX{} group. This means -that @code{@@set} and other such commands have no effect inside a -macro. - -@item -Commas in macro arguments, even if escaped by a backslash, don't -always work. - -@item -Macro arguments cannot cross lines. - -@item -It is (usually) best to avoid comments inside macro definitions, but -see the next item. - -@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. In general, -the interaction of newlines in the macro definitions and invocations -depends on the precise commands and context. You may be able to work -around some problems with judicious use of @code{@@c}. Suppose you -define a macro that is always intended to be used on a line by itself: - -@example -@@macro linemac -@@cindex whatever -@@c -@@end macro -... -foo -@@linemac -bar -@end example - -Without the @code{@@c}, there will be an unwanted blank line between -the @samp{@@cindex whatever} and the @samp{bar} (one newline comes -from the macro definition, one from after the invocation), causing a -paragraph break. - -On the other hand, you wouldn't want the @code{@@c} if the macro was -sometimes invoked in the middle of a line (the text after the -invocation would be treated as a comment). - -@item -In general, you can't arbitrarily substitute a macro call for Texinfo -command arguments, even when the text is the same. It might work with -some commands, it fails with others. Best not to do it at all. For -instance, this fails: - -@example -@@macro offmacro -off -@@end macro -@@headings @@offmacro -@end example - -@noindent -You would expect this to be equivalent to @code{@@headings off}, but -for @TeX{}nical reasons, it fails with a mysterious error message -(@code{Paragraph ended before @@headings was complete}). - -@item -Macros cannot define macros in the natural way. To do this, you must -use conditionals and raw @TeX{}. For example: - -@example -@@ifnottex -@@macro ctor @{name, arg@} -@@macro \name\ -something involving \arg\ somehow -@@end macro -@@end macro -@@end ifnottex -@@tex -\gdef\ctor#1@{\ctorx#1,@} -\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} -@@end tex -@end example - -@end itemize - -The @command{makeinfo} implementation also has limitations: - -@itemize -@item -@code{@@verbatim} and macros do not mix; for instance, you can't start -a verbatim block inside a macro and end it outside. -(@xref{verbatim}.) Starting any environment inside a macro and ending -it outside may or may not work, for that matter. - -@item -Macros that completely define macros are ok, but it's not possible to -have incorrectly nested macro definitions. That is, @code{@@macro} -and @code{@@end macro} (likewise for @code{@@rmacro}) must be -correctly paired. For example, you cannot start a macro definition -within a macro, and then end the nested definition outside the macro. - -@item -@code{@@rmacro} is a kludge. - -@end itemize - -One more limitation is common to both implementations: white space is -ignored at the beginnings of lines. - -Future major revisions of Texinfo may ease some of these limitations -(by introducing a new macro syntax). - - -@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 as aliases, 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. - -It is not advisable to redefine any @TeX{} primitive, plain, or -Texinfo command name as an alias. Unfortunately this is a very large -set of names, and the possible resulting errors are completely random. - - -@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 predefined 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 - -@example -@@iftex -@@global@@let@@phoo=@@i -@@end iftex -@end example - -@noindent -to define @code{@@phoo} as a command that causes @TeX{} to typeset the -argument to @code{@@phoo} in italics. - -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}. - -@findex headword -Here is another example: write - -@example -@@definfoenclose headword, , : -@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}. - -@samp{@@definfoenclose} definitions must not be recursive, directly or -indirectly. - - -@node Hardcopy -@chapter Formatting and Printing Hardcopy -@cindex Format and print hardcopy -@cindex Printing hardcopy -@cindex Hardcopy, printing it -@cindex Making a printed manual -@cindex Sorting indices -@cindex Indices, sorting -@cindex @TeX{} index sorting -@pindex texindex - -There are three major shell commands for making a printed manual from a -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. - -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. - -@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. -* 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{}. -* 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 A4 or A5 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. -* Obtaining TeX:: How to Obtain @TeX{}. -@end menu - -@node Use TeX -@section Use @TeX{} - -The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, if used correctly, -does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain -@TeX{}}, for information on how to obtain @TeX{}.) - -The standalone @code{makeinfo} program and Emacs functions -@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}). - - -@node Format with tex/texindex -@section Format with @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 - -You can format the Texinfo file with the shell command @code{tex} -followed by the name of the Texinfo file. For example: - -@example -tex foo.texi -@end example - -@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). - -@pindex texindex -The @code{tex} formatting command itself does not sort the indices; it -writes an output file of unsorted index data. To generate a printed -index after running the @command{tex} command, you first need a sorted -index to work from. The @command{texindex} command sorts indices. -(The source file @file{texindex.c} comes as part of the standard -Texinfo distribution, among other places.) (@command{texi2dvi} runs -@command{tex} and @command{texindex} as necessary.) - -@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, -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}. - -@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: - -@example -texindex foo.?? -@end example - -@noindent -This command will run @code{texindex} on all the unsorted index files, -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.) - -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 -(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the -raw index output file. - -After you have sorted the indices, you need to rerun @code{tex} on the -Texinfo file. This regenerates the DVI file, 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: - -@enumerate -@item -Run @code{tex} on your Texinfo file. This generates a DVI file (with -undefined cross-references and no indices), and the raw index files -(with two letter extensions). - -@item -Run @code{texindex} on the raw index files. This creates the -corresponding sorted index files (with three letter extensions). - -@item -Run @code{tex} again on your Texinfo file. This regenerates the DVI -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}). - -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 - -@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} -@pindex texi2dvi @r{(shell script)} - -The @code{texi2dvi} command automatically runs both @TeX{} and -@command{texindex} as many times as necessary to produce a DVI file -with sorted indices and all cross-references resolved. It is -therefore simpler than manually executing the -@code{tex}---@code{texindex}---@code{tex}---@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): - -@example -prompt$ @kbd{texi2dvi foo.texi} -@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. - -@opindex --command @r{(@command{texi2dvi})} -One useful option to @code{texi2dvi} is @samp{--command=@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{@@pagesizes} -(@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{}}). - -@opindex --pdf @r{(@command{texi2dvi})} -With the @option{--pdf} option, @command{texi2dvi} produces PDF output -instead of DVI (@pxref{PDF Output}), by running @command{pdftex} -instead of @command{tex}. Alternatively, the command -@command{texi2pdf} is an abbreviation for running @samp{texi2dvi ---pdf}. The command @command{pdftexi2dvi} is also supported as a -convenience to AUC-@TeX{} users, since the latter merely prepends -@samp{pdf} to DVI producing tools to have PDF producing tools. - -@cindex @LaTeX{}, processing with @command{texi2dvi} -@command{texi2dvi} can also be used to process @LaTeX{} files; simply -run @samp{texi2dvi filename.ext}. - -@opindex --language @r{(@command{texi2dvi})} -Normally @command{texi2dvi} is able to guess the input file language -by its contents and file name suffix. If, however, it fails to do so -you can specify the input language using -@option{--language=@var{lang}} command line option, where @var{lang} -is either @samp{latex} or @samp{texinfo}. - -@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if -they are available; these extended versions of @TeX{} are not -required, and the DVI (or PDF) output is identical, but they simplify -the @TeX{} programming in some cases, and provide additional tracing -information when debugging @file{texinfo.tex}. - -@opindex --translate-file @r{(@command{texi2dvi})} -Several options are provided for handling documents, written in -character sets other than ASCII. The -@option{--translate-file=@var{file}} option instructs -@command{texi2dv} to translate input into internal @TeX{} character -set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX -files, TCX files: Character translations, web2c, Web2c: A @TeX{} -implementation}). - -@opindex --recode @r{(@command{texi2dvi})} -The options @option{--recode} and @option{--recode-from=@var{enc}} -allow conversion of an input document before running @TeX{}. The -@option{--recode} option recodes the document from encoding specified -by @samp{@@documentencoding} command -(@pxref{documentencoding,,@code{documentencoding}}) to plain 7-bit -@samp{texinfo} encoding. - -@opindex --recode-from @r{(@command{texi2dvi})} -The option @option{--recode-from=@var{enc}} recodes the document from -@var{enc} encoding to the encoding specified by -@samp{@@documentencoding}. This is useful, for example, if the -document is written in @samp{UTF-8} encoding and an equivalent 8-bit -encoding is supported by @command{makeinfo}. - -Both @option{--recode} and @option{--recode-from=@var{enc}} use -@command{recode} utility to perform the conversion. If -@command{recode} fails to process the file, @command{texi2dvi} prints -a warning and continues using unmodified input file. - -For a list of other options, run @samp{texi2dvi --help}. - - -@node Print with lpr -@section Shell Print Using @code{lpr -d} -@pindex lpr @r{(DVI print command)} - -The precise command to print a DVI file depends on your system -installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr --d foo.dvi}. - -For example, the following commands will (perhaps) suffice to sort the -indices, format, and print the @cite{Bison Manual}: - -@example -@group -tex bison.texinfo -texindex bison.?? -tex bison.texinfo -lpr -d bison.dvi -@end group -@end example - -@noindent -(Remember that the shell commands may be different at your site; but -these are commonly used versions.) - -Using the @code{texi2dvi} shell script (see the previous section): - -@example -@group -texi2dvi bison.texinfo -lpr -d bison.dvi -# or perhaps dvips bison.dvi -o -@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{Invoking Dvips,,, 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 -@section From an Emacs Shell -@cindex Print, format from Emacs shell -@cindex Format, print from Emacs shell -@cindex Shell, format, print from -@cindex Emacs shell, format, print from -@cindex GNU Emacs shell, format, print from - -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. - -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 -on a slow machine, this can be very convenient.@refill - -You can also use @code{texi2dvi} from an Emacs shell. For example, -here is how to use @code{texi2dvi} to format and print @cite{Using and -Porting GNU CC} from a shell within Emacs: - -@example -@group -texi2dvi gcc.texinfo -lpr -d gcc.dvi -@end group -@end example - -See the next section for more information about formatting -and printing in Texinfo mode. - - -@node Texinfo Mode Printing -@section Formatting and Printing in Texinfo Mode -@cindex Region printing in Texinfo mode -@cindex Format and print in Texinfo mode -@cindex Print and format in Texinfo mode - -Texinfo mode provides several predefined key commands for @TeX{} -formatting and printing. These include commands for sorting indices, -looking at the printer queue, killing the formatting job, and -recentering the display of the buffer in which the operations -occur.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -Run @code{texi2dvi} on the current buffer.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -Run @TeX{} on the current region.@refill - -@item C-c C-t C-i -@itemx M-x texinfo-texindex -Sort the indices of a Texinfo file formatted with -@code{texinfo-tex-region}.@refill - -@item C-c C-t C-p -@itemx M-x texinfo-tex-print -Print a DVI file that was made with @code{texinfo-tex-region} or -@code{texinfo-tex-buffer}.@refill - -@item C-c C-t C-q -@itemx M-x tex-show-print-queue -Show the print queue.@refill - -@item C-c C-t C-d -@itemx M-x texinfo-delete-from-print-queue -Delete a job from the print queue; you will be prompted for the job -number shown by a preceding @kbd{C-c C-t C-q} command -(@code{texinfo-show-tex-print-queue}).@refill - -@item C-c C-t C-k -@itemx M-x tex-kill-job -Kill the currently running @TeX{} job started by either -@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other -process running in the Texinfo shell buffer.@refill - -@item C-c C-t C-x -@itemx M-x texinfo-quit-job -Quit a @TeX{} formatting job that has stopped because of an error by -sending an @key{x} to it. When you do this, @TeX{} preserves a record -of what it did in a @file{.log} file.@refill - -@item C-c C-t C-l -@itemx M-x tex-recenter-output-buffer -Redisplay the shell buffer in which the @TeX{} printing and formatting -commands are run to show its most recent output.@refill -@end table - -@need 1000 -Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right):@refill - -@example -@group -C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} -C-c C-t C-p @r{Print the DVI file.} -C-c C-t C-q @r{Display the printer queue.} -@end group -@end example - -The Texinfo mode @TeX{} formatting commands start a subshell in Emacs -called the @file{*tex-shell*}. The @code{texinfo-tex-command}, -@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} -commands are all run in this shell. - -You can watch the commands operate in the @samp{*tex-shell*} buffer, -and you can switch to and from and use the @samp{*tex-shell*} buffer -as you would any other shell buffer.@refill - -@need 1500 -The formatting and print commands depend on the values of several variables. -The default values are:@refill - -@example -@group - @r{Variable} @r{Default value} - -texinfo-texi2dvi-command "texi2dvi" -texinfo-tex-command "tex" -texinfo-texindex-command "texindex" -texinfo-delete-from-print-queue-command "lprm" -texinfo-tex-trailer "@@bye" -tex-start-of-header "%**start" -tex-end-of-header "%**end" -tex-dvi-print-command "lpr -d" -tex-show-queue-command "lpq" -@end group -@end example - -You can change the values of these variables 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}). - -@cindex Customize Emacs package (@t{Development/Docs/Texinfo}) -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 -@section Using the Local Variables List -@cindex Local variables -@cindex Compile command for formatting -@cindex Format with the compile command - -Yet another way to apply the @TeX{} formatting command to a Texinfo file -is to put that command in a @dfn{local variables list} at the end of the -Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} -commands as a @code{compile-command} and have Emacs run it by typing -@kbd{M-x compile}. This creates a special shell called the -@file{*compilation*} buffer in which Emacs runs the compile command. -For example, at the end of the @file{gdb.texinfo} file, after the -@code{@@bye}, you could put the following:@refill - -@example -@group -Local Variables: -compile-command: "texi2dvi gdb.texinfo" -End: -@end group -@end example - -@noindent -This technique is most often used by programmers who also compile programs -this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill - - -@node Requirements Summary -@section @TeX{} Formatting Requirements Summary -@cindex Requirements for formatting -@cindex Minimal requirements for formatting -@cindex Formatting requirements - -Every Texinfo file that is to be input to @TeX{} must begin with a -@code{\input} command and must contain an @code{@@setfilename} command: - -@example -\input texinfo -@@setfilename @var{arg-not-used-by-@TeX{}} -@end example - -@noindent -The first command instructs @TeX{} to load the macros it needs to -process a Texinfo file and the second command opens auxiliary files. - -Every Texinfo file must end with a line that terminates @TeX{}'s -processing and forces out unfinished pages: - -@example -@@bye -@end example - -Strictly speaking, these lines are all a Texinfo file needs to be -processed successfully by @TeX{}. - -Usually, however, the beginning includes an @code{@@settitle} command to -define the title of the printed manual, an @code{@@setchapternewpage} -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 - - -@node Preparing for TeX -@section Preparing for @TeX{} -@cindex Preparing for @TeX{} -@cindex @TeX{} input initialization -@cindex @b{.profile} initialization file -@cindex @b{.cshrc} initialization file -@cindex Initialization file for @TeX{} input - -@TeX{} needs to know where to find the @file{texinfo.tex} file that the -@samp{\input texinfo} command on the first line reads. The -@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is -included in all standard GNU distributions. The latest version is -always available from the Texinfo source repository: -@smalldisplay -@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD} -@end smalldisplay - -@pindex texinfo.tex@r{, installing} - -Usually, the installer has put the @file{texinfo.tex} file in the -default directory that contains @TeX{} macros when GNU Texinfo, Emacs or -other GNU software is installed. In this case, @TeX{} will find the -file and you do not need to do anything special. If this has not been -done, you can put @file{texinfo.tex} in the current directory when you -run @TeX{}, and @TeX{} will find it there. - -@pindex epsf.tex@r{, installing} -Also, you should install @file{epsf.tex}, if it is not already installed -from another distribution. More details are at the end of the description -of the @code{@@image} command (@pxref{Images}). - -@cindex European Computer Modern fonts, installing -@cindex EC fonts, installing -@cindex CM-Super fonts, installing -To be able to use quotation marks other than those used in English -you'll need to install European Computer Modern fonts and optionally -CM-Super fonts, unless they are already installed (@pxref{Inserting -Quotation Marks}). - -@pindex feymr10@r{, installing} -@cindex Euro font, installing -If you intend to use the @code{@@euro} command, you should install the -Euro font, if it is not already installed. @xref{euro}. - -@pindex texinfo.cnf @r{installation} -@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. - -@cindex Environment variable @code{TEXINPUTS} -@vindex TEXINPUTS -If neither of the above locations for these system files suffice for -you, you can specify the directories explicitly. For -@file{texinfo.tex}, you can do this by writing the complete path for the -file after the @code{\input} command. Another way, that works for both -@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} -might read), is to set the @code{TEXINPUTS} environment variable in your -@file{.cshrc} or @file{.profile} file. - -Which you use of @file{.cshrc} or @file{.profile} depends on -whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, -@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) -command interpreter. The latter read the @file{.cshrc} file for -initialization information, and the former read @file{.profile}. - -In a @file{.cshrc} file, you could use the following @code{csh} command -sequence: - -@example -setenv TEXINPUTS .:/home/me/mylib: -@end example - -@need 1000 -In a @file{.profile} file, you could use the following @code{sh} command -sequence: - -@example -@group -TEXINPUTS=.:/home/me/mylib: -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: -@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. - -@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 @samp{me}'s @file{mylib} directory, and finally in -the system directories. (A leading, trailing, or doubled @samp{:} -indicates searching the system directories at that point.) - -@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 - -@noindent -(@code{dump} is a @TeX{} primitive.) Then, 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. - - -@node Overfull hboxes -@section Overfull ``hboxes'' -@cindex Overfull @samp{hboxes} -@cindex @samp{hboxes}, overfull -@cindex Final output - -@TeX{} is sometimes unable to typeset a line without extending it into -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: - -@example -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.) - -@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. -@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -for more information about typesetting errors. - -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 should 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 -is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension -containing the current line width. - -@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. - -@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: - -@example -@@finalout -@end example - - -@node smallbook -@section Printing ``Small'' Books -@findex smallbook -@cindex Small book size -@cindex Book, printing small -@cindex Page sizes for books -@cindex Size of printed book - -By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch -format. However, you can direct @TeX{} to typeset a document in a 7 by -9.25 inch format that is suitable for bound books by inserting the -following command on a line by itself at the beginning of the Texinfo -file, before the title page:@refill - -@example -@@smallbook -@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.) - -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. - -@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. - - -@node A4 Paper -@section Printing on A4 Paper -@cindex A4 paper, printing on -@cindex A5 paper, printing on -@cindex Paper size, A4 -@cindex European A4 paper -@findex afourpaper - -You can tell @TeX{} to format a document for printing on European size -A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) -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: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename texinfo -@@settitle Texinfo -@@afourpaper -@@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 for different paper sizes that do not -require changing the source file. - -@findex afourlatex -@findex afourwide -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. - -@code{@@pagesizes} is ignored by @code{makeinfo}. - - -@node Cropmarks and Magnification -@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 -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 -page, like this:@refill - -@example -@group -@@iftex -@@cropmarks -@@end iftex -@end group -@end example - -This command is mainly for printers that typeset several pages on one -sheet of film; but you can attempt to use it to mark the corners of a -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}. - -@findex \mag @r{(raw @TeX{} magnification)} -@cindex Magnified printing -@cindex Larger or smaller pages -You can attempt to direct @TeX{} to typeset pages larger or smaller than -usual with the @code{\mag} @TeX{} command. Everything that is typeset -is scaled proportionally larger or smaller. (@code{\mag} stands for -``magnification''.) This is @emph{not} a Texinfo @@-command, but is a -plain @TeX{} command that is prefixed with a backslash. You have to -write this command between @code{@@tex} and @code{@@end tex} -(@pxref{Raw Formatter Commands}). - -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: - -@example -@group -@@tex -\mag=1200 -@@end tex -@end group -@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 -The simplest way to generate PDF output from Texinfo source is to run -the convenience script @command{texi2pdf} (or @command{pdftexi2dvi}); -this simply executes the @command{texi2dvi} script with the -@option{--pdf} option (@pxref{Format with texi2dvi}). If for some -reason you want to process the document by hand, simply run the -@command{pdftex} program instead of plain @command{tex}. That is, run -@samp{pdftex foo.texi} instead of @samp{tex foo.texi}. - -@dfn{PDF} stands for `Portable Document Format'. It was invented by -Adobe Systems some years ago for document interchange, based on their -PostScript language. Related links: - -@itemize -@item -GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF -reader}. (It can also preview PostScript documents.) - -@item -A freely available standalone @uref{http://www.foolabs.com/xpdf/, -PDF reader} for the X window system. - -@item -@uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. - -@end itemize - -At present, Texinfo does not provide -@samp{@@ifpdf} or @samp{@@pdf} commands as for the other output -formats, since PDF documents contain many internal links that would be -hard or impossible to get right at the Texinfo source level. - -PDF files require special software to be displayed, unlike the plain -ASCII formats (Info, HTML) that Texinfo supports. They also tend to -be much larger than the DVI files output by @TeX{} by default. -Nevertheless, a PDF file does define an actual typeset document in a -self-contained file, so it has its place. - - -@node Obtaining TeX -@section How to Obtain @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@c !!! Here is information about obtaining TeX. Update it whenever. -@c !!! Also consider updating TeX.README on ftp.gnu.org. -@c Updated by RJC on 1 March 1995, conversation with MacKay. -@c Updated by kb@cs.umb.edu on 29 July 1996. -@c Updated by kb@cs.umb.edu on 25 April 1997. -@c Updated by kb@cs.umb.edu on 27 February 1998. -@TeX{} is freely redistributable. You can obtain @TeX{} for Unix -systems via anonymous ftp or on physical media. The core material -consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}). - -Instructions for retrieval by anonymous ftp and information on other -available distributions: -@uref{http://tug.org/unixtex.ftp}. - -The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: - -@display -@group -Free Software Foundation, Inc. -51 Franklin St, Fifth Floor -Boston, MA @ @ 02110-1301 -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 - -Many other @TeX{} distributions are available; see -@uref{http://tug.org/}. - - -@node Creating and Installing Info Files -@chapter Creating and Installing Info Files - -This chapter describes how to create and install Info files. @xref{Info -Files}, for general information about the file format itself. - -@menu -* Creating an Info File:: -* Installing an Info File:: -@end menu - - -@node Creating an Info File -@section Creating an Info File -@cindex Creating an Info file -@cindex Info, creating an online 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. - -For information on installing the Info file in the Info system, -@pxref{Installing an Info File}. - -@menu -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* 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. -@end menu - - -@node makeinfo advantages -@subsection @code{makeinfo} Preferred - -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. - -The @code{texinfo-format-region} and the @code{texinfo-format-buffer} -commands are useful if you cannot run @code{makeinfo}. Also, in some -circumstances, they format short regions or buffers more quickly than -@code{makeinfo}. - - -@node Invoking makeinfo -@subsection Running @code{makeinfo} from a Shell -@pindex makeinfo - -To create an Info file from a Texinfo file, invoke @command{makeinfo} -followed by the name of the Texinfo file. Thus, to create the Info -file for Bison, type the following to the shell: - -@example -makeinfo bison.texinfo -@end example - -(You can run a shell inside Emacs by typing @kbd{M-x shell}.) - -@command{makeinfo} has many options to control its actions and output; -see the next section. - - -@node makeinfo options -@subsection Options for @code{makeinfo} -@cindex @code{makeinfo} options -@cindex Options for @code{makeinfo} - -The @command{makeinfo} program accepts many options. Perhaps the most -commonly needed are those that change the output format. By default, -@command{makeinfo} outputs Info files. - -Each command line option is a word preceded by @samp{--} or a letter -preceded by @samp{-}. You can use abbreviations for the long option -names as long as they are unique. - -For example, you could use the following shell command to create an Info -file for @file{bison.texinfo} in which each line is filled to only 68 -columns: - -@example -makeinfo --fill-column=68 bison.texinfo -@end example - -You can write two or more options in sequence, like this:@refill - -@example -makeinfo --no-split --fill-column=70 @dots{} -@end example - -@noindent -This would keep the Info file together as one possibly very long -file and would also set the fill column to 70. - -The options are: - -@table @code - -@item -D @var{var} -@opindex -D @var{var} -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 --css-include=@var{file} -@opindex --css-include -Include the contents of @var{file}, which should contain cascading -style sheets specifications, in the @samp{<style>} block of the HTML -output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard -input. - -@item --css-ref=@var{url} -@opindex --css-ref -In HTML mode, add a @samp{<link>} tag to the HTML output which -references a cascading style sheet at @var{url}. This allows using -standalone style sheets. - -@item --disable-encoding -@itemx --enable-encoding -@opindex --disable-encoding -@opindex --enable-encoding -By default, or with @option{--enable-encoding}, output accented and -special characters in Info or plain text output based on -@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit -ASCII transliterations are output. -@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting -Accents}. - -@item --docbook -@opindex --docbook -Generate Docbook output rather than Info. - -@item --document-language=@var{lang} -@opindex --document-language -@vindex LANG -Use @var{lang} to translate Texinfo keywords which end up in the -output document. The default is the locale specified by the -@code{@@documentlanguage} command if there is one -(@pxref{documentlanguage}). - -@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. - -@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}. - -@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 -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}. - -@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 -@opindex --html -Generate HTML output rather than Info. @xref{Generating HTML}. By -default, the HTML output is split into one output file per Texinfo -source node, and the split output is written into a subdirectory with -the name of the top-level info file. - -@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 --ifdocbook -@opindex --ifdocbook -@itemx --ifhtml -@opindex --ifhtml -@itemx --ifinfo -@opindex --ifinfo -@itemx --ifplaintext -@opindex --ifplaintext -@itemx --iftex -@opindex --iftex -@itemx --ifxml -@opindex --ifxml -For the specified format, process @samp{@@if@var{format}} and -@samp{@@@var{format}} commands even if not generating the given output -format. For instance, if @option{--iftex} is specified, then -@samp{@@iftex} and @samp{@@tex} blocks will be read. - -@item --macro-expand=@var{file} -@itemx -E @var{file} -@opindex --macro-expand=@var{file} -@opindex -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}. - -@item --no-headers -@item --plaintext -@opindex --no-headers -@opindex --plaintext -@cindex Plain text output -@cindex ASCII text output -@cindex Generating plain text files -@cindex @file{INSTALL} file, generating -@cindex Node separators, omitting -@cindex Menus, omitting -Do not include menus or node separator lines in the output, and -implicitly @option{--enable-encoding} (see above). This results in a -simple plain text file that you can (for example) send in email -without complications, or include in a distribution (as in an -@file{INSTALL} file). - -@cindex Navigation links, omitting -For HTML output, likewise omit menus. And if @samp{--no-split} is also -specified, do not include a navigation links at the top of each node -(these are never included in the default case of split output). -@xref{Generating HTML}. - -In both cases, ignore @code{@@setfilename} and write to standard -output by default---can be overridden with @option{-o}. - -@item --no-ifdocbook -@opindex --no-ifdocbook -@itemx --no-ifhtml -@opindex --no-ifhtml -@itemx --no-ifinfo -@opindex --no-ifinfo -@itemx --no-ifplaintext -@opindex --no-ifplaintext -@itemx --no-iftex -@opindex --no-iftex -@itemx --no-ifxml -@opindex --no-ifxml -Do not process @samp{@@if@var{format}} and @samp{@@@var{format}} -commands, and do process @samp{@@ifnot@var{format}}, even if -generating the given format. For instance, if @option{--no-ifhtml} is -specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be -read, and @samp{@@ifnothtml} blocks will be. - -@item --no-number-footnotes -@opindex --no-number-footnotes -Suppress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@item --no-number-sections -@opindex --no-number-sections -Do not output chapter, section, and appendix numbers. -You need to specify this if your manual is not hierarchically-structured. - -@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{Generating HTML}). - -@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}---a dangerous -thing to do. 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}. - -@item --no-warn -@opindex --no-warn -Suppress warning messages (but @emph{not} error messages). - -@item --number-sections -@opindex --number-sections -Output chapter, section, and appendix numbers as in printed manuals. -This is the default. It works only with hierarchically-structured -manuals. - -@item --output=@var{file} -@itemx -o @var{file} -@opindex --output=@var{file} -@opindex -o @var{file} -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 for the directory into which all -HTML nodes are written (@pxref{Generating HTML}). - -@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. -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 -of @var{indent} is interpreted as follows: - -@table @asis -@item @samp{asis} -Preserve any existing indentation at the starts of paragraphs. - -@item @samp{0} or @samp{none} -Delete any existing indentation. - -@item @var{num} -Indent each paragraph by @var{num} spaces. -@end table - -@item --split-size=@var{num} -@opindex --split-size=@var{num} -Keep Info files to at most @var{num} characters; default is 300,000. - -@item --transliterate-file-names -@opindex --transliterate-file-names -Enable transliteration of 8-bit characters in node names for the -purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}. - -@item -U @var{var} -Cause @var{var} to be undefined. This is equivalent to -@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}). - -@item --verbose -@opindex --verbose -Cause @code{makeinfo} to display messages saying what it is doing. -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. - -@item --xml -@opindex --xml -Generate XML output rather than Info. - -@end table - -@vindex TEXINFO_OUTPUT_FORMAT -@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} -@command{makeinfo} also reads the environment variable -@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not -overridden by a command line option. The possible values are: - -@example -docbook html info plaintext xml -@end example - -If not set, Info output is the default. - - -@node Pointer Validation -@subsection 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: - -@enumerate -@item -If a `Next', `Previous', or `Up' node reference is a reference to a -node in the current file and is not an external reference such as to -@file{(dir)}, then the referenced node must exist.@refill - -@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 - -@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})'. - -@item -If the `Next' reference of a node is not the same as the `Next' reference -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. (Your best bet -is to avoid using @@-commands in node names.) 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} Within Emacs -@cindex Running @code{makeinfo} in Emacs -@cindex @code{makeinfo} inside Emacs -@cindex Shell, running @code{makeinfo} in - -You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the -@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In -Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c -C-m C-b} by default.@refill - -@table @kbd -@item C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@findex makeinfo-region - -@item C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@findex makeinfo-buffer -@end table - -When you invoke @code{makeinfo-region} the output goes to a temporary -buffer. When you invoke @code{makeinfo-buffer} output goes to the -file set with @code{@@setfilename} (@pxref{setfilename}). - -The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands -run the @code{makeinfo} program in a temporary shell buffer. If -@code{makeinfo} finds any errors, Emacs displays the error messages in -the temporary buffer.@refill - -@cindex Errors, parsing -@cindex Parsing errors -@findex next-error -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 -information about using the @code{next-error} command.@refill - -In addition, you can kill the shell in which the @code{makeinfo} -command is running or make the shell buffer display its most recent -output.@refill - -@table @kbd -@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 - -@item C-c C-m C-l -@itemx M-x makeinfo-recenter-output-buffer -@findex makeinfo-recenter-output-buffer -Redisplay the @code{makeinfo} shell buffer to display its most recent -output.@refill -@end table - -@noindent -(Note that the parallel commands for killing and recentering a @TeX{} -job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode -Printing}.)@refill - -You can specify options for @code{makeinfo} by setting the -@code{makeinfo-options} variable with either the @kbd{M-x -customize} or the @kbd{M-x set-variable} command, or by setting the -variable in your @file{.emacs} initialization file. - -For example, you could write the following in your @file{.emacs} file:@refill - -@example -@group -(setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") -@end group -@end example - -@noindent -@c If you write these three cross references using xref, you see -@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 ``Easy Customization Interface,'' ``Examining -and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs -Manual}. -@end iftex -@ifnottex -For more information, see@* -@ref{Easy Customization, , Easy Customization Interface, 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{makeinfo options, , Options for @code{makeinfo}}. -@end ifnottex - -@node texinfo-format commands -@subsection The @code{texinfo-format@dots{}} Commands - -In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo -file with the @code{texinfo-format-region} command. This formats the -current region and displays the formatted text in a temporary buffer -called @samp{*Info Region*}.@refill - -Similarly, you can format a buffer with the -@code{texinfo-format-buffer} command. This command creates a new -buffer and generates the Info file in it. Typing @kbd{C-x C-s} will -save the Info file under the name specified by the -@code{@@setfilename} line which must be near the beginning of the -Texinfo file.@refill - -@table @kbd -@item C-c C-e C-r -@itemx @code{texinfo-format-region} -@findex texinfo-format-region -Format the current region for Info. - -@item C-c C-e C-b -@itemx @code{texinfo-format-buffer} -@findex texinfo-format-buffer -Format the current buffer for Info. -@end table - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands provide you with some error checking, and other functions can -provide you with further help in finding formatting errors. These -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 -@comment node-name, next, previous, up -@subsection 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 Arguments,,, -emacs, The GNU Emacs Manual}.) - -Here is a shell command to format all the files that end in -@file{.texinfo} in the current directory: - -@example -emacs -batch -funcall batch-texinfo-format *.texinfo -@end example - -@noindent -Emacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them.@refill - -Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; -it is not interactive. It kills the Batch mode Emacs on completion.@refill - -@code{batch-texinfo-format} is convenient if you lack @code{makeinfo} -and want to format several Texinfo files at once. When you use Batch -mode, you create a new Emacs process. This frees your current Emacs, so -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 -@comment node-name, next, previous, up -@subsection Tag Files and Split Files -@cindex Making a tag table automatically -@cindex Tag table, making automatically - -If a Texinfo file has more than 30,000 bytes, -@code{texinfo-format-buffer} automatically creates a tag table -for its Info file; @code{makeinfo} always creates a tag table. With -a @dfn{tag table}, Info can jump to new nodes more quickly than it can -otherwise.@refill - -@cindex Indirect subfiles -In addition, if the Texinfo file contains more than about 300,000 -bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the -large Info file into shorter @dfn{indirect} subfiles of about 300,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 -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 -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 -@dfn{indirect} files.@refill - -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 - -@example -@group -Info file: test-texinfo, -*-Text-*- -produced by texinfo-format-buffer -from file: new-texinfo-manual.texinfo - -^_ -Indirect: -test-texinfo-1: 102 -test-texinfo-2: 50422 -@end group -@group -test-texinfo-3: 101300 -^_^L -Tag table: -(Indirect) -Node: overview^?104 -Node: info file^?1271 -@end group -@group -Node: printed manual^?4853 -Node: conventions^?6855 -@dots{} -@end group -@end example - -@noindent -(But @file{test-texinfo} had far more nodes than are shown here.) Each of -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 - -In the list of indirect files, the number following the file name -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. - -If you are using @code{texinfo-format-buffer} to create Info files, -you may want to run the @code{Info-validate} command. (The -@code{makeinfo} command does such a good job on its own, you do not -need @code{Info-validate}.) However, you cannot run the @kbd{M-x -Info-validate} node-checking command on indirect files. For -information on how to prevent files from being split and how to -validate the structure of the nodes, see @ref{Using Info-validate}. - - -@node Installing an Info File -@section Installing an Info File -@cindex Installing an Info file -@cindex Info file installation -@cindex @file{dir} directory for Info installation - -Info files are usually kept in the @file{info} directory. You can read -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. -* New Info File:: Listing a new Info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking install-info:: @code{install-info} options. -@end menu - - -@node Directory File -@subsection The Directory File @file{dir} - -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, -this file is called @file{dir}. (You can find the location of this file -within Emacs by typing @kbd{C-h i} to enter Info and then typing -@kbd{C-x C-f} to see the pathname to the @file{info} directory.) - -The @file{dir} file is itself an Info file. It contains the top level -menu for all the Info files in the system. The menu looks like -this:@refill - -@example -@group -* Menu: -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -* Texinfo: (texinfo). With one source file, make - either a printed manual using - @@TeX@{@} or an Info file. -@dots{} -@end group -@end example - -Each of these menu entries points to the `Top' node of the Info file -that is named in parentheses. (The menu entry does not need to -specify the `Top' node, since Info goes to the `Top' node if no node -name is mentioned. @xref{Other Info Files, , Nodes in Other Info -Files}.)@refill - -Thus, the @samp{Info} entry points to the `Top' node of the -@file{info} file and the @samp{Emacs} entry points to the `Top' node -of the @file{emacs} file.@refill - -In each of the Info files, the `Up' pointer of the `Top' node refers -back to the @code{dir} file. For example, the line for the `Top' -node of the Emacs manual looks like this in Info:@refill - -@example -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}. - - -@node New Info File -@subsection 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 @file{dir} file listing - -To add a new Info file to your system, you must write a menu entry to -add to the menu in the @file{dir} file in the @file{info} directory. -For example, if you were adding documentation for GDB, you would write -the following new entry:@refill - -@example -* GDB: (gdb). The source-level C debugger. -@end example - -@noindent -The first part of the menu entry is the menu entry name, followed by a -colon. The second part is the name of the Info file, in parentheses, -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}. - - -@node Other Info Directories -@subsection 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 -@item -Write the pathname in the @file{dir} file as the second part of the menu. - -@item -If you are using Emacs, list the name of the file in a second @file{dir} -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 - -@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 - -For example, to reach a test file in the @file{/home/bob/info} -directory, you could add an entry like this to the menu in the -standard @file{dir} file:@refill - -@example -* Test: (/home/bob/info/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 - -Alternatively, you could write the following in your @file{.emacs} file: - -@vindex Info-directory-list -@example -@group -(require 'info) -(setq Info-directory-list - (cons (expand-file-name "/home/bob/info") - Info-directory-list)) -@end group -@end example - -This tells Emacs to merge the system @file{dir} file with the @file{dir} -file in @file{/home/bob/info}. Thus, 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. - -@vindex INFOPATH -@cindex Environment variable @code{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. - -@itemize @bullet -@item -In a @file{.cshrc} file, you could set the @code{INFOPATH} -variable as follows:@refill - -@smallexample -setenv INFOPATH .:~/info:/usr/local/emacs/info -@end smallexample - -@item -In a @file{.profile} file, you would achieve the same effect by -writing:@refill - -@smallexample -INFOPATH=.:$HOME/info:/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 Colon, 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 -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): - -@example -INFOPATH=/local/info: -export INFOPATH -@end example - -@noindent -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 -@subsection 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}. -Normally the makefile for the package runs @code{install-info}, just -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 include -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: - -@smallexample -@@dircategory Texinfo documentation system -@@direntry -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -@@end direntry -@end smallexample - -Here's what this produces in the Info file: - -@smallexample -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. @dots{} -@dots{} -END-INFO-DIR-ENTRY -@end smallexample - -@noindent -The @code{install-info} program sees these lines in the Info file, and -that is how it knows what to do. - -Always use the @code{@@direntry} and @code{@@dircategory} commands near -the beginning of the Texinfo input, before the first @code{@@node} -command. If you use them later on in the input, @code{install-info} -will not notice them. - -@code{install-info} will automatically reformat the description of the -menu entries it is adding. As a matter of convention, the description -of the main entry (above, @samp{The GNU documentation format}) should -start at column 32, starting at zero (as in -@code{what-cursor-position} in Emacs). This will make it align with -most others. Description for individual utilities best start in -column 48, where possible. For more information about formatting see -the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in -@ref{Invoking install-info}. - -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. - -@cindex Free Software Directory -@cindex Dir categories, choosing -@cindex Categories, choosing -When choosing a category name for the @code{@@dircategory} command, we -recommend consulting the @uref{http://www.gnu.org/directory, -Free Software Directory}. If your program is not listed there, -or listed incorrectly or incompletely, please report the situation to -the directory maintainers (@email{bug-directory@@gnu.org}) so that the -category names can be kept in sync. - -Here are a few examples (see the @file{util/dir-example} file in the -Texinfo distribution for large sample @code{dir} file): - -@display -Emacs -Localization -Printing -Software development -Software libraries -Text creation and manipulation -@end display - -@cindex Invoking nodes, including in dir file -Each `Invoking' node for every program installed should have a -corresponding @code{@@direntry}. This lets users easily find the -documentation for the different programs they can run, as with the -traditional @command{man} system. - - -@node Invoking install-info -@subsection Invoking @command{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). @code{install-info} -also removes menu entries from the @file{dir} file. It's most often -run as part of software installation, or when constructing a @file{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. - -@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 -@item --add-once -Specifies that the entry or entries will only be put into a single section. - -@item --align=@var{column} -@opindex --align=@var{column} -Specifies the column that the second and subsequent lines of menu entry's -description will be formatted to begin at. The default for this option is -@samp{35}. It is used in conjunction with the @samp{--max-width} option. -@var{column} starts counting at 1. - -@item --append-new-sections -Instead of alphabetizing new sections, place them at the end of the DIR file. - -@item --calign=@var{column} -@opindex --calign=@var{column} -Specifies the column that the first line of menu entry's description will -be formatted to begin at. The default for this option is @samp{33}. It is -used in conjunction with the @samp{--max-width} option. -When the name of the menu entry exceeds this column, entry's description -will start on the following line. -@var{column} starts counting at 1. - -@item --debug -@opindex --debug -Report what is being done. - -@item --delete -@opindex --delete -Delete the entries in @var{info-file} from @var{dir-file}. The file -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. -Any empty sections that result from the removal are also removed. - -@item --description=@var{text} -@opindex --description=@var{text} -Specify the explanatory portion of the menu entry. If you don't specify -a description (either via @samp{--entry}, @samp{--item} or this option), -the description is taken from the Info file itself. - -@item --dir-file=@var{name} -@opindex --dir-file=@var{name} -Specify file name of the Info directory file. This is equivalent to -using the @var{dir-file} argument. - -@item --dry-run -@opindex --dry-run -Same as @samp{--test}. - -@item --entry=@var{text} -@opindex --entry=@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 -added. If you don't specify any entries, they are determined from -information in the Info file itself. - -@item --help -@opindex --help -Display a usage message with basic usage and all available options, -then exit successfully. - -@item --info-file=@var{file} -@opindex --info-file=@var{file} -Specify Info file to install in the directory. This is -equivalent to using the @var{info-file} argument. - -@item --info-dir=@var{dir} -@opindex --info-dir=@var{dir} -Specify the directory where the directory file @file{dir} resides. -Equivalent to @samp{--dir-file=@var{dir}/dir}. - -@item --infodir=@var{dir} -@opindex --infodir=@var{dir} -Same as @samp{--info-dir}. - -@item --item=@var{text} -@opindex --item=@var{text} -Same as @samp{--entry=@var{text}}. An Info directory entry is actually -a menu item. - -@item --keep-old -@opindex --keep-old -Do not replace pre-existing menu entries. When @samp{--remove} is specified, -this option means that empty sections are not removed. - -@item --max-width=@var{column} -@opindex --max-width=@var{column} -Specifies the column that the menu entry's description will be word-wrapped -at. @var{column} starts counting at 1. - -@item --maxwidth=@var{column} -@opindex --maxwidth=@var{column} -Same as @samp{--max-width}. - -@item --menuentry=@var{text} -@opindex --menuentry=@var{text} -Same as @samp{--name}. - -@item --name=@var{text} -@opindex --name=@var{text} -Specify the name portion of the menu entry. If the @var{text} does not start -with an asterisk @samp{*}, it is presumed to be the text after the @samp{*} -and before the parentheses that specify the Info file. Otherwise @var{text} -is taken verbatim, and is meant to include the text up to and including the -first dot @samp{.}. If you don't specify the name (either via @samp{--entry}, -@samp{--item} or this option), it is taken from the Info file itself. If -the Info does not contain the name, the basename of the Info file is used. - -@item --no-indent -@opindex --no-indent -Suppress formatting of new entries into the @file{dir} file. - -@item --quiet -@opindex --quiet -@itemx --silent -@opindex --silent -Suppress warnings, etc., for silent operation. - -@item --remove -@opindex --remove -Same as @samp{--delete}. - -@item --remove-exactly -@opindex --remove-exactly -Also like @samp{--delete}, but only entries if the Info file name -matches exactly; @code{.info} and/or @code{.gz} suffixes are -@emph{not} ignored. - -@item --section=@var{sec} -@opindex --section=@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. If the Info file doesn't specify -a section, the menu entries are put into the Miscellaneous section. - -@item --section @var{regex} @var{sec} -@opindex --section @var{regex} @var{sec} -Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}. - -@code{install-info} tries to detect when this alternate syntax is used, -but does not always guess correctly! Here is the heuristic that -@code{install-info} uses: -@enumerate -@item -If the second argument to @code{--section} starts with a hyphen, the original syntax is presumed. -@item -If the second argument to @code{--section} is a file that can be opened, the original syntax is presumed -@item -Otherwise the alternate syntax is used. -@end enumerate - -When heuristic fails because your section title starts with a hyphen, or it -happens to be a filename that can be opened, the syntax should be changed -to @samp{--regex=@var{regex} --section=@var{sec} --add-once}. - - -@item --regex=@var{regex} -@opindex --regex=@var{regex} -Put this file's entries into any section that matches @var{regex}. If -more than one section matches, all of the entries are added in each of the -sections. Specify @var{regex} using basic regular expression syntax, more -or less as used with @command{grep}, for example. - -@item --test -@opindex --test -Suppress updating of the directory file. - -@item --version -@opindex --version -@cindex Version number, for install-info -Display version information and exit successfully. - -@end table - - -@node Generating HTML -@chapter Generating HTML -@cindex HTML output - -@command{makeinfo} generates Info output by default, but given the -@option{--html} option, it will generate HTML, for web browsers and -other programs. This chapter gives some details on such HTML output. - - -@command{makeinfo} can also write in XML and Docbook format, but we do -not as yet describe these further. @xref{Output Formats}, for a brief -overview of all the output formats. - -@menu -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: Influencing HTML output with Cascading Style Sheets. -* HTML Xref:: Cross-references in HTML output. -@end menu - - -@node HTML Translation -@section HTML Translation - -@command{makeinfo} will include segments of Texinfo source between -@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not -any of the other conditionals, by default). Source between -@code{@@html} and @code{@@end html} is passed without change to the -output (i.e., suppressing the normal escaping of input @samp{<}, -@samp{>} and @samp{&} characters which have special significance in -HTML). @xref{Conditional Commands}. - -@opindex --footnote-style@r{, ignored in HTML output} -The @option{--footnote-style} option is currently ignored for HTML output; -footnotes are always linked to the end of the output file. - -@cindex Navigation bar, in HTML output -By default, a navigation bar is inserted at the start of each node, -analogous to Info output. The @samp{--no-headers} option suppresses -this if used with @samp{--no-split}. Header @code{<link>} elements in -split output can support info-like navigation with browsers like Lynx -and @w{Emacs W3} which implement this HTML@tie{}1.0 feature. - -@cindex HTML output, browser compatibility of -The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866). -One exception is that HTML@tie{}3.2 tables are generated from the -@code{@@multitable} command, but tagged to degrade as well as possible -in browsers without table support. The HTML@tie{}4 @samp{lang} -attribute on the @samp{<html>} attribute is also used. (Please report -output from an error-free run of @code{makeinfo} which has browser -portability problems as a bug.) - - -@node HTML Splitting -@section HTML Splitting -@cindex Split HTML output -@cindex HTML output, split - -When splitting output (which is the default), @command{makeinfo} -writes HTML output into (generally) one output file per Texinfo source -@code{@@node}. - -The output file name is the node name with special characters replaced -by @samp{-}'s, so it can work as a filename. In the unusual case of -two different nodes having the same name after this treatment, they -are written consecutively to the same file, with HTML anchors so each -can be referred to separately. If @command{makeinfo} is run on a -system which does not distinguish case in filenames, nodes which are -the same except for case will also be folded into the same output -file. - -When splitting, the HTML output files are written into a subdirectory, -with the name chosen as follows: -@enumerate -@item -@command{makeinfo} first tries the subdirectory with the base name -from @code{@@setfilename} (that is, any extension is removed). For -example, HTML output for @code{@@setfilename gcc.info} would be -written into a subdirectory named @samp{gcc}. - -@item -If that directory cannot be created for any reason, then -@command{makeinfo} tries appending @samp{.html} to the directory name. -For example, output for @code{@@setfilename texinfo} would be written -to @samp{texinfo.html}. - -@item -If the @samp{@var{name}.html} directory can't be -created either, @code{makeinfo} gives up. - -@end enumerate - -@noindent In any case, the top-level output file within the directory -is always named @samp{index.html}. - -Monolithic output (@code{--no-split}) is named according to -@code{@@setfilename} (with any @samp{.info} extension is replaced with -@samp{.html}) or @code{--output} (the argument is used literally). - - -@node HTML CSS -@section HTML CSS -@cindex HTML, and CSS -@cindex CSS, and HTML output -@cindex Cascading Style Sheets, and HTML output - -Cascading Style Sheets (CSS for short) is an Internet standard for -influencing the display of HTML documents: see -@uref{http://www.w3.org/Style/CSS/}. - -By default, @command{makeinfo} includes a few simple CSS commands to -better implement the appearance of some of the environments. Here -are two of them, as an example: - -@example -pre.display @{ font-family:inherit @} -pre.smalldisplay @{ font-family:inherit; font-size:smaller @} -@end example - -A full explanation of CSS is (far) beyond this manual; please see the -reference above. In brief, however, this specification tells the web -browser to use a `smaller' font size for @code{@@smalldisplay} text, -and to use the `inherited' font (generally a regular roman typeface) -for both @code{@@smalldisplay} and @code{@@display}. By default, the -HTML @samp{<pre>} command uses a monospaced font. - -You can influence the CSS in the HTML output with two -@command{makeinfo} options: @option{--css-include=@var{file}} and -@option{--css-ref=@var{url}}. - -The option @option{--css-ref=@var{url}} adds to each output HTML file -a @samp{<link>} tag referencing a CSS at the given @var{url}. This -allows using external style sheets. - -The option @option{--css-include=@var{file}} includes the contents -@var{file} in the HTML output, as you might expect. However, the -details are somewhat tricky, as described in the following, to provide -maximum flexibility. - -@cindex @@import specifications, in CSS files -The CSS file may begin with so-called @samp{@@import} directives, -which link to external CSS specifications for browsers to use when -interpreting the document. Again, a full description is beyond our -scope here, but we'll describe how they work syntactically, so we can -explain how @command{makeinfo} handles them. - -@cindex Comments, in CSS files -There can be more than one @samp{@@import}, but they have to come -first in the file, with only whitespace and comments interspersed, no -normal definitions. (Technical exception: an @samp{@@charset} -directive may precede the @samp{@@import}'s. This does not alter -@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if -present.) Comments in CSS files are delimited by @samp{/* ... */}, as -in C. An @samp{@@import} directive must be in one of these two forms: - -@example -@@import url(http://example.org/foo.css); -@@import "http://example.net/bar.css"; -@end example - -As far as @command{makeinfo} is concerned, the crucial characters are -the @samp{@@} at the beginning and the semicolon terminating the -directive. When reading the CSS file, it simply copies any such -@samp{@@}-directive into the output, as follows: - -@itemize -@item If @var{file} contains only normal CSS declarations, it is -included after @command{makeinfo}'s default CSS, thus overriding it. - -@item If @var{file} begins with @samp{@@import} specifications (see -below), then the @samp{import}'s are included first (they have to come -first, according to the standard), and then @command{makeinfo}'s -default CSS is included. If you need to override @command{makeinfo}'s -defaults from an @samp{@@import}, you can do so with the @samp{!@: -important} CSS construct, as in: -@example -pre.smallexample @{ font-size: inherit ! important @} -@end example - -@item If @var{file} contains both @samp{@@import} and inline CSS -specifications, the @samp{@@import}'s are included first, then -@command{makeinfo}'s defaults, and lastly the inline CSS from -@var{file}. - -@item Any @@-directive other than @samp{@@import} and @samp{@@charset} -is treated as a CSS declaration, meaning @command{makeinfo} includes -its default CSS and then the rest of the file. - -@end itemize - -If the CSS file is malformed or erroneous, @command{makeinfo}'s output -is unspecified. @command{makeinfo} does not try to interpret the -meaning of the CSS file in any way; it just looks for the special -@samp{@@} and @samp{;} characters and blindly copies the text into the -output. Comments in the CSS file may or may not be included in the -output. - - -@node HTML Xref -@section HTML Cross-references -@cindex HTML cross-references -@cindex Cross-references, in HTML output - -Cross-references between Texinfo manuals in HTML format amount, in the -end, to a standard HTML @code{<a>} link, but the details are -unfortunately complex. This section describes the algorithm used in -detail, so that Texinfo can cooperate with other programs, such as -@command{texi2html}, by writing mutually compatible HTML files. - -This algorithm may or may not be used for links @emph{within} HTML -output for a Texinfo file. Since no issues of compatibility arise in -such cases, we do not need to specify this. - -We try to support references to such ``external'' manuals in both -monolithic and split forms. A @dfn{monolithic} (mono) manual is -entirely contained in one file, and a @dfn{split} manual has a file -for each node. (@xref{HTML Splitting}.) - -@cindex Dumas, Patrice -Acknowledgement: this algorithm was primarily devised by Patrice Dumas -in 2003--04. - -@menu -* Link Basics: HTML Xref Link Basics. -* Node Expansion: HTML Xref Node Name Expansion. -* Command Expansion: HTML Xref Command Expansion. -* 8-bit Expansion: HTML Xref 8-bit Character Expansion. -* Mismatch: HTML Xref Mismatch. -@end menu - - -@node HTML Xref Link Basics -@subsection HTML Cross-reference Link Basics -@cindex HTML cross-reference link basics - -For our purposes, an HTML link consists of four components: a host -name, a directory part, a file part, and a target part. We -always assume the @code{http} protocol. For example: - -@example -http://@var{host}/@var{dir}/@var{file}.html#@var{target} -@end example - -The information to construct a link comes from the node name and -manual name in the cross-reference command in the Texinfo source -(@pxref{Cross References}), and from @dfn{external information}, which -is currently simply hardwired. In the future, it may come from an -external data file. - -We now consider each part in turn. - -The @var{host} is hardwired to be the local host. This could either -be the literal string @samp{localhost}, or, according to the rules for -HTML links, the @samp{http://localhost/} could be omitted entirely. - -The @var{dir} and @var{file} parts are more complicated, and depend on -the relative split/mono nature of both the manual being processed and -the manual that the cross-reference refers to. The underlying idea is -that there is one directory for Texinfo manuals in HTML, and a given -@var{manual} is either available as a monolithic file -@file{@var{manual}.html}, or a split subdirectory -@file{@var{manual}/*.html}. Here are the cases: - -@itemize @bullet -@item -If the present manual is split, and the referent manual is also split, -the directory is @samp{../@var{referent/}} and the file is the -expanded node name (described later). - -@item -If the present manual is split, and the referent manual is mono, the -directory is @samp{../} and the file is @file{@var{referent}.html}. - -@item -If the present manual is mono, and the referent manual is split, the -directory is @file{@var{referent}/} and the file is the expanded node -name. - -@item -If the present manual is mono, and the referent manual is also mono, -the directory is @file{./} (or just the empty string), and the file is -@file{@var{referent}.html}. - -@end itemize - -One exception: the algorithm for node name expansion prefixes the -string @samp{g_t} when the node name begins with a non-letter. This -kludge (due to XHTML rules) is not necessary for filenames, and is -therefore omitted. - -Any directory part in the filename argument of the source -cross-reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} -and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. -This is because any such attempted hardwiring of the directory is very -unlikely to be useful for both Info and HTML output. - -Finally, the @var{target} part is always the expanded node name. - -Whether the present manual is split or mono is determined by user -option; @command{makeinfo} defaults to split, with the -@option{--no-split} option overriding this. - -Whether the referent manual is split or mono is another bit of the -external information. For now, @command{makeinfo} simply assumes the -referent manual is the same as the present manual. - -There can be a mismatch between the format of the referent manual that -the generating software assumes, and the format it's actually present -in. @xref{HTML Xref Mismatch}. - - -@node HTML Xref Node Name Expansion -@subsection HTML Cross-reference Node Name Expansion -@cindex HTML cross-reference node name expansion -@cindex node name expansion, in HTML cross-references -@cindex expansion, of node names in HTML cross-references - -As mentioned in the previous section, the key part of the HTML -cross-reference algorithm is the conversion of node names in the -Texinfo source into strings suitable for XHTML identifiers and -filenames. The restrictions are similar for each: plain ASCII -letters, numbers, and the @samp{-} and @samp{_} characters are all -that can be used. (Although HTML anchors can contain most characters, -XHTML is more restrictive.) - -Cross-references in Texinfo can actually refer either to nodes or -anchors (@pxref{anchor}), but anchors are treated identically to nodes -in this context, so we'll continue to say ``node'' names for -simplicity. - -(@@-commands and 8-bit characters are not presently handled by -@command{makeinfo} for HTML cross-references. See the next section.) - -A special exception: the Top node (@pxref{The Top Node}) is always -mapped to the file @file{index.html}, to match web server software. -However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): - -@example -@@xref@{Top, Introduction,, emacs, The GNU Emacs Manual@}. -@result{} <a href="emacs/index.html#Top"> -@end example - -@enumerate -@item -The standard ASCII letters (a-z and A-Z) are not modified. All other -characters are changed as specified below. - -@item -The standard ASCII numbers (0-9) are not modified except when a number -is the first character of the node name. In that case, see below. - -@item -Multiple consecutive space, tab and newline characters are transformed -into just one space. (It's not possible to have newlines in node -names with the current implementation, but we specify it anyway, just -in case.) - -@item -Leading and trailing spaces are removed. - -@item -After the above has been applied, each remaining space character is -converted into a @samp{-} character. - -@item -Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}}, -where @var{xx} is the ASCII character code in (lowercase) hexadecimal. -This includes @samp{_}, which is mapped to @samp{_005f}. - -@item -If the node name does not begin with a letter, the literal string -@samp{g_t} is prefixed to the result. (Due to the rules above, that -string can never occur otherwise; it is an arbitrary choice, standing -for ``GNU Texinfo''.) This is necessary because XHTML requires that -identifiers begin with a letter. - -@end enumerate - -For example: - -@example -@@node A node --- with _'% -@result{} A-node-_002d_002d_002d-with-_005f_0027_0025 -@end example - -Notice in particular: - -@itemize @bullet -@item @samp{_} @result{} @samp{_005f} -@item @samp{-} @result{} @samp{_002d} -@item @samp{A node} @result{} @samp{A-node} -@end itemize - -On case-folding computer systems, nodes differing only by case will be -mapped to the same file. - -In particular, as mentioned above, Top always maps to the file -@file{index.html}. Thus, on a case-folding system, Top and a node -named `Index' will both be written to @file{index.html}. - -Fortunately, the targets serve to distinguish these cases, since HTML -target names are always case-sensitive, independent of operating -system. - - -@node HTML Xref Command Expansion -@subsection HTML Cross-reference Command Expansion -@cindex HTML cross-reference command expansion - -In standard Texinfo, node names may not contain @@-commands. -@command{makeinfo} has an option @option{--commands-in-node-names} -which partially supports it (@pxref{Invoking makeinfo}), but it is not -robust and not recommended. - -Thus, @command{makeinfo} also does not fully implement this part of -the HTML cross-reference algorithm, but it is documented here for the -sake of completeness. - -First, comments are removed. - -Next, any @code{@@value} commands (@pxref{set value}) and macro invocations -(@pxref{Invoking Macros}) are fully expanded. - -Then, for the following commands, the command name and braces are removed, -the text of the argument is recursively transformed: -@example -@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless -@@emph @@env @@file @@indicateurl @@kbd @@key -@@samp @@sc @@slanted @@strong @@t @@var @@w -@end example - -@noindent For @code{@@sc}, any letters are capitalized. - -The following commands are replaced by constant text, as shown. If -any of these commands have non-empty arguments, as in -@code{@@TeX@{bad@}}, it is an error, and the result is unspecified. -`(space)' means a space character, `(nothing)' means the empty string, -etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}. -There are further transformations of many of these expansions for the -final file or target name, such as space characters to @samp{-}, etc., -according to the other rules. - -@multitable @columnfractions .3 .5 -@item @code{@@(newline)} @tab (space) -@item @code{@@(space)} @tab (space) -@item @code{@@(tab)} @tab (space) -@item @code{@@!} @tab @samp{!} -@item @code{@@*} @tab (space) -@item @code{@@-} @tab (nothing) -@item @code{@@.} @tab @samp{.} -@item @code{@@:} @tab (nothing) -@item @code{@@?} @tab @samp{?} -@item @code{@@@@} @tab @samp{@@} -@item @code{@@@{} @tab @samp{@{} -@item @code{@@@}} @tab @samp{@}} -@item @code{@@LaTeX} @tab @samp{LaTeX} -@item @code{@@TeX} @tab @samp{TeX} -@item @code{@@bullet} @tab U+2022 -@item @code{@@comma} @tab @samp{,} -@item @code{@@copyright} @tab U+00A9 -@item @code{@@dots} @tab U+2026 -@item @code{@@enddots} @tab @samp{...} -@item @code{@@equiv} @tab U+2261 -@item @code{@@error} @tab @samp{error-->} -@item @code{@@euro} @tab U+20AC -@item @code{@@exclamdown} @tab U+00A1 -@item @code{@@expansion} @tab U+2192 -@item @code{@@minus} @tab U+2212 -@item @code{@@ordf} @tab U+00AA -@item @code{@@ordm} @tab U+00BA -@item @code{@@point} @tab U+2605 -@item @code{@@pounds} @tab U+00A3 -@item @code{@@print} @tab U+22A3 -@item @code{@@questiondown} @tab U+00BF -@item @code{@@registeredsymbol} @tab U+00AE -@item @code{@@result} @tab U+21D2 -@item @code{@@tie} @tab (space) -@end multitable - -An @code{@@acronym} or @code{@@abbr} command is replaced by the first -argument, followed by the second argument in parentheses, if present. -@xref{acronym}. - -An @code{@@email} command is replaced by the @var{text} argument if -present, else the address. @xref{email}. - -An @code{@@image} command is replaced by the filename (first) -argument. @xref{Images}. - -A @code{@@verb} command is replaced by its transformed argument. -@xref{verb}. - -Any other command is an error, and the result is unspecified. - - -@node HTML Xref 8-bit Character Expansion -@subsection HTML Cross-reference 8-bit Character Expansion -@cindex HTML cross-reference 8-bit character expansion -@cindex 8-bit characters, in HTML cross-references -@cindex Expansion of 8-bit characters in HTML cross-references -@cindex Transliteration of 8-bit characters in HTML cross-references - -Usually, characters other than plain 7-bit ASCII are transformed into -the corresponding Unicode code point(s) in Normalization Form C, which -uses precomposed characters where available. (This is the -normalization form recommended by the W3C and other bodies.) This -holds when that code point is 0xffff or less, as it almost always is. - -These will then be further transformed by the rules above into the -string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex. - -For example, combining this rule and the previous section: - -@example -@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} -@result{} A-TeX-B_0306-_2605_002e_002e_002e -@end example - -Notice: 1)@tie{}@code{@@enddots} expands to three periods which in -turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' -with a breve accent, which does not exist as a pre-accented Unicode -character, therefore expands to @samp{B_0306} (B with combining -breve). - -When the Unicode code point is above 0xffff, the transformation is -@samp{__@var{xxxxxx}}, that is, two leading underscores followed by -six hex digits. Since Unicode has declared that their highest code -point is 0x10ffff, this is sufficient. (We felt it was better to -define this extra escape than to always use six hex digits, since the -first two would nearly always be zeros.) - -This method works fine if the node name consists mostly of ASCII -characters and contains only few 8-bit ones. If the document is -written in a language whose script is not based on the Latin alphabet -(such as, e.g. Ukrainian), it will create file names consisting -entirely of @samp{_@var{xxxx}} notations, which is inconvenient. - -To handle such cases, @command{makeinfo} offers -@option{--transliterate-file-names} command line option. This option -enables @dfn{transliteration} of node names into ASCII characters for -the purposes of file name creation and referencing. The -transliteration is based on phonetic principle, which makes the -produced file names easily readable. - -For the definition of Unicode Normalization Form C, see Unicode report -UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related -documents and implementations are available elsewhere on the web. - - -@node HTML Xref Mismatch -@subsection HTML Cross-reference Mismatch -@cindex HTML cross-reference mismatch -@cindex Mismatched HTML cross-reference source and target - -As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating -software has to guess whether a given manual being cross-referenced is -available in split or monolithic form---and, inevitably, it might -guess wrong. However, it is possible when the referent manual itself -is generated, it is possible to handle at least some mismatches. - -In the case where we assume the referent is split, but it is actually -available in mono, the only recourse would be to generate a -@file{manual/} subdirectory full of HTML files which redirect back to -the monolithic @file{manual.html}. Since this is essentially the same -as a split manual in the first place, it's not very appealing. - -On the other hand, in the case where we assume the referent is mono, -but it is actually available in split, it is possible to use -JavaScript to redirect from the putatively monolithic -@file{manual.html} to the different @file{manual/node.html} files. -Here's an example: - -@example -function redirect() @{ - switch (location.hash) @{ - case "#Node1": - location.replace("manual/Node1.html#Node1"); break; - case "#Node2" : - location.replace("manual/Node2.html#Node2"); break; - @dots{} - default:; - @} -@} -@end example - -Then, in the @code{<body>} tag of @file{manual.html}: - -@example -<body onLoad="redirect();"> -@end example - -Once again, this is something the software which generated the -@emph{referent} manual has to do in advance, it's not something the -software generating the actual cross-reference in the present manual -can control. - -Ultimately, we hope to allow for an external configuration file to -control which manuals are available from where, and how. - - -@ignore --- not yet -- - -external information --------------------- - -The information for the reference is searched in the file -`htmlxref.cnf' present in the following directories: -<srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/, -DATADIR/texinfo/ -The first match should be used. - -The file is line-oriented, with the following format: - <manualname> <whitespace> <keyword> <whitespace> <urlprefix> -with <keyword> being "mono" or "split". Thus -texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/ -texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html - -If the keyword is 'split', that is the target is split, the urlprefix gives -the directory and host name. -If the keyword is 'mono', that is the target is mono, the urlprefix gives -directory, host and file name. - -'#' followed by a space begins comments. '#' followed by another character -cannot begin comments as there are # in urls. - -@end ignore - - -@node Command List -@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. - -More specifics on the general syntax of different @@-commands are -given in the section below. - -@menu -* Command Syntax:: General syntax for varieties of @@-commands. -@end menu - -@sp 1 -@table @code -@item @@@var{whitespace} -An @code{@@} followed by a space, tab, or newline produces a normal, -stretchable, interword space. @xref{Multiple Spaces}. - -@item @@! -Generate an exclamation point that really does end a sentence (usually -after an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@" -@itemx @@' -Generate an umlaut or acute accent, respectively, over the next -character, as in @"o and @'o. @xref{Inserting Accents}. - -@item @@* -Force a line break. @xref{Line Breaks}. - -@item @@,@{@var{c}@} -Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting -Accents}. - -@item @@- -Insert a discretionary hyphenation point. @xref{- and hyphenation}. - -@item @@. -Produce a period that really does end a sentence (usually after an -end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@/ -Produces no output, but allows a line break. @xref{Line Breaks}. - -@item @@: -Tell @TeX{} to refrain from inserting extra whitespace after an -immediately preceding period, question mark, exclamation mark, or -colon, as @TeX{} normally would. @xref{Not Ending a Sentence}. - -@item @@= -Generate a macron (bar) accent over the next character, as in @=o. -@xref{Inserting Accents}. - -@item @@? -Generate a question mark that really does end a sentence (usually after -an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@@@ -Stands for an at sign, @samp{@@}. -@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. - -@item @@\ -Stands for a backslash (@samp{\}) inside @code{@@math}. -@xref{math,,@code{math}}. - -@item @@^ -@itemx @@` -Generate a circumflex (hat) or grave accent, respectively, over the next -character, as in @^o and @`e. -@xref{Inserting Accents}. - -@item @@@{ -Stands for a left brace, @samp{@{}. -@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. - -@item @@@} -Stands for a right-hand brace, @samp{@}}.@* -@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. - -@item @@~ -Generate a tilde accent over the next character, as in @~N. -@xref{Inserting Accents}. - -@item @@AA@{@} -@itemx @@aa@{@} -Generate the uppercase and lowercase Scandinavian A-ring letters, -respectively: @AA{}, @aa{}. @xref{Inserting Accents}. - -@item @@abbr@{@var{abbreviation}@} -Tag @var{abbreviation} as an abbreviation, such as `Comput.'. -@xref{abbr,, @code{abbr}}. - -@item @@acronym@{@var{acronym}@} -Tag @var{acronym} as an acronym, such as `NASA'. -@xref{acronym,, @code{acronym}}. - -@item @@AE@{@} -@itemx @@ae@{@} -Generate the uppercase and lowercase AE ligatures, respectively: -@AE{}, @ae{}. @xref{Inserting Accents}. - -@itemx @@afivepaper -Change page dimensions for the A5 paper size. @xref{A4 Paper}. - -@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 @@appendix @var{title} -Begin an appendix. The title appears in the table -of contents of a printed manual. In Info, the title is -underlined with asterisks. @xref{unnumbered & appendix, , The -@code{@@unnumbered} and @code{@@appendix} Commands}.@refill - -@item @@appendixsec @var{title} -@itemx @@appendixsection @var{title} -Begin an appendix section within an appendix. The section title appears -in the table of contents of a printed manual. In Info, the title is -underlined with equal signs. @code{@@appendixsection} is a longer -spelling of the @code{@@appendixsec} command. @xref{unnumberedsec -appendixsec heading, , Section Commands}.@refill - -@item @@appendixsubsec @var{title} -Begin an appendix subsection within an appendix. The title appears -in the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , Subsection Commands}.@refill - -@item @@appendixsubsubsec @var{title} -Begin an appendix subsubsection within an appendix subsection. 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 @@arrow@{@} -Produce a normal right arrow glyph: @samp{@arrow{}}. Used by default -for @code{@@click}. @xref{Click Sequences}. - -@item @@asis -Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to -print the table's first column without highlighting (``as is''). -@xref{Two-column Tables}. - -@item @@author @var{author} -Typeset @var{author} flushleft and underline it. @xref{title -subtitle author, , The @code{@@title} and @code{@@author} -Commands}.@refill - -@item @@b@{@var{text}@} -Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill - -@ignore -@item @@br -Force a paragraph break. If used within a line, follow @code{@@br} -with braces. @xref{br, , @code{@@br}}.@refill -@end ignore - -@item @@bullet@{@} -Generate a large round dot, or the closest possible -thing to one. @xref{bullet, , @code{@@bullet}}.@refill - -@item @@bye -Stop formatting a file. The formatters do not see the contents of a -file following an @code{@@bye} command. @xref{Ending a File}.@refill - -@item @@c @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{@@comment}. @xref{Comments}. - -@item @@caption -Define the full caption for a @code{@@float}. @xref{caption shortcaption}. - -@item @@cartouche -Highlight an example or quotation by drawing a box with rounded -corners around it. Pair with @code{@@end cartouche}. No effect in -Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@item @@center @var{line-of-text} -Center the line of text following the command. -@xref{titlefont center sp, , @code{@@center}}.@refill - -@item @@centerchap @var{line-of-text} -Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, -@code{@@chapter}}. - -@item @@chapheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{majorheading & chapheading, , @code{@@majorheading} -and @code{@@chapheading}}.@refill - -@item @@chapter @var{title} -Begin a chapter. The chapter title appears in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{chapter, , @code{@@chapter}}.@refill - -@item @@cindex @var{entry} -Add @var{entry} to the index of concepts. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@cite@{@var{reference}@} -Highlight the name of a book or other reference that lacks a -companion Info file. @xref{cite, , @code{@@cite}}.@refill - -@item @@click@{@} -Represent a single ``click'' in a GUI. Used within -@code{@@clicksequence}. @xref{Click Sequences}. - -@item @@clicksequence@{@var{action} @@click@{@} @var{action}@} -Represent a sequence of clicks in a GUI. @xref{Click Sequences}. - -@item @@clickstyle @@@var{cmd} -Execute @@@var{cmd} for each @code{@@click}; the default is -@code{@@arrow}. The usual following empty braces on @@@var{cmd} are -omitted. @xref{Click Sequences}. - -@item @@clear @var{flag} -Unset @var{flag}, preventing the Texinfo formatting commands from -formatting text between subsequent pairs of @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, and preventing -@code{@@value@{@var{flag}@}} from expanding to the value to which -@var{flag} is set. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@code@{@var{sample-code}@} -Highlight text that is an expression, a syntactically complete token -of a program, or a program name. @xref{code, , @code{@@code}}.@refill - -@item @@comma@{@} -Insert a comma `,' character; only needed when a literal comma would -be taken as an argument separator. @xref{Inserting a Comma}. - -@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}. - -@item @@contents -Print a complete table of contents. Has no effect in Info, which uses -menus instead. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@copyright@{@} -Generate the copyright symbol @copyright{}. @xref{copyright symbol,, -@code{@@copyright@{@}}}. - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Describe an ASCII control character. Insert actual control character -into Info file. @xref{ctrl, , @code{@@ctrl}}. -@end ignore - -@item @@defcodeindex @var{index-name} -Define a new index and its indexing command. Print entries in an -@code{@@code} font. @xref{New Indices, , Defining New -Indices}.@refill - -@item @@defcv @var{category} @var{class} @var{name} -@itemx @@defcvx @var{category} @var{class} @var{name} -Format a description for a variable associated with a class in -object-oriented programming. Takes three arguments: the category of -thing being defined, the class to which it belongs, and its name. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} -Format a description for a function, interactive command, or similar -entity that may take arguments. @code{@@deffn} takes as arguments the -category of entity being described, the name of this particular -entity, and its arguments, if any. @xref{Definition Commands}.@refill - -@item @@defindex @var{index-name} -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}. - -@item @@defivar @var{class} @var{instance-variable-name} -@itemx @@defivarx @var{class} @var{instance-variable-name} -This command formats a description for an instance variable in -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{} -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}. - -@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} -Format a description for a method in object-oriented programming. The -command is equivalent to @samp{@@defop Method @dots{}}. Takes as -arguments the name of the class of the method, the name of the -method, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} -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}. - -@item @@defopt @var{option-name} -@itemx @@defoptx @var{option-name} -Format a description for a user option. The command is equivalent to -@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defspec @var{special-form-name} @var{arguments}@dots{} -@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} -Format a description for a special form. The command is equivalent to -@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} -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}. - -@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} -@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name} -Format a description for a typed class variable in object-oriented programming. -@xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a function or similar entity that may take -arguments and that is typed. @code{@@deftypefn} takes as arguments the -classification of entity being described, the type, the name of the -entity, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} -@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}. - -@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. -@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 -language---an entity that records a value. Takes as arguments the -classification of entity being described, the type, and the name of the -entity. @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 -@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvar @var{variable-name} -@itemx @@defvarx @var{variable-name} -Format a description for variables. The command is equivalent to -@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvr @var{category} @var{name} -@itemx @@defvrx @var{category} @var{name} -Format a description for any kind of variable. @code{@@defvr} takes -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 -Avoid @code{makeinfo} confusion stemming from the detailed node listing -in a master menu. @xref{Master Menu Parts}. - -@item @@dfn@{@var{term}@} -Highlight the introductory or defining use of a term. -@xref{dfn, , @code{@@dfn}}.@refill - -@item @@dircategory @var{dirpart} -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}. - -@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}}. - -@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 @@docbook -Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw -Formatter Commands}. - -@item @@documentdescription -Set the document description text, included in the HTML output. Pair -with @code{@@end documentdescription}. @xref{documentdescription,, -@code{@@documentdescription}}. - -@item @@documentencoding @var{enc} -Declare the input encoding to be @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}}. - -@item @@dotaccent@{@var{c}@} -Generate a dot accent over the character @var{c}, as in @dotaccent{o}. -@xref{Inserting Accents}. - -@item @@dots@{@} -Insert an ellipsis: @samp{@dots{}}. -@xref{dots, , @code{@@dots}}.@refill - -@item @@email@{@var{address}[, @var{displayed-text}]@} -Indicate an electronic mail address. -@xref{email, , @code{@@email}}. - -@item @@emph@{@var{text}@} -Highlight @var{text}; text is displayed in @emph{italics} in printed -output, and surrounded by asterisks in Info. @xref{Emphasis, , -Emphasizing Text}. - -@item @@end @var{environment} -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@{@}}}. - -@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 - -@item @@equiv@{@} -Indicate to the reader the exact equivalence of two forms with a -glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill - -@item @@euro@{@} -Generate the Euro currency sign. -@xref{euro,,@code{@@euro@{@}}}. - -@item @@error@{@} -Indicate to the reader with a glyph that the following text is -an error message: @samp{@error{}}. @xref{Error Glyph}.@refill - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for even-numbered (left-hand) -pages. @xref{Custom Headings, , -How to Make Your Own Headings}.@refill - -@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for every page. Not relevant to -Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill - -@item @@example -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}. - -@item @@exdent @var{line-of-text} -Remove any indentation a line might have. @xref{exdent, , -Undoing the Indentation of a Line}.@refill - -@item @@expansion@{@} -Indicate the result of a macro expansion to the reader with a special -glyph: @samp{@expansion{}}. -@xref{expansion, , @expansion{} Indicating an Expansion}.@refill - -@item @@file@{@var{filename}@} -Highlight the name of a file, buffer, node, or directory. @xref{file, , -@code{@@file}}.@refill - -@item @@finalout -Prevent @TeX{} from printing large black warning rectangles beside -over-wide lines. @xref{Overfull hboxes}.@refill - -@item @@findex @var{entry} -Add @var{entry} to the index of functions. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@float -Environment to define floating material. Pair with @code{@@end float}. -@xref{Floats}. - -@item @@flushleft -@itemx @@flushright -Left justify every line but leave the right end ragged. -Leave font as is. Pair with @code{@@end flushleft}. -@code{@@flushright} analogous. -@xref{flushleft & flushright, , @code{@@flushleft} and -@code{@@flushright}}.@refill - -@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. -@xref{Footnotes}.@refill - -@item @@footnotestyle @var{style} -Specify an Info file's footnote style, either @samp{end} for the end -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}}. - -@item @@ftable @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 -index of functions. Pair with @code{@@end ftable}. The same as -@code{@@table}, except for indexing. @xref{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@item @@geq@{@} -Generate a greater-than-or-equal sign, `@geq{}'. @xref{geq leq}. - -@item @@group -Hold text together that must appear on one printed page. Pair with -@code{@@end group}. Not relevant to Info. @xref{group, , -@code{@@group}}.@refill - -@item @@H@{@var{c}@} -Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. - -@item @@heading @var{title} -Print an unnumbered section-like heading in the text, but not in the -table of contents of a printed manual. In Info, the title is -underlined with equal signs. @xref{unnumberedsec appendixsec heading, -, Section Commands}.@refill - -@item @@headings @var{on-off-single-double} -Turn page headings on or off, and/or specify single-sided or double-sided -page headings for printing. @xref{headings on off, , The -@code{@@headings} Command}. - -@item @@html -Enter HTML completely. Pair with @code{@@end html}. @xref{Raw -Formatter Commands}. - -@item @@hyphenation@{@var{hy-phen-a-ted words}@} -Explicitly define hyphenation points. @xref{- and hyphenation,, -@code{@@-} and @code{@@hyphenation}}. - -@item @@i@{@var{text}@} -Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}. - -@item @@ifclear @var{flag} -If @var{flag} is cleared, the Texinfo formatting commands format text -between @code{@@ifclear @var{flag}} and the following @code{@@end -ifclear} command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@ifdocbook -@itemx @@ifhtml -@itemx @@ifinfo -Begin text that will appear only in the given output format. -@code{@@ifinfo} output appears in both Info and (for historical -compatibility) plain text output. Pair with @code{@@end ifdocbook} -resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. -@xref{Conditionals}. - -@item @@ifnotdocbook -@itemx @@ifnothtml -@itemx @@ifnotinfo -@itemx @@ifnotplaintext -@itemx @@ifnottex -@itemx @@ifnotxml -Begin a stretch of text that will be ignored in one output format but -not the others. The text appears in the formats not specified: -@code{@@ifnothtml} text is omitted from HTML output, etc. The exception -is @code{@@ifnotinfo} text, which is omitted from plain text output as -well as Info output. Pair with the corresponding @code{@@end -ifnot@var{format}}. @xref{Conditionals}. - -@item @@ifplaintext -Begin text that will appear only in the plain text output. -Pair with @code{@@end ifplaintext}. @xref{Conditionals}. - -@item @@ifset @var{flag} -If @var{flag} is set, the Texinfo formatting commands format text -between @code{@@ifset @var{flag}} and the following @code{@@end ifset} -command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@iftex -Begin text that will not appear in the Info file or other output, but -will be processed only by @TeX{}. Pair with @code{@@end iftex}. -@xref{Conditionals, , Conditionally Visible Text}.@refill - -@item @@ifxml -Begin text that will appear only in the XML output. Pair with -@code{@@end ifxml}. @xref{Conditionals}. - -@item @@ignore -Begin text that will not appear in any output. Pair with @code{@@end -ignore}. @xref{Comments, , Comments and Ignored Text}. - -@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} -Include graphics image in external @var{filename} scaled to the given -@var{width} and/or @var{height}, using @var{alt} text and looking for -@samp{@var{filename}.@var{ext}} in HTML. @xref{Images}. - -@item @@include @var{filename} -Incorporate the contents of the file @var{filename} into the Info file -or printed document. @xref{Include Files}.@refill - -@item @@indicateurl@{@var{indicateurl}@} -Indicate text that is a uniform resource locator for the World Wide -Web. @xref{indicateurl, , @code{@@indicateurl}}. - -@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} -Make a cross reference to an Info file for which there is no printed -manual. @xref{inforef, , Cross references using -@code{@@inforef}}.@refill - -@item \input @var{macro-definitions-file} -Use the specified macro definitions file. This command is used only -in the first line of a Texinfo file to cause @TeX{} to make use of the -@file{texinfo} macro definitions file. The backslash in @code{\input} -is used instead of an @code{@@} because @TeX{} does not -recognize @code{@@} until after it has read the definitions file. -@xref{Texinfo File Header}. - -@item @@item -Indicate the beginning of a marked paragraph for @code{@@itemize} and -@code{@@enumerate}; indicate the beginning of the text of a first column -entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. -@xref{Lists and Tables}.@refill - -@item @@itemize @var{mark-generating-character-or-command} -Produce a sequence of indented paragraphs, with a mark inside the left -margin at the beginning of each paragraph. Pair with @code{@@end -itemize}. @xref{itemize, , @code{@@itemize}}.@refill - -@item @@itemx -Like @code{@@item} but do not generate extra vertical space above the -item text. @xref{itemx, , @code{@@itemx}}.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate text that is characters of input to be typed by -users. @xref{kbd, , @code{@@kbd}}.@refill - -@item @@kbdinputstyle @var{style} -Specify when @code{@@kbd} should use a font distinct from @code{@@code}. -@xref{kbd, , @code{@@kbd}}.@refill - -@item @@key@{@var{key-name}@} -Indicate a name for a key on a keyboard. -@xref{key, , @code{@@key}}.@refill - -@item @@kindex @var{entry} -Add @var{entry} to the index of keys. -@xref{Index Entries, , Defining the Entries of an Index}.@refill - -@item @@L@{@} -@itemx @@l@{@} -Generate the uppercase and lowercase Polish suppressed-L letters, -respectively: @L{}, @l{}. - -@item @@LaTeX@{@} -Insert the logo @LaTeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. - -@item @@leq@{@} -Generate a less-than-or-equal sign, `@leq{}'. @xref{geq leq}. - -@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}}. - -@item @@listoffloats -Produce a table-of-contents-like listing of @code{@@float}s. -@xref{listoffloats}. - -@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}@}}. -Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining -Macros}. - -@item @@majorheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. Generate more vertical whitespace before -the heading than the @code{@@chapheading} command. @xref{majorheading & -chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. -@xref{math, , @code{@@math}: Inserting Mathematical Expressions}. - -@item @@menu -Mark the beginning of a menu of nodes in Info. No effect in a printed -manual. Pair with @code{@@end menu}. @xref{Menus}.@refill - -@item @@minus@{@} -Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}. - -@item @@multitable @var{column-width-spec} -Begin a multi-column table. Pair with @code{@@end multitable}. -@xref{Multitable Column Widths}. - -@item @@need @var{n} -Start a new page in a printed manual if fewer than @var{n} mils -(thousandths of an inch) remain on the current page. @xref{need, , -@code{@@need}}. - -@item @@node @var{name}, @var{next}, @var{previous}, @var{up} -Define the beginning of a new node in Info, and serve as a locator for -references for @TeX{}. @xref{node, , @code{@@node}}. - -@item @@noindent -Prevent text from being indented as if it were a new paragraph. -@xref{noindent, , @code{@@noindent}}. - -@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: -@O{}, @o{}. - -@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] -Specify page footings resp.@: headings for odd-numbered (right-hand) -pages. @xref{Custom Headings, , -How to Make Your Own Headings}.@refill - -@item @@OE@{@} -@itemx @@oe@{@} -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}. - -@item @@pindex @var{entry} -Add @var{entry} to the index of programs. @xref{Index Entries, , Defining -the Entries of an Index}.@refill - -@item @@point@{@} -Indicate the position of point in a buffer to the reader with a -glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating -Point in a Buffer}.@refill - -@item @@pounds@{@} -Generate the pounds sterling currency sign. -@xref{pounds,,@code{@@pounds@{@}}}. - -@item @@print@{@} -Indicate printed output to the reader with a glyph: -@samp{@print{}}. @xref{Print Glyph}.@refill - -@item @@printindex @var{index-name} -Print an alphabetized two-column index in a printed manual or generate -an alphabetized menu of index entries for Info. @xref{Printing -Indices & Menus}.@refill - -@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with a lower case `see' in a printed -manual. Use within parentheses only. Do not follow command with a -punctuation mark---the Info formatting commands automatically insert -terminating punctuation as needed. Only the first argument is mandatory. -@xref{pxref, , @code{@@pxref}}.@refill - -@item @@questiondown@{@} -Generate an upside-down question mark. @xref{Inserting Accents}. - -@item @@quotation -Narrow the margins to indicate text that is quoted from another real -or imaginary work. Takes optional argument of prefix text. Pair with -@code{@@end quotation}. @xref{quotation, , -@code{@@quotation}}.@refill - -@item @@r@{@var{text}@} -Print @var{text} in @r{roman} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@raisesections -Change subsequent sections to chapters, subsections to sections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@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 - -@item @@refill -This command used to refill and indent the paragraph after all the -other processing has been done. It is no longer needed, since all -formatters now automatically refill as needed, but you may still see -it in the source to some manuals, as it does no harm. - -@item @@registeredsymbol@{@} -Generate the legal symbol @registeredsymbol{}. @xref{registered -symbol,, @code{@@registeredsymbol@{@}}}. - -@item @@result@{@} -Indicate the result of an expression to the reader with a special -glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill - -@item @@ringaccent@{@var{c}@} -Generate a ring accent over the next character, as in @ringaccent{o}. -@xref{Inserting Accents}. - -@item @@samp@{@var{text}@} -Highlight @var{text} that is a literal example of a sequence of -characters. Used for single characters, for statements, and often for -entire shell commands. @xref{samp, , @code{@@samp}}.@refill - -@item @@sansserif@{@var{text}@} -Print @var{text} in a @sansserif{sans serif} font if possible. No -effect in Info. @xref{Fonts}. - -@item @@sc@{@var{text}@} -Set @var{text} in a printed output in @sc{the small caps font} and -set text in the Info file in uppercase letters. -@xref{Smallcaps}.@refill - -@item @@section @var{title} -Begin a section within a chapter. In a printed manual, the section -title is numbered and appears in the table of contents. In Info, the -title is underlined with equal signs. @xref{section, , -@code{@@section}}.@refill - -@item @@set @var{flag} [@var{string}] -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}}. - -@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}. - -@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}. - -@item @@settitle @var{title} -Provide a title for page headers in a printed manual, and the default -document description for HTML @samp{<head>}. -@xref{settitle, , @code{@@settitle}}.@refill - -@item @@shortcaption -Define the short caption for a @code{@@float}. @xref{caption shortcaption}. - -@item @@shortcontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@summarycontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@shorttitlepage @var{title} -Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. - -@item @@slanted@{@var{text}@} -Print @var{text} in a @slanted{slanted} font if possible. No effect -in Info. @xref{Fonts}. - -@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} (narrow margins, no -filling), but do not select the fixed-width font. Pair with @code{@@end -smalldisplay}. @xref{small}. - -@item @@smallexample -Indent text to indicate an example. Do not fill, select fixed-width -font, narrow the margins. In printed manuals, 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. Pair with @code{@@end smallformat}. @xref{small}. - -@item @@smalllisp -Begin an example of Lisp code. Same as @code{@@smallexample}. Pair -with @code{@@end smalllisp}. @xref{small}. - -@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}@} -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 - -@item @@subheading @var{title} -Print an unnumbered subsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@subsection @var{title} -Begin a subsection within a section. In a printed manual, the -subsection title is numbered and appears in the table of contents. In -Info, the title is underlined with hyphens. @xref{subsection, , -@code{@@subsection}}.@refill - -@item @@subsubheading @var{title} -Print an unnumbered subsubsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with periods. @xref{subsubsection, , The `subsub' -Commands}.@refill - -@item @@subsubsection @var{title} -Begin a subsubsection within a subsection. In a printed manual, -the subsubsection title is numbered and appears in the table of -contents. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@item @@subtitle @var{title} -In a printed manual, set a subtitle in a normal sized font flush to -the right-hand side of the page. Not relevant to Info, which does not -have title pages. @xref{title subtitle author, , @code{@@title} -@code{@@subtitle} and @code{@@author} Commands}.@refill - -@item @@summarycontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@shortcontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@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 - -@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 - -@item @@t@{@var{text}@} -Print @var{text} in a @t{fixed-width}, typewriter-like font. -No effect in Info. @xref{Fonts}.@refill - -@item @@tab -Separate columns in a multitable. @xref{Multitable Rows}. - -@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 -column entries are printed in the font resulting from -@var{formatting-command}. Pair with @code{@@end table}. -@xref{Two-column Tables, , Making a Two-column Table}. -Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, -and @ref{itemx, , @code{@@itemx}}.@refill - -@item @@TeX@{@} -Insert the logo @TeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. - -@item @@tex -Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw -Formatter Commands}. - -@item @@thischapter -@itemx @@thischaptername -@itemx @@thischapternum -@itemx @@thisfile -@itemx @@thispage -@itemx @@thistitle -Only allowed in a heading or footing. Stands for, respectively, the -number and name of the current chapter (in the format `Chapter 1: -Title'), the current chapter name only, the current chapter number -only, the filename, the current page number, and the title of the -document, respectively. @xref{Custom Headings, , How to Make Your Own -Headings}. - -@item @@tie@{@} -Generate a normal interword space at which a line break is not allowed. -@xref{tie,, @code{@@tie@{@}}}. - -@item @@tieaccent@{@var{cc}@} -Generate a tie-after accent over the next two characters @var{cc}, as in -`@tieaccent{oo}'. @xref{Inserting Accents}. - -@item @@tindex @var{entry} -Add @var{entry} to the index of data types. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@title @var{title} -In a printed manual, set a title flush to the left-hand side of the -page in a larger than normal font and underline it with a black rule. -Not relevant to Info, which does not have title pages. @xref{title -subtitle author, , The @code{@@title} @code{@@subtitle} and -@code{@@author} Commands}.@refill - -@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 - -@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 - -@item @@today@{@} -Insert the current date, in `1 Jan 1900' style. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@top @var{title} -In a Texinfo file to be formatted with @code{makeinfo}, identify the -topmost @code{@@node} in the file, which must be written on the line -immediately preceding the @code{@@top} command. Used for -@code{makeinfo}'s node pointer insertion feature. The title is -underlined with asterisks. Both the @code{@@node} line and the @code{@@top} -line normally should be enclosed by @code{@@ifnottex} and @code{@@end -ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo -Pointer Creation, , Creating Pointers with @code{makeinfo}}. - -@item @@u@{@var{c}@} -@itemx @@ubaraccent@{@var{c}@} -@itemx @@udotaccent@{@var{c}@} -Generate a breve, underbar, or underdot accent, respectively, over or -under the character @var{c}, as in @u{o}, @ubaraccent{o}, -@udotaccent{o}. @xref{Inserting Accents}. - -@item @@unnumbered @var{title} -In a printed manual, begin a chapter that appears without chapter -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with asterisks. -@xref{unnumbered & appendix, , @code{@@unnumbered} and -@code{@@appendix}}.@refill - -@item @@unnumberedsec @var{title} -In a printed manual, begin a section that appears without section -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with equal signs. -@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill - -@item @@unnumberedsubsec @var{title} -In a printed manual, begin an unnumbered subsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with hyphens. -@xref{unnumberedsubsec appendixsubsec subheading, , -@code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@unnumberedsubsubsec @var{title} -In a printed manual, begin an unnumbered subsubsection within a -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}@} -@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} -Define a cross reference to an external uniform resource locator for the -World Wide Web. @xref{uref, , @code{@@uref}}. - -@item @@v@{@var{c}@} -Generate check accent over the character @var{c}, as in @v{o}. -@xref{Inserting Accents}. - -@item @@value@{@var{flag}@} -Replace @var{flag} with the value to which it is set by @code{@@set -@var{flag}}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Highlight a metasyntactic variable, which is something that stands for -another piece of text. @xref{var, , Indicating Metasyntactic -Variables}.@refill - -@item @@verb@{@var{delim} @var{literal} @var{delim}@} -Output @var{literal}, delimited by the single character @var{delim}, -exactly as is (in the fixed-width font), including any whitespace or -Texinfo special characters. @xref{verb,,@code{verb}}. - -@item @@verbatim -Output the text of the environment exactly as is (in the fixed-width -font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}. - -@item @@verbatiminclude @var{filename} -Output the contents of @var{filename} exactly as is (in the fixed-width font). -@xref{verbatiminclude,,@code{verbatiminclude}}. - -@item @@vindex @var{entry} -Add @var{entry} to the index of variables. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@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 -formatting the copyright page with the argument @samp{0pt plus -1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used -only in contexts ignored for Info. @xref{Copyright}. - -@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 -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 - -@item @@w@{@var{text}@} -Prevent @var{text} from being split across two lines. -@xref{w, , @code{@@w}}.@refill - -@item @@xml -Enter XML completely. Pair with @code{@@end xml}. @xref{Raw -Formatter Commands}. - -@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 -mandatory. @xref{xref, , @code{@@xref}}.@refill -@end table - - -@node Command Syntax -@section @@-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 -has four types of @@-command:@refill - -@table @asis -@item 1. Non-alphabetic commands. -These commands consist of an @@ followed by a punctuation mark or -other character that is not part of the alphabet. Non-alphabetic -commands are almost always part of the text within a paragraph. The -non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}}, -@code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and -many more. - -@item 2. Alphabetic commands that do not require arguments. -These commands start with @@ followed by a word followed by left- and -right-hand braces. These commands insert special symbols in the -document; they do not require arguments. For example, -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', -and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill - -@item 3. Alphabetic commands that require arguments within braces. -These commands start with @@ followed by a letter or a word, followed by an -argument within braces. For example, the command @code{@@dfn} indicates -the introductory or defining use of a term; it is used as follows: @samp{In -Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill - -@item 4. Alphabetic commands that occupy an entire line. -These commands occupy an entire line. The line starts with @@, -followed by the name of the command (a word); for example, @code{@@center} -or @code{@@cindex}. If no argument is needed, the word is followed by -the end of the line. If there is an argument, it is separated from -the command name by a space. Braces are not used.@refill -@end table - -@cindex Braces and argument syntax -Thus, the alphabetic commands fall into classes that have -different argument syntaxes. You cannot tell to which class a command -belongs by the appearance of its name, but you can tell by the -command's meaning: if the command stands for a glyph, it is in -class 2 and does not require an argument; if it makes sense to use the -command together with other text as part of a paragraph, the command -is in class 3 and must be followed by an argument in braces; -otherwise, it is in class 4 and uses the rest of the line as its -argument.@refill - -The purpose of having a different syntax for commands of classes 3 and -4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command @code{@@refill}, which is always -used at the end of a paragraph immediately following the final period -or other punctuation character. @code{@@refill} takes no argument and -does @emph{not} require braces. @code{@@refill} never confuses the -Emacs paragraph commands because it cannot appear at the beginning of -a line. It is also no longer needed, since all formatters now refill -paragraphs automatically. - - -@node Tips -@appendix Tips and Hints - -Here are some tips for writing Texinfo documentation:@refill - -@cindex Tips -@cindex Usage tips -@cindex Hints -@itemize @bullet -@item -Write in the present tense, not in the past or the future. - -@item -Write actively! For example, write ``We recommend that @dots{}'' rather -than ``It is recommended that @dots{}''. - -@item -Use 70 or 72 as your fill column. Longer lines are hard to read. - -@item -Include a copyright notice and copying permissions. -@end itemize - -@subsubheading Index, Index, Index! - -Write many index entries, in different ways. -Readers like indices; they are helpful and convenient. - -Although it is easiest to write index entries as you write the body of -the text, some people prefer to write entries afterwards. In either -case, write an entry before the paragraph to which it applies. This -way, an index entry points to the first page of a paragraph that is -split across pages. - -Here are more hints we have found valuable: - -@itemize @bullet -@item -Write each index entry differently, so each entry refers to a different -place in the document. - -@item -Write index entries only where a topic is discussed significantly. For -example, it is not useful to index ``debugging information'' in a -chapter on reporting bugs. Someone who wants to know about debugging -information will certainly not find it in that chapter. - -@item -Consistently capitalize the first word of every concept index entry, -or else consistently use lower case. Terse entries often call for -lower case; longer entries for capitalization. Whichever case -convention you use, please use one or the other consistently! Mixing -the two styles looks bad. - -@item -Always capitalize or use upper case for those words in an index for -which this is proper, such as names of countries or acronyms. Always -use the appropriate case for case-sensitive names, such as those in C or -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. - -In the example that follows, a blank line comes after the index -entry for ``Leaping'': - -@example -@group -@@section The Dog and the Fox -@@cindex Jumping, in general -@@cindex Leaping - -@@cindex Dog, lazy, jumped over -@@cindex Lazy dog jumped over -@@cindex Fox, jumps over dog -@@cindex Quick fox jumps over dog -The quick brown fox jumps over the lazy dog. -@end group -@end example - -@noindent -(Note that the example shows entries for the same concept that are -written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so -readers can look up the concept in different ways.) -@end itemize - -@subsubheading Blank Lines - -@itemize @bullet -@item -Insert a blank line between a sectioning command and the first following -sentence or paragraph, or between the indexing commands associated with -the sectioning command and the first following sentence or paragraph, as -shown in the tip on indexing. Otherwise, a formatter may fold title and -paragraph together. - -@item -Always insert a blank line before an @code{@@table} command and after an -@code{@@end table} command; but never insert a blank line after an -@code{@@table} command or before an @code{@@end table} command. - -@need 1000 -For example, - -@example -@group -Types of fox: - -@@table @@samp -@@item Quick -Jump over lazy dogs. -@end group - -@group -@@item Brown -Also jump over lazy dogs. -@@end table - -@end group -@group -@@noindent -On the other hand, @dots{} -@end group -@end example - -Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end -itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the -same way. -@end itemize - -@subsubheading Complete Phrases - -Complete phrases are easier to read than @dots{} - -@itemize @bullet -@item -Write entries in an itemized list as complete sentences; or at least, as -complete phrases. Incomplete expressions @dots{} awkward @dots{} like -this. - -@item -Write the prefatory sentence or phrase for a multi-item list or table as -a complete expression. Do not write ``You can set:''; instead, write -``You can set these variables:''. The former expression sounds cut off. -@end itemize - -@subsubheading Editions, Dates and Versions - -Include edition numbers, version numbers, and dates in the -@code{@@copying} text (for people reading the Texinfo file, and for the -legal copyright in the output files). Then use @code{@@insertcopying} -in the @code{@@titlepage} section (for people reading the printed -output) and the Top node (for people reading the online output). - -It is easiest to do this using @code{@@set} and @code{@@value}. -@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}. - - -@subsubheading Definition Commands - -Definition commands are @code{@@deffn}, @code{@@defun}, -@code{@@defmac}, and the like, and enable you to write descriptions in -a uniform format.@refill - -@itemize @bullet -@item -Write just one definition command for each entity you define with a -definition command. The automatic indexing feature creates an index -entry that leads the reader to the definition. - -@item -Use @code{@@table} @dots{} @code{@@end table} in an appendix that -contains a summary of functions, not @code{@@deffn} or other definition -commands. -@end itemize - -@subsubheading Capitalization - -@itemize @bullet -@item -Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or -@samp{i} in upper case. - -@item -Capitalize ``Info''; it is a name. - -@item -Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase -@samp{T} and @samp{X}. This command causes the formatters to -typeset the name according to the wishes of Donald Knuth, who wrote -@TeX{}. -@end itemize - -@subsubheading Spaces - -Do not use spaces to format a Texinfo file, except inside of -@code{@@example} @dots{} @code{@@end example} and other literal -environments and commands. - -@need 700 -For example, @TeX{} fills the following: - -@example -@group - @@kbd@{C-x v@} - @@kbd@{M-x vc-next-action@} - Perform the next logical operation - on the version-controlled file - corresponding to the current buffer. -@end group -@end example - -@need 950 -@noindent -so it looks like this: - -@iftex -@quotation - @kbd{C-x v} - @kbd{M-x vc-next-action} - Perform the next logical operation on the version-controlled file - corresponding to the current buffer. -@end quotation -@end iftex -@ifnottex -@quotation -`C-x v' `M-x vc-next-action' Perform the next logical operation on the -version-controlled file corresponding to the current buffer. -@end quotation -@end ifnottex - -@noindent -In this case, the text should be formatted with -@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. - - -@subsubheading @@code, @@samp, @@var, and @samp{---} - -@itemize @bullet -@item -Use @code{@@code} around Lisp symbols, including command names. -For example, - -@example -The main function is @@code@{vc-next-action@}, @dots{} -@end example - -@item -Avoid putting letters such as @samp{s} immediately after an -@samp{@@code}. Such letters look bad. - -@item -Use @code{@@var} around meta-variables. Do not write angle brackets -around them. - -@item -Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} -typesets these as a long dash and the Info formatters reduce three -hyphens to two. -@end itemize - -@subsubheading Periods Outside of Quotes - -Place periods and other punctuation marks @emph{outside} of quotations, -unless the punctuation is part of the quotation. This practice goes -against publishing conventions in the United States, but enables the -reader to distinguish between the contents of the quotation and the -whole passage. - -For example, you should write the following sentence with the period -outside the end quotation marks: - -@example -Evidently, @samp{au} is an abbreviation for ``author''. -@end example - -@noindent -since @samp{au} does @emph{not} serve as an abbreviation for -@samp{author.} (with a period following the word). - -@subsubheading Introducing New Terms - -@itemize @bullet -@item -Introduce new terms so that a reader who does not know them can -understand them from context; or write a definition for the term. - -For example, in the following, the terms ``check in'', ``register'' and -``delta'' are all appearing for the first time; the example sentence should be -rewritten so they are understandable. - -@quotation -The major function assists you in checking in a file to your -version control system and registering successive sets of changes to -it as deltas. -@end quotation - -@item -Use the @code{@@dfn} command around a word being introduced, to indicate -that the reader should not expect to know the meaning already, and -should expect to learn the meaning from this passage. -@end itemize - -@subsubheading @@pxref - -@c !!! maybe include this in the tips on pxref -@ignore -By the way, it is okay to use pxref with something else in front of -it within the parens, as long as the pxref is followed by the close -paren, and the material inside the parens is not part of a larger -sentence. Also, you can use xref inside parens as part of a complete -sentence so long as you terminate the cross reference with punctuation. -@end ignore -Absolutely never use @code{@@pxref} except in the special context for -which it is designed: inside parentheses, with the closing parenthesis -following immediately after the closing brace. One formatter -automatically inserts closing punctuation and the other does not. This -means that the output looks right both in printed output and in an Info -file, but only when the command is used inside parentheses. - -@subsubheading Invoking from a Shell - -You can invoke programs such as Emacs, GCC, and @code{gawk} from a -shell. The documentation for each program should contain a section that -describes this. Unfortunately, if the node names and titles for these -sections are all different, they are difficult for users to find. - -So, there is a convention to name such sections with a phrase beginning -with the word `Invoking', as in `Invoking Emacs'; this way, users can -find the section easily. - - -@subsubheading ANSI C Syntax - -When you use @code{@@example} to describe a C function's calling -conventions, use the ANSI C syntax, like this:@refill - -@example -void dld_init (char *@@var@{path@}); -@end example - -@noindent -And in the subsequent discussion, refer to the argument values by -writing the same argument names, again highlighted with -@code{@@var}.@refill - -@need 800 -Avoid the obsolete style that looks like this:@refill - -@example -#include <dld.h> - -dld_init (path) -char *path; -@end example - -Also, it is best to avoid writing @code{#include} above the -declaration just to indicate that the function is declared in a -header file. The practice may give the misimpression that the -@code{#include} belongs near the declaration of the function. Either -state explicitly which header file holds the declaration or, better -yet, name the header file used for a group of functions at the -beginning of the section that describes the functions.@refill - -@subsubheading Bad Examples - -Here are several examples of bad writing to avoid: - -In this example, say, `` @dots{} you must @code{@@dfn}@{check -in@} the new version.'' That flows better. - -@quotation -When you are done editing the file, you must perform a -@code{@@dfn}@{check in@}. -@end quotation - -In the following example, say, ``@dots{} makes a unified interface such as VC -mode possible.'' - -@quotation -SCCS, RCS and other version-control systems all perform similar -functions in broadly similar ways (it is this resemblance which makes -a unified control mode like this possible). -@end quotation - -And in this example, you should specify what `it' refers to: - -@quotation -If you are working with other people, it assists in coordinating -everyone's changes so they do not step on each other. -@end quotation - -@subsubheading And Finally @dots{} - -@itemize @bullet -@item -Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last -sound in the name `Bach'. But pronounce Texinfo as in `speck': -``teckinfo''. - -@item -Write notes for yourself at the very end of a Texinfo file after the -@code{@@bye}. None of the formatters process text after the -@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} -@code{@@end ignore}. -@end itemize - - -@node Sample Texinfo Files -@appendix Sample Texinfo Files -@cindex Sample Texinfo files - -The first example is from the first chapter (@pxref{Short Sample}), -given here in its entirety, without commentary. The second -includes the full texts to be used in GNU manuals. - -@menu -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: -@end menu - - -@node Short Sample Texinfo File -@section Short Sample -@cindex Sample Texinfo file, no comments - -Here is a complete, short sample Texinfo file, without any commentary. -You can see this file, with comments, in the first chapter. @xref{Short -Sample}. - -In a nutshell: The @command{makeinfo} program transforms a Texinfo -source file such as this into an Info file or HTML; and @TeX{} typesets -it for a printed manual. - - -@sp 1 -@example -\input texinfo @@c -*-texinfo-*- -@@c %**start of header -@@setfilename sample.info -@@settitle Sample Manual 1.0 -@@c %**end of header - -@@copying -This is a short example of a complete Texinfo file. - -Copyright @copyright{} 2005 Free Software Foundation, Inc. -@@end copying - -@@titlepage -@@title Sample Title -@@page -@@vskip 0pt plus 1filll -@@insertcopying -@@end titlepage - -@@c Output the table of the contents at the beginning. -@@contents - -@@ifnottex -@@node Top -@@top GNU Sample - -@@insertcopying -@@end ifnottex - -@@menu -* First Chapter:: The first chapter is the - only chapter in this sample. -* Index:: Complete index. -@@end menu - - -@@node First Chapter -@@chapter First Chapter - -@@cindex chapter, first - -This is the first chapter. -@@cindex index entry, another - -Here is a numbered list. - -@@enumerate -@@item -This is the first item. - -@@item -This is the second item. -@@end enumerate - - -@@node Index -@@unnumbered Index - -@@printindex cp - -@@bye -@end example - - -@node GNU Sample Texts -@section GNU Sample Texts - -@cindex GNU sample texts -@cindex Sample texts, GNU -@cindex Full texts, GNU - -Following is a sample Texinfo document with the full texts that should -be used in GNU manuals. - -As well as the legal texts, it also serves as a practical example of how -many elements in a GNU system can affect the manual. If you're not -familiar with all these different elements, don't worry. They're not -required and a perfectly good manual can be written without them. -They're included here nonetheless because many manuals do (or could) -benefit from them. - -@xref{Short Sample}, for a minimal example of a Texinfo file. -@xref{Beginning a File}, for a full explanation of that minimal -example. - -Here are some notes on the example: - -@itemize @bullet -@item -@cindex $Id -@cindex CVS $Id -@cindex RCS $Id -@cindex Documentation identification -@cindex Identification of documentation -The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs, -Concurrent Versions System}) or RCS -(@url{http://www.gnu.org/software/rcs}) version control systems, which -expand it into a string such as: -@example -$Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@end example -(This is useful in all sources that use version control, not just manuals.) -You may wish to include the @samp{$Id:} comment in the @code{@@copying} -text, if you want a completely unambiguous reference to the -documentation version. - -If you want to literally write @t{@w{$}Id$}, use @code{@@w}: -@code{@@w@{$@}Id$}. - -@item -@pindex automake@r{, and version info} -@vindex UPDATED @r{Automake variable} -@vindex VERSION @r{Automake variable} -@pindex time-stamp.el -The @file{version.texi} in the @code{@@include} command is maintained -automatically by Automake (@pxref{Top,, Introduction, automake, GNU -Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used -elsewhere. If your distribution doesn't use Automake, but you do use -Emacs, you may find the time-stamp.el package helpful (@pxref{Time -Stamps,,,emacs,The GNU Emacs Manual}). - -@item -The @code{@@syncodeindex} command reflects the recommendation to use -only one index where possible, to make it easier for readers to look up -index entries. - -@item -The @code{@@dircategory} is for constructing the Info directory. -@xref{Installing Dir Entries}, which includes a variety of recommended -category names. - -@item -The `Invoking' node is a GNU standard to help users find the basic -information about command-line usage of a given program. @xref{Manual -Structure Details,,,standards, GNU Coding Standards}. - -@item -@cindex GNU Free Documentation License, including entire -@cindex Free Documentation License, including entire -It is best to include the entire GNU Free Documentation License in a GNU -manual, unless the manual is only a few pages long. Of course this -sample is even shorter than that, but it includes the FDL anyway in -order to show one conventional way to do so. The @file{fdl.texi} file -is available on the GNU machines and in the Texinfo and other GNU -source distributions. - -The FDL provides for omitting itself under certain conditions, but in -that case the sample texts given here have to be modified. @xref{GNU -Free Documentation License}. - -@item -If the FSF is not the copyright holder, then use the appropriate name. - -@item -If your manual is not published on paper by the FSF, then omit the -last sentence in the Back-Cover Text that talks about copies from GNU -Press. - -@item -If your manual has Invariant Sections (again, see the license itself -for details), then change the text here accordingly. - -@item -For documents that express your personal views, feelings or experiences, -it is more appropriate to use a license permitting only verbatim -copying, rather than the FDL. @xref{Verbatim Copying License}. - -@end itemize - -Here is the sample document: - -@verbatim -\input texinfo @c -*-texinfo-*- -@comment $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@comment %**start of header -@setfilename sample.info -@include version.texi -@settitle GNU Sample @value{VERSION} -@syncodeindex pg cp -@comment %**end of header -@copying -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), -which is an example in the Texinfo documentation. - -Copyright @copyright{} 2007 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* sample: (sample)Invoking sample. -@end direntry - -@titlepage -@title GNU Sample -@subtitle for version @value{VERSION}, @value{UPDATED} -@author A.U. Thor (@email{bug-texinfo@@gnu.org}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Sample - -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). -@end ifnottex - -@menu -* Invoking sample:: -* Copying This Manual:: -* Index:: -@end menu - - -@node Invoking sample -@chapter Invoking sample - -@pindex sample -@cindex invoking @command{sample} - -This is a sample manual. There is no sample program to -invoke, but if there was, you could see its basic usage -and command line options here. - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include fdl.texi - - -@node Index -@unnumbered Index - -@printindex cp - -@bye -@end verbatim - - -@node Verbatim Copying License -@section Verbatim Copying License - -@cindex Verbatim copying license -@cindex License for verbatim copying - -For software manuals and other documentation, it is important to use a -license permitting free redistribution and updating, so that when a free -program is changed, the documentation can be updated as well. - -On the other hand, for documents that express your personal views, -feelings or experiences, it is more appropriate to use a license -permitting only verbatim copying. - -Here is sample text for such a license permitting verbatim copying only. -This is just the license text itself. For a complete sample document, -see the previous sections. - -@verbatim -@copying -This document is a sample for allowing verbatim copying only. - -Copyright @copyright{} 2005 Free Software Foundation, Inc. - -@quotation -Permission is granted to make and distribute verbatim copies -of this entire document without royalty provided the -copyright notice and this permission notice are preserved. -@end quotation -@end copying -@end verbatim - - -@node All-permissive Copying License -@section All-permissive Copying License - -@cindex All-permissive copying license -@cindex License for all-permissive copying - -For software manuals and other documentation, it is important to use a -license permitting free redistribution and updating, so that when a free -program is changed, the documentation can be updated as well. - -On the other hand, for small supporting files, short manuals (under 300 -lines long) and rough documentation (README files, INSTALL files, etc.), -the full FDL would be overkill. They can use a simple all-permissive -license. - -Here is sample text for such an all-permissive license. This is just -the license text itself. For a complete sample document, see the -previous sections. - -@example -Copyright @copyright{} 2005 Free Software Foundation, Inc. - -Copying and distribution of this file, with or without modification, -are permitted in any medium without royalty provided the copyright -notice and this notice are preserved. -@end example - - -@node Include Files -@appendix Include Files -@cindex Include files - -When @TeX{} or an Info formatting command sees an @code{@@include} -command in a Texinfo file, it processes the contents of the file named -by the command and incorporates them into the DVI or Info file being -created. Index entries from the included file are incorporated into -the indices of the output file. - -Include files let you keep a single large document as a collection of -conveniently small parts. - -@menu -* Using Include Files:: How to use the @code{@@include} command. -* texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. -* Sample Include File:: A sample outer file with included files - within it; and a sample included file. -* Include Files Evolution:: How use of the @code{@@include} command - has changed over time. -@end menu - -@node Using Include Files -@section How to Use Include Files -@findex include - -To include another file within a Texinfo file, write the -@code{@@include} command at the beginning of a line and follow it on -the same line by the name of a file to be included. For example: - -@example -@@include buffers.texi -@end example - -The name of the file is taken literally, with a single exception: -@code{@@value@{@var{var}@}} references are expanded. This makes it -possible to reliably include files in other directories in a -distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for -an example. - -An included file should simply be a segment of text that you expect to -be included as is into the overall or @dfn{outer} Texinfo file; it -should not contain the standard beginning and end parts of a Texinfo -file. In particular, you should not start an included file with a -line saying @samp{\input texinfo}; if you do, that phrase is inserted -into the output file as is. Likewise, you should not end an included -file with an @code{@@bye} command; nothing after @code{@@bye} is -formatted. - -In the past, you were required to write an @code{@@setfilename} line at the -beginning of an included file, but no longer. Now, it does not matter -whether you write such a line. If an @code{@@setfilename} line exists -in an included file, it is ignored.@refill - -Conventionally, an included file begins with an @code{@@node} line that -is followed by an @code{@@chapter} line. Each included file is one -chapter. This makes it easy to use the regular node and menu creating -and updating commands to create the node pointers and menus within the -included file. However, the simple Emacs node and menu creating and -updating commands do not work with multiple Texinfo files. Thus you -cannot use these commands to fill in the `Next', `Previous', and `Up' -pointers of the @code{@@node} line that begins the included file. Also, -you cannot use the regular commands to create a master menu for the -whole file. Either you must insert the menus and the `Next', -`Previous', and `Up' pointers by hand, or you must use the GNU Emacs -Texinfo mode command, @code{texinfo-multiple-files-update}, that is -designed for @code{@@include} files.@refill - -When an included file does not have any node lines in it, the -multiple files update command does not try to create a menu entry -for it. Consequently, you can include any file, such as a -version or an update file without node lines, not just files that -are chapters. Small includable files like this are created by -Automake (@pxref{GNU Sample Texts}). - - -@node texinfo-multiple-files-update -@section @code{texinfo-multiple-files-update} -@findex texinfo-multiple-files-update - -GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} -command. This command creates or updates `Next', `Previous', and `Up' -pointers of included files as well as those in the outer or overall -Texinfo file, and it creates or updates a main menu in the outer file. -Depending whether you call it with optional arguments, the command -updates only the pointers in the first @code{@@node} line of the -included files or all of them:@refill - -@table @kbd -@item M-x texinfo-multiple-files-update -Called without any arguments:@refill - -@itemize @minus -@item -Create or update the `Next', `Previous', and `Up' pointers of the -first @code{@@node} line in each file included in an outer or overall -Texinfo file.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -Create or update a main menu in the outer file.@refill -@end itemize - -@item C-u M-x texinfo-multiple-files-update -Called with @kbd{C-u} as a prefix argument: - -@itemize @minus{} -@item -Create or update pointers in the first @code{@@node} line in each -included file. - -@item -Create or update the `Top' level node pointers of the outer file. - -@item -Create and insert a master menu in the outer file. The master menu -is made from all the menus in all the included files.@refill -@end itemize - -@item C-u 8 M-x texinfo-multiple-files-update -Called with a numeric prefix argument, such as @kbd{C-u 8}: - -@itemize @minus -@item -Create or update @strong{all} the `Next', `Previous', and `Up' pointers -of all the included files.@refill - -@item -Create or update @strong{all} the menus of all the included -files.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -And then create a master menu in the outer file. This is similar to -invoking @code{texinfo-master-menu} with an argument when you are -working with just one file.@refill -@end itemize -@end table - -Note the use of the prefix argument in interactive use: with a regular -prefix argument, just @w{@kbd{C-u}}, the -@code{texinfo-multiple-files-update} command inserts a master menu; -with a numeric prefix argument, such as @kbd{C-u 8}, the command -updates @strong{every} pointer and menu in @strong{all} the files and then inserts a -master menu.@refill - - -@node Include Files Requirements -@section Include Files Requirements -@cindex Include files requirements -@cindex Requirements for include files - -If you plan to use the @code{texinfo-multiple-files-update} command, -the outer Texinfo file that lists included files within it should -contain nothing but the beginning and end parts of a Texinfo file, and -a number of @code{@@include} commands listing the included files. It -should not even include indices, which should be listed in an included -file of their own.@refill - -Moreover, each of the included files must contain exactly one highest -level node (conventionally, @code{@@chapter} or equivalent), -and this node must be the first node in the included file. -Furthermore, each of these highest level nodes in each included file -must be at the same hierarchical level in the file structure. -Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an -@code{@@unnumbered} node. Thus, normally, each included file contains -one, and only one, chapter or equivalent-level node.@refill - -The outer file should contain only @emph{one} node, the `Top' node. It -should @emph{not} contain any nodes besides the single `Top' node. The -@code{texinfo-multiple-files-update} command will not process -them.@refill - - -@node Sample Include File -@section Sample File with @code{@@include} -@cindex Sample @code{@@include} file -@cindex Include file sample -@cindex @code{@@include} file sample - -Here is an example of an outer Texinfo file with @code{@@include} files -within it before running @code{texinfo-multiple-files-update}, which -would insert a main or master menu: - -@example -@group -\input texinfo @@c -*-texinfo-*- -@c %**start of header -@@setfilename include-example.info -@@settitle Include Example -@c %**end of header -@end group - -... @xref{Sample Texinfo Files}, for -examples of the rest of the frontmatter ... - -@group -@@ifnottex -@@node Top -@@top Include Example -@@end ifnottex -@end group - -@group -@@include foo.texinfo -@@include bar.texinfo -@@include concept-index.texinfo -@@bye -@end group -@end example - -An included file, such as @file{foo.texinfo}, might look like this: - -@example -@group -@@node First -@@chapter First Chapter - -Contents of first chapter @dots{} -@end group -@end example - -The full contents of @file{concept-index.texinfo} might be as simple as this: - -@example -@group -@@node Concept Index -@@unnumbered Concept Index - -@@printindex cp -@end group -@end example - -The outer Texinfo source file for @cite{The GNU Emacs 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. - - -@node Include Files Evolution -@section 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 -Texinfo source file. This custom meant that Emacs did not need to -make a large buffer to hold the whole of a large Info file when -someone wanted information; instead, Emacs allocated just enough -memory for the small Info file that contained the particular -information sought. This way, Emacs could avoid wasting memory.@refill - -References from one file to another were made by referring to the file -name as well as the node name. (@xref{Other Info Files, , Referring to -Other Info Files}. Also, see @ref{Four and Five Arguments, , -@code{@@xref} with Four and Five Arguments}.)@refill - -Include files were designed primarily as a way to create a single, -large printed manual out of several smaller Info files. In a printed -manual, all the references were within the same document, so @TeX{} -could automatically determine the references' page numbers. The Info -formatting commands used include files only for creating joint -indices; each of the individual Texinfo files had to be formatted for -Info individually. (Each, therefore, required its own -@code{@@setfilename} line.)@refill - -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 -in which several different people write different sections of a -document simultaneously.@refill - -In addition, the Info formatting commands have been extended to work -with the @code{@@include} command so as to create a single large Info -file that is split into smaller files if necessary. This means that -you can write menus and cross references without naming the different -Texinfo files.@refill - - -@node Headings -@appendix Page Headings -@cindex Headings -@cindex Footings -@cindex Page numbering -@cindex Page headings -@cindex Formatting headings and footings - -Most printed manuals contain headings along the top of every page -except the title and copyright pages. Some manuals also contain -footings. (Headings and footings have no meaning to Info, which is -not paginated.)@refill - -@menu -* Headings Introduced:: Conventions for using page headings. -* Heading Format:: Standard page heading formats. -* Heading Choice:: How to specify the type of page heading. -* Custom Headings:: How to create your own headings and footings. -@end menu - -@node Headings Introduced -@section Headings Introduced - -Texinfo provides standard page heading formats for manuals that are -printed on one side of each sheet of paper and for manuals that are -printed on both sides of the paper. Typically, you will use these -formats, but you can specify your own format if you wish.@refill - -In addition, you can specify whether chapters should begin on a new -page, or merely continue the same page as the previous chapter; and if -chapters begin on new pages, you can specify whether they must be -odd-numbered pages.@refill - -By convention, a book is printed on both sides of each sheet of paper. -When you open a book, the right-hand page is odd-numbered, and -chapters begin on right-hand pages---a preceding left-hand page is -left blank if necessary. Reports, however, are often printed on just -one side of paper, and chapters begin on a fresh page immediately -following the end of the preceding chapter. In short or informal -reports, chapters often do not begin on a new page at all, but are -separated from the preceding text by a small amount of whitespace.@refill - -The @code{@@setchapternewpage} command controls whether chapters begin -on new pages, and whether one of the standard heading formats is used. -In addition, Texinfo has several heading and footing commands that you -can use to generate your own heading and footing formats.@refill - -In Texinfo, headings and footings are single lines at the tops and -bottoms of pages; you cannot create multiline headings or footings. -Each header or footer line is divided into three parts: a left part, a -middle part, and a right part. Any part, or a whole line, may be left -blank. Text for the left part of a header or footer line is set -flushleft; text for the middle part is centered; and, text for the -right part is set flushright.@refill - -@node Heading Format -@comment node-name, next, previous, up -@section 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 -on both sides of the paper. - -By default, nothing is specified for the footing of a Texinfo file, -so the footing remains blank.@refill - -The standard format for single-sided printing consists of a header -line in which the left-hand part contains the name of the chapter, the -central part is blank, and the right-hand part contains the page -number.@refill - -@need 950 -A single-sided page looks like this: - -@example -@group - _______________________ - | | - | chapter page number | - | | - | Start of text ... | - | ... | - | | -@end group -@end example - -The standard format for two-sided printing depends on whether the page -number is even or odd. By convention, even-numbered pages are on the -left- and odd-numbered pages are on the right. (@TeX{} will adjust the -widths of the left- and right-hand margins. Usually, widths are -correct, but during double-sided printing, it is wise to check that -pages will bind properly---sometimes a printer will produce output in -which the even-numbered pages have a larger right-hand margin than the -odd-numbered pages.)@refill - -In the standard double-sided format, the left part of the left-hand -(even-numbered) page contains the page number, the central part is -blank, and the right part contains the title (specified by the -@code{@@settitle} command). The left part of the right-hand -(odd-numbered) page contains the name of the chapter, the central part -is blank, and the right part contains the page number.@refill - -@need 750 -Two pages, side by side as in an open book, look like this:@refill - -@example -@group - _______________________ _______________________ - | | | | - | page number title | | chapter page number | - | | | | - | Start of text ... | | More text ... | - | ... | | ... | - | | | | -@end group -@end example - -@noindent -The chapter name is preceded by the word ``Chapter'', the chapter number -and a colon. This makes it easier to keep track of where you are in the -manual.@refill - -@node Heading Choice -@comment node-name, next, previous, up -@section 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 -title and copyright pages are not numbered. The @code{@@end -titlepage} command causes @TeX{} to begin to generate page headings -according to a standard format specified by the -@code{@@setchapternewpage} command that precedes the -@code{@@titlepage} section.@refill - -@need 1000 -There are four possibilities:@refill - -@table @asis -@item No @code{@@setchapternewpage} command -Cause @TeX{} to specify the single-sided heading format, with chapters -on new pages. This is the same as @code{@@setchapternewpage on}.@refill - -@item @code{@@setchapternewpage on} -Specify the single-sided heading format, with chapters on new pages.@refill - -@item @code{@@setchapternewpage off} -Cause @TeX{} to start a new chapter on the same page as the last page of -the preceding chapter, after skipping some vertical whitespace. Also -cause @TeX{} to typeset for single-sided printing. (You can override -the headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage odd} -Specify the double-sided heading format, with chapters on new pages.@refill -@end table - -@noindent -Texinfo lacks an @code{@@setchapternewpage even} command.@refill - -@node Custom Headings -@comment node-name, next, previous, up -@section 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. - -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 - -Write custom heading specifications in the Texinfo file immediately -after the @code{@@end titlepage} command. -You must cancel the predefined heading commands with the -@code{@@headings off} command before defining your own -specifications. - -@need 1000 -Here is how to tell @TeX{} to place the chapter name at the left, the -page number in the center, and the date at the right of every header -for both even- and odd-numbered pages: - -@example -@group -@@headings off -@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} -@end group -@end example - -@noindent -You need to divide the left part from the central part and the central -part from the right part by inserting @samp{@@|} between parts. -Otherwise, the specification command will not be able to tell where -the text for one part ends and the next part begins. - -Each part can contain text or @@-commands. The text -is printed as if the part were within an ordinary paragraph in the -body of the page. The @@-commands replace -themselves with the page number, date, chapter name, or -whatever. - -@need 950 -Here are the six heading and footing commands: - -@table @code -@item @@everyheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} -@findex everyheading -@findex everyfooting -The `every' commands specify the format for both even- and odd-numbered -pages. These commands are for documents that are printed on one side -of each sheet of paper, or for documents in which you want symmetrical -headers or footers. - -@item @@evenheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} -@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} -@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} -@findex evenheading -@findex evenfooting -@findex oddheading -@findex oddfooting -The `even' and `odd' commands specify the format for even-numbered -pages and odd-numbered pages. These commands are for books and -manuals that are printed on both sides of each sheet of paper. -@end table - -Use the @samp{@@this@dots{}} series of @@-commands to -provide the names of chapters -and sections and the page number. You can use the -@samp{@@this@dots{}} commands in the left, center, or right portions -of headers and footers, or anywhere else in a Texinfo file so long as -they are between @code{@@iftex} and @code{@@end iftex} commands. - -@need 1000 -Here are the @samp{@@this@dots{}} commands: - -@table @code -@item @@thispage -@findex thispage -Expands to the current page number. - -@item @@thissectionname -@findex thissectionname -Expands to the name of the current section. - -@item @@thissectionnum -@findex thissectionnum -Expands to the number of the current section. - -@item @@thissection -@findex thissection -Expands to the number and name of the current section, in the format -`Section 1: Title'. - -@item @@thischaptername -@findex thischaptername -Expands to the name of the current chapter. - -@item @@thischapternum -@findex thischapternum -Expands to the number of the current chapter, or letter of the current -appendix. - -@item @@thischapter -@findex thischapter -Expands to the number and name of the current -chapter, in the format `Chapter 1: Title'. - -@item @@thistitle -@findex thistitle -Expands to the name of the document, as specified by the -@code{@@settitle} command. - -@item @@thisfile -@findex thisfile -For @code{@@include} files only: expands to the name of the current -@code{@@include} file. If the current Texinfo source file is not an -@code{@@include} file, this command has no effect. This command does -@emph{not} provide the name of the current Texinfo source file unless -it is an @code{@@include} file. (@xref{Include Files}, for more -information about @code{@@include} files.) -@end table - -@noindent -You can also use the @code{@@today@{@}} command, which expands to the -current date, in `1 Jan 1900' format. -@findex today - -Other @@-commands and text are printed in a header or footer just as -if they were in the body of a page. It is useful to incorporate text, -particularly when you are writing drafts: - -@example -@group -@@headings off -@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter -@@everyfooting @@| @@| Version: 0.27: @@today@{@} -@end group -@end example - -Beware of overlong titles: they may overlap another part of the -header or footer and blot it out. - -If you have very short chapters and/or sections, several of them can -appear on a single page. You can specify which chapters and sections -you want @code{@@thischapter}, @code{@@thissection} and other such -macros to refer to on such pages as follows: - -@table @code -@item @@everyheadingmarks @var{ref} -@itemx @@everyfootingmarks @var{ref} -@findex everyheadingmarks -@findex everyfootingmarks -The @var{ref} argument can be either @code{top} (the @code{@@this...} -commands will refer to the chapter/section at the top of a page) or -@code{bottom} (the commands will reflect the situation at the bottom -of a page). These @samp{@@every...} commands specify what to do on -both even- and odd-numbered pages. - -@item @@evenheadingmarks @var{ref} -@itemx @@oddheadingmarks @var{ref} -@itemx @@evenfootingmarks @var{ref} -@itemx @@oddfootingmarks @var{ref} -@findex evenheadingmarks -@findex oddheadingmarks -@findex evenfootingmarks -@findex oddfootingmarks -These @samp{@@even...} and @samp{@@odd...} commands specify what to do -on only even- or odd-numbered pages, respectively. The @var{ref} -argument is the same as with the @samp{@@every...} commands. -@end table - -Write these commands immediately after the @code{@@...contents} -commands, or after the @code{@@end titlepage} command if you don't -have a table of contents or if it is printed at the end of your -manual. - -By default the @code{@@this...} commands reflect the situation at the -bottom of a page both in headings and in footings. - - -@node Catching Mistakes -@appendix Formatting Mistakes -@cindex Structure, catching mistakes in -@cindex Nodes, catching mistakes -@cindex Catching mistakes -@cindex Correcting mistakes -@cindex Mistakes, catching -@cindex Problems, catching -@cindex Debugging the Texinfo structure - -Besides mistakes in the content of your documentation, there are two -kinds of mistake you can make with Texinfo: you can make mistakes with -@@-commands, and you can make mistakes with the structure of the nodes -and chapters. - -Emacs has two tools for catching the @@-command mistakes and two for -catching structuring mistakes.@refill - -For finding problems with @@-commands, you can run @TeX{} or a region -formatting command on the region that has a problem; indeed, you can -run these commands on each region as you write it.@refill - -For finding problems with the structure of nodes and chapters, you can use -@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} -command and you can use the @kbd{M-x Info-validate} command.@refill - -@menu -* makeinfo Preferred:: @code{makeinfo} finds errors. -* Debugging with Info:: How to catch errors with Info formatting. -* Debugging with TeX:: How to catch errors with @TeX{} formatting. -* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. -@end menu - - -@node makeinfo Preferred -@section @code{makeinfo} Find Errors - -The @code{makeinfo} program does an excellent job of catching errors -and reporting them---far better than @code{texinfo-format-region} or -@code{texinfo-format-buffer}. In addition, the various functions for -automatically creating and updating node pointers and menus remove -many opportunities for human error.@refill - -If you can, use the updating commands to create and insert pointers -and menus. These prevent many errors. Then use @code{makeinfo} (or -its Texinfo mode manifestations, @code{makeinfo-region} and -@code{makeinfo-buffer}) to format your file and check for other -errors. This is the best way to work with Texinfo. But if you -cannot use @code{makeinfo}, or your problem is very puzzling, then you -may want to use the tools described in this appendix.@refill - -@node Debugging with Info -@comment node-name, next, previous, up -@section Catching Errors with Info Formatting -@cindex Catching errors with Info formatting -@cindex Debugging with Info formatting - -After you have written part of a Texinfo file, you can use the -@code{texinfo-format-region} or the @code{makeinfo-region} command to -see whether the region formats properly.@refill - -Most likely, however, you are reading this section because for some -reason you cannot use the @code{makeinfo-region} command; therefore, the -rest of this section presumes that you are using -@code{texinfo-format-region}.@refill - -If you have made a mistake with an @@-command, -@code{texinfo-format-region} will stop processing at or after the -error and display an error message. To see where in the buffer the -error occurred, switch to the @samp{*Info Region*} buffer; the cursor -will be in a position that is after the location of the error. Also, -the text will not be formatted after the place where the error -occurred (or more precisely, where it was detected).@refill - -For example, if you accidentally end a menu with the command @code{@@end -menus} with an `s' on the end, instead of with @code{@@end menu}, you -will see an error message that says:@refill - -@example -@@end menus is not handled by texinfo -@end example - -@noindent -The cursor will stop at the point in the buffer where the error -occurs, or not long after it. The buffer will look like this:@refill - -@example -@group ----------- Buffer: *Info Region* ---------- -* Menu: - -* Using texinfo-show-structure:: How to use - `texinfo-show-structure' - to catch mistakes. -* Running Info-Validate:: How to check for - unreferenced nodes. -@@end menus -@point{} ----------- Buffer: *Info Region* ---------- -@end group -@end example - -The @code{texinfo-format-region} command sometimes provides slightly -odd error messages. For example, the following cross reference fails to format:@refill - -@example -(@@xref@{Catching Mistakes, for more info.) -@end example - -@noindent -In this case, @code{texinfo-format-region} detects the missing closing -brace but displays a message that says @samp{Unbalanced parentheses} -rather than @samp{Unbalanced braces}. This is because the formatting -command looks for mismatches between braces as if they were -parentheses.@refill - -Sometimes @code{texinfo-format-region} fails to detect mistakes. For -example, in the following, the closing brace is swapped with the -closing parenthesis:@refill - -@example -(@@xref@{Catching Mistakes), for more info.@} -@end example - -@noindent -Formatting produces: -@example -(*Note for more info.: Catching Mistakes) -@end example - -The only way for you to detect this error is to realize that the -reference should have looked like this:@refill - -@example -(*Note Catching Mistakes::, for more info.) -@end example - -Incidentally, if you are reading this node in Info and type @kbd{f -@key{RET}} (@code{Info-follow-reference}), you will generate an error -message that says: - -@example -No such node: "Catching Mistakes) The only way @dots{} -@end example - -@noindent -This is because Info perceives the example of the error as the first -cross reference in this node and if you type a @key{RET} immediately -after typing the Info @kbd{f} command, Info will attempt to go to the -referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info -will complete the node name of the correctly written example and take -you to the `Catching Mistakes' node. (If you try this, you can return -from the `Catching Mistakes' node by typing @kbd{l} -(@code{Info-last}).) - -@c !!! section on using Elisp debugger ignored. -@ignore -Sometimes @code{texinfo-format-region} will stop long after the -original error; this is because it does not discover the problem until -then. In this case, you will need to backtrack.@refill - -@c menu -@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. -@c end menu - -@c node Using the Emacs Lisp Debugger -@c appendixsubsec Using the Emacs Lisp Debugger -@c index Using the Emacs Lisp debugger -@c index Emacs Lisp debugger -@c index Debugger, using the Emacs Lisp - -If an error is especially elusive, you can turn on the Emacs Lisp -debugger and look at the backtrace; this tells you where in the -@code{texinfo-format-region} function the problem occurred. You can -turn on the debugger with the command:@refill - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} -@end example - -@noindent -and turn it off with - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} -@end example - -Often, when you are using the debugger, it is easier to follow what is -going on if you use the Emacs Lisp files that are not byte-compiled. -The byte-compiled sources send octal numbers to the debugger that may -look mysterious. To use the uncompiled source files, load -@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} -command.@refill - -The debugger will not catch an error if @code{texinfo-format-region} -does not detect one. In the example shown above, -@code{texinfo-format-region} did not find the error when the whole -list was formatted, but only when part of the list was formatted. -When @code{texinfo-format-region} did not find an error, the debugger -did not find one either. @refill - -However, when @code{texinfo-format-region} did report an error, it -invoked the debugger. This is the backtrace it produced:@refill - -@example ----------- Buffer: *Backtrace* ---------- -Signalling: (search-failed "[@},]") - re-search-forward("[@},]") - (while ...) - (let ...) - texinfo-format-parse-args() - (let ...) - texinfo-format-xref() - funcall(texinfo-format-xref) - (if ...) - (let ...) - (if ...) - (while ...) - texinfo-format-scan() - (save-excursion ...) - (let ...) - texinfo-format-region(103370 103631) -* call-interactively(texinfo-format-region) ----------- Buffer: *Backtrace* ---------- -@end example - -The backtrace is read from the bottom up. -@code{texinfo-format-region} was called interactively; and it, in -turn, called various functions, including @code{texinfo-format-scan}, -@code{texinfo-format-xref} and @code{texinfo-format-parse-args}. -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 -@end ignore - -@node Debugging with TeX -@comment node-name, next, previous, up -@section Catching Errors with @TeX{} Formatting -@cindex Catching errors with @TeX{} formatting -@cindex Debugging with @TeX{} formatting - -You can also catch mistakes when you format a file with @TeX{}.@refill - -Usually, you will want to do this after you have run -@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on -the same file, because @code{texinfo-format-buffer} sometimes displays -error messages that make more sense than @TeX{}. (@xref{Debugging -with Info}, for more information.)@refill - -For example, @TeX{} was run on a Texinfo file, part of which is shown -here:@refill - -@example ----------- Buffer: texinfo.texi ---------- -name of the Texinfo file as an extension. The -@@samp@{??@} are `wildcards' that cause the shell to -substitute all the raw index files. (@@xref@{sorting -indices, for more information about sorting -indices.)@@refill ----------- Buffer: texinfo.texi ---------- -@end example - -@noindent -(The cross reference lacks a closing brace.) -@TeX{} produced the following output, after which it stopped:@refill - -@example ----------- Buffer: *tex-shell* ---------- -Runaway argument? -@{sorting indices, for more information about sorting -indices.) @@refill @@ETC. -! Paragraph ended before @@xref was complete. -<to be read again> - @@par -l.27 - -? ----------- Buffer: *tex-shell* ---------- -@end example - -In this case, @TeX{} produced an accurate and -understandable error message: - -@example -Paragraph ended before @@xref was complete. -@end example - -@noindent -@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. -@samp{l.27} means that @TeX{} detected the problem on line 27 of the -Texinfo file. The @samp{?} is the prompt @TeX{} uses in this -circumstance.@refill - -Unfortunately, @TeX{} is not always so helpful, and sometimes you must -truly be a Sherlock Holmes to discover what went wrong.@refill - -In any case, if you run into a problem like this, you can do one of three -things.@refill - -@enumerate -@item -You can tell @TeX{} to continue running and ignore just this error by -typing @key{RET} at the @samp{?} prompt.@refill - -@item -You can tell @TeX{} to continue running and to ignore all errors as best -it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill - -This is often the best thing to do. However, beware: the one error -may produce a cascade of additional error messages as its consequences -are felt through the rest of the file. To stop @TeX{} when it is -producing such an avalanche of error messages, type @kbd{C-c} (or -@kbd{C-c C-c}, if you are running a shell inside Emacs). - -@item -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. - -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 -but @TeX{} is able to continue processing anyhow. For example, if you fail -to end an itemized list with the @code{@@end itemize} command, @TeX{} will -write a DVI file that you can print out. The only error message that -@TeX{} will give you is the somewhat mysterious comment that@refill - -@example -(@@end occurred inside a group at level 1) -@end example - -@noindent -However, if you print the DVI file, you will find that the text -of the file that follows the itemized list is entirely indented as if -it were part of the last item in the itemized list. The error message -is the way @TeX{} says that it expected to find an @code{@@end} -command somewhere in the file; but that it could not determine where -it was needed.@refill - -Another source of notoriously hard-to-find errors is a missing -@code{@@end group} command. If you ever are stumped by -incomprehensible errors, look for a missing @code{@@end group} command -first.@refill - -If the Texinfo file lacks header lines, -@TeX{} may stop in the -beginning of its run and display output that looks like the following. -The @samp{*} indicates that @TeX{} is waiting for input.@refill - -@example -This is TeX, Version 3.14159 (Web2c 7.0) -(test.texinfo [1]) -* -@end example - -@noindent -In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then -write the header lines in the Texinfo file and run the @TeX{} command -again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} -instead of @samp{@@}; and in this circumstance, you are working -directly with @TeX{}, not with Texinfo.)@refill - -@node Using texinfo-show-structure -@comment node-name, next, previous, up -@section Using @code{texinfo-show-structure} -@cindex Showing the structure of a file -@findex texinfo-show-structure - -It is not always easy to keep track of the nodes, chapters, sections, and -subsections of a Texinfo file. This is especially true if you are revising -or adding to a Texinfo file that someone else has written.@refill - -In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} -command lists all the lines that begin with the @@-commands that -specify the structure: @code{@@chapter}, @code{@@section}, -@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} -as prefix argument, if interactive), -the command also shows the @code{@@node} lines. The -@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in -Texinfo mode, by default.@refill - -The lines are displayed in a buffer called the @samp{*Occur*} buffer, -indented by hierarchical level. For example, here is a part of what was -produced by running @code{texinfo-show-structure} on this manual:@refill - -@example -@group -Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| -unnum\\|major\\|chapheading \\|heading \\|appendix\\)" -in buffer texinfo.texi. -@dots{} -4177:@@chapter Nodes -4198: @@heading Two Paths -4231: @@section Node and Menu Illustration -4337: @@section The @@code@{@@@@node@} Command -4393: @@subheading Choosing Node and Pointer Names -4417: @@subsection How to Write an @@code@{@@@@node@} Line -4469: @@subsection @@code@{@@@@node@} Line Tips -@dots{} -@end group -@end example - -This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin -with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} -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 -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}, -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 -how the example used above was generated. (To see the whole buffer -again, use @kbd{C-x n w} (@code{widen}).)@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 lines beginning with -@code{@@node} as well as the lines beginning with the @@-sign commands -for @code{@@chapter}, @code{@@section}, and the like.@refill - -You can remind yourself of the structure of a Texinfo file by looking at -the list in the @samp{*Occur*} window; and if you have mis-named a node -or left out a section, you can correct the mistake.@refill - -@node Using occur -@comment node-name, next, previous, up -@section Using @code{occur} -@cindex Occurrences, listing with @code{@@occur} -@findex occur - -Sometimes the @code{texinfo-show-structure} command produces too much -information. Perhaps you want to remind yourself of the overall structure -of a Texinfo file, and are overwhelmed by the detailed list produced by -@code{texinfo-show-structure}. In this case, you can use the @code{occur} -command directly. To do this, type@refill - -@example -@kbd{M-x occur} -@end example - -@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 - -For example, to see all the lines that contain the word -@samp{@@chapter} in them, just type @samp{@@chapter}. This will -produce a list of the chapters. It will also list all the sentences -with @samp{@@chapter} in the middle of the line.@refill - -If you want to see only those lines that start with the word -@samp{@@chapter}, type @samp{^@@chapter} when prompted by -@code{occur}. If you want to see all the lines that end with a word -or phrase, end the last word with a @samp{$}; for example, -@samp{catching mistakes$}. This can be helpful when you want to see -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}, -for more information.@refill - -@node Running Info-Validate -@comment node-name, next, previous, up -@section Finding Badly Referenced Nodes -@findex Info-validate -@cindex Nodes, checking for badly referenced -@cindex Checking for badly referenced nodes -@cindex Looking for badly referenced nodes -@cindex Finding badly referenced nodes -@cindex Badly referenced nodes - -You can use the @code{Info-validate} command to check whether any of -the `Next', `Previous', `Up' or other node pointers fail to point to a -node. This command checks that every node pointer points to an -existing node. The @code{Info-validate} command works only on Info -files, not on Texinfo files.@refill - -The @code{makeinfo} program validates pointers automatically, so you -do not need to use the @code{Info-validate} command if you are using -@code{makeinfo}. You only may need to use @code{Info-validate} if you -are unable to run @code{makeinfo} and instead must create an Info file -using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or -if you write an Info file from scratch.@refill - -@menu -* Using Info-validate:: How to run @code{Info-validate}. -* Unsplit:: How to create an unsplit file. -* Tagifying:: How to tagify a file. -* Splitting:: How to split a file manually. -@end menu - -@node Using Info-validate -@subsection Running @code{Info-validate} -@cindex Running @code{Info-validate} -@cindex Info validating a large file -@cindex Validating a large file - -To use @code{Info-validate}, visit the Info file you wish to check and -type:@refill - -@example -M-x Info-validate -@end example - -@noindent -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}. - -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, -error messages will be displayed in a buffer called @samp{*problems in -info file*}.@refill - -For example, @code{Info-validate} was run on a test file that contained -only the first node of this manual. One of the messages said:@refill - -@example -In node "Overview", invalid Next: Texinfo Mode -@end example - -@noindent -This meant that the node called @samp{Overview} had a `Next' pointer that -did not point to anything (which was true in this case, since the test file -had only one node in it).@refill - -Now suppose we add a node named @samp{Texinfo Mode} to our test case -but we do not specify a `Previous' for this node. Then we will get -the following error message:@refill - -@example -In node "Texinfo Mode", should have Previous: Overview -@end example - -@noindent -This is because every `Next' pointer should be matched by a -`Previous' (in the node where the `Next' points) which points back.@refill - -@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. - -@node Unsplit -@comment node-name, next, previous, up -@subsection Creating an Unsplit File -@cindex Creating an unsplit file -@cindex Unsplit file creation - -You can run @code{Info-validate} only on a single Info file that has a -tag table. The command will not work on the indirect subfiles that -are generated when a master file is split. If you have a large file -(longer than 300,000 bytes or so), you need to run the -@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such -a way that it does not create indirect subfiles. You will also need -to create a tag table for the Info file. After you have done this, -you can run @code{Info-validate} and look for badly referenced -nodes.@refill - -The first step is to create an unsplit Info file. To prevent -@code{texinfo-format-buffer} from splitting a Texinfo file into -smaller Info files, give a prefix to the @kbd{M-x -texinfo-format-buffer} command:@refill - -@example -C-u M-x texinfo-format-buffer -@end example - -@noindent -or else - -@example -C-u C-c C-e C-b -@end example - -@noindent -When you do this, Texinfo will not split the file and will not create -a tag table for it. @refill -@cindex Making a tag table manually -@cindex Tag table, making manually - -@node Tagifying -@subsection 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 - -@example -M-x Info-tagify -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an -Info file with a tag table that you can validate.@refill - -The third step is to validate the Info file:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-validate}.) -In brief, the steps are:@refill - -@example -@group -C-u M-x texinfo-format-buffer -M-x Info-tagify -M-x Info-validate -@end group -@end example - -After you have validated the node structure, you can rerun -@code{texinfo-format-buffer} in the normal way so it will construct a -tag table and split the file automatically, or you can make the tag -table and split the file manually.@refill - -@node Splitting -@comment node-name, next, previous, up -@subsection 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 - -The split-off files are called the indirect subfiles.@refill - -Info files are split to save memory. With smaller files, Emacs does not -have make such a large buffer to hold the information.@refill - -If an Info file has more than 30 nodes, you should also make a tag -table for it. @xref{Using Info-validate}, for information -about creating a tag table. (Again, tag tables are usually created -automatically by the formatting command; you only need to create a tag -table yourself if you are doing the job manually. Most likely, you -will do this for a large, unsplit file on which you have run -@code{Info-validate}.)@refill - -@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 -@ignore -Before running @code{Info-split}, you need to load the @code{info} library -into Emacs by giving the command @kbd{M-x load-library @key{RET} info -@key{RET}}. -@end ignore - -Visit the Info file you wish to tagify and split and type the two -commands:@refill - -@example -M-x Info-tagify -M-x Info-split -@end example - -@noindent -(Note that the @samp{I} in @samp{Info} is upper case.)@refill - -When you use the @code{Info-split} command, the buffer is modified into a -(small) Info file which lists the indirect subfiles. This file should be -saved in place of the original visited file. The indirect subfiles are -written in the same directory the original file is in, with names generated -by appending @samp{-} and a number to the original file name.@refill - -The primary file still functions as an Info file, but it contains just -the tag table and a directory of subfiles.@refill - - -@ignore -The simple description in the command summary seems sufficient to me -these days, so ignore this appendix. --karl, 13mar04. - -@node Refilling Paragraphs -@appendix Refilling Paragraphs -@cindex Refilling paragraphs -@cindex Filling paragraphs -@cindex Paragraphs, filling -@findex refill - -The @code{@@refill} command refills and, optionally, indents the first -line of a paragraph.@footnote{Perhaps the command should have been -called the @code{@@refillandindent} command, but @code{@@refill} is -shorter and the name was chosen before indenting was possible.} The -@code{@@refill} command is no longer important, but we describe it here -because you once needed it. You will see it in many old Texinfo -files.@refill - -Without refilling, paragraphs containing long @@-constructs may look -bad after formatting because the formatter removes @@-commands and -shortens some lines more than others. In the past, neither the -@code{texinfo-format-region} command nor the -@code{texinfo-format-buffer} command refilled paragraphs -automatically. The @code{@@refill} command had to be written at the -end of every paragraph to cause these formatters to fill them. (Both -@TeX{} and @code{makeinfo} have always refilled paragraphs -automatically.) Now, all the Info formatters automatically fill and -indent those paragraphs that need to be filled and indented.@refill - -The @code{@@refill} command causes @code{texinfo-format-region} and -@code{texinfo-format-buffer} to refill a paragraph in the Info file -@emph{after} all the other processing has been done. For this reason, -you can not use @code{@@refill} with a paragraph containing either -@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will -override those two commands.@refill - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands now automatically append @code{@@refill} to the end of each -paragraph that should be filled. They do not append @code{@@refill} to -the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} -and therefore do not refill or indent them.@refill - -@end ignore - - -@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 -@c node New Features, Command and Variable Index, Obtaining TeX, Top -@c appendix Second Edition Features - -@tex -% Widen the space for the first column so three control-character -% strings fit in the first column. Switched back to default .8in -% value at end of chapter. -\global\tableindent=1.0in -@end tex - -The second edition of the Texinfo manual describes more than 20 new -Texinfo mode commands and more than 50 previously undocumented Texinfo -@@-commands. This edition is more than twice the length of the first -edition.@refill - -Here is a brief description of the new commands.@refill - -@c menu -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@c end menu - -@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX -@c appendixsec New Texinfo Mode Commands - -Texinfo mode provides commands and features especially designed for -working with Texinfo files. More than 20 new commands have been -added, including commands for automatically creating and updating -both nodes and menus. This is a tedious task when done by hand.@refill - -The keybindings are intended to be somewhat mnemonic.@refill - -@c subheading Update all nodes and menus - -The @code{texinfo-master-menu} command is the primary command: - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -Create or update a master menu. -With @kbd{C-u} as a prefix argument, -first create or update all nodes -and regular menus. -@end table - -@c subheading Update Pointers - -@noindent -Create or update `Next', `Previous', and `Up' node pointers.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -Update a node. - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -Update every node in the buffer. -@end table - -@c subheading Update Menus - -@noindent -Create or update menus.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -Make or update a menu. - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -Make or update all the menus in a buffer. -With @kbd{C-u} as a prefix argument, -first update all the nodes. -@end table - -@c subheading Insert Title as Description - -@noindent -Insert a node's chapter or section title in the space for the -description in a menu entry line; position point so you can edit the -insert. (This command works somewhat differently than the other -insertion commands, which insert only a predefined string.)@refill - -@noindent -@xref{Inserting, Inserting Frequently Used Commands}. - -@table @kbd -@item C-c C-c C-d -Insert title. -@end table - -@c subheading Format for Info - -@noindent -Provide keybindings both for the Info formatting commands that are -written in Emacs Lisp and for @code{makeinfo} that is written in -C.@refill - -@noindent -@xref{Info Formatting}. - -@noindent -Use the Emacs lisp @code{texinfo-format@dots{}} commands: - -@table @kbd -@item C-c C-e C-r -Format the region. - -@item C-c C-e C-b -Format the buffer. -@end table - -@noindent -Use @code{makeinfo}: - -@table @kbd -@item C-c C-m C-r -Format the region. - -@item C-c C-m C-b -Format the buffer. - -@item C-c C-m C-l -Recenter the @code{makeinfo} output buffer. - -@item C-c C-m C-k -Kill the @code{makeinfo} formatting job. -@end table - -@c subheading Typeset and Print - -@noindent -Typeset and print Texinfo documents from within Emacs. - -@noindent -@xref{Printing}. - -@table @kbd -@item C-c C-t C-b -Run @code{texi2dvi} on the buffer. - -@item C-c C-t C-r -Run @TeX{} on the region. - -@item C-c C-t C-i -Run @code{texindex}. - -@item C-c C-t C-p -Print the DVI file. - -@item C-c C-t C-q -Show the print queue. - -@item C-c C-t C-d -Delete a job from the print queue. - -@item C-c C-t C-k -Kill the current @TeX{} formatting job. - -@item C-c C-t C-x -Quit a currently stopped @TeX{} formatting job. - -@item C-c C-t C-l -Recenter the output buffer. -@end table - -@c subheading Other Updating Commands - -@noindent -The ``other updating commands'' do not have standard keybindings because -they are used less frequently.@refill - -@noindent -@xref{Other Updating Commands}. - -@table @kbd -@item M-x texinfo-insert-node-lines -Insert missing @code{@@node} lines using -section titles as node names. - -@item M-x texinfo-multiple-files-update -Update a multi-file document. -With a numeric prefix, such as @kbd{C-u 8}, -update @strong{every} pointer and -menu in @strong{all} the files and -then insert a master menu. - -@item M-x texinfo-indent-menu-description -Indent descriptions in menus. - -@item M-x texinfo-sequential-node-update -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 - -The second edition of the Texinfo manual describes more than 50 -commands that were not described in the first edition. A third or so -of these commands existed in Texinfo but were not documented in the -manual; the others are new. Here is a listing, with brief -descriptions of them:@refill - -@c subheading Indexing - -@noindent -Create your own index, and merge indices.@refill - -@noindent -@xref{Indices}. - -@table @kbd -@item @@defindex @var{index-name} -Define a new index and its indexing command. -See also the @code{@@defcodeindex} command. - -@c written verbosely to avoid overfull hbox -@item @@synindex @var{from-index} @var{into-index} -Merge the @var{from-index} index into the @var{into-index} index. -See also the @code{@@syncodeindex} command. -@end table - -@c subheading Definitions - -@noindent -Describe functions, variables, macros, -commands, user options, special forms, and other such artifacts in a -uniform format.@refill - -@noindent -@xref{Definition Commands}. - -@table @kbd -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -Format a description for functions, interactive -commands, and similar entities. - -@item @@defvr, @@defop, @dots{} -15 other related commands. -@end table - -@c subheading Glyphs - -@noindent -Indicate the results of evaluation, expansion, -printed output, an error message, equivalence of expressions, and the -location of point.@refill - -@noindent -@xref{Glyphs}. - -@table @kbd -@item @@equiv@{@} -@itemx @equiv{} -Equivalence: - -@item @@error@{@} -@itemx @error{} -Error message - -@item @@expansion@{@} -@itemx @expansion{} -Macro expansion - -@item @@point@{@} -@itemx @point{} -Position of point - -@item @@print@{@} -@itemx @print{} -Printed output - -@item @@result@{@} -@itemx @result{} -Result of an expression -@end table - -@c subheading Page Headings - -@noindent -Customize page headings. - -@noindent -@xref{Headings}. - -@table @kbd -@item @@headings @var{on-off-single-double} -Headings on or off, single, or double-sided. - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Footings for even-numbered (left-hand) pages. - -@item @@evenheading, @@everyheading, @@oddheading, @dots{} -Five other related commands. - -@item @@thischapter -Insert name of chapter and chapter number. - -@item @@thischaptername, @@thisfile, @@thistitle, @@thispage -Related commands. -@end table - -@c subheading Formatting - -@noindent -Format blocks of text. - -@noindent -@xref{Quotations and Examples}, and@* -@ref{Lists and Tables, , Making Lists and Tables}. - -@table @kbd -@item @@cartouche -Draw rounded box surrounding text (no effect in Info). - -@item @@enumerate @var{optional-arg} -Enumerate a list with letters or numbers. - -@item @@exdent @var{line-of-text} -Remove indentation. - -@item @@flushleft -Left justify. - -@item @@flushright -Right justify. - -@item @@format -Do not narrow nor change font. - -@item @@ftable @var{formatting-command} -@itemx @@vtable @var{formatting-command} -Two-column table with indexing. - -@item @@lisp -For an example of Lisp code. - -@item @@smallexample -@itemx @@smalllisp -Like @@table and @@lisp, but for (originally) @@smallbook. -@end table - -@c subheading Conditionals - -@noindent -Conditionally format text. - -@noindent -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@table @kbd -@item @@set @var{flag} [@var{string}] -Set a flag. Optionally, set value -of @var{flag} to @var{string}. - -@item @@clear @var{flag} -Clear a flag. - -@item @@value@{@var{flag}@} -Replace with value to which @var{flag} is set. - -@item @@ifset @var{flag} -Format, if @var{flag} is set. - -@item @@ifclear @var{flag} -Ignore, if @var{flag} is set. -@end table - -@c subheading @@heading series for Titles - -@noindent -Produce unnumbered headings that do not appear in a table of contents. - -@noindent -@xref{Structuring}. - -@table @kbd -@item @@heading @var{title} -Unnumbered section-like heading not listed -in the table of contents of a printed manual. - -@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading -Related commands. -@end table - -@need 1000 -@c subheading Font commands - -@need 1000 -@noindent -@xref{Smallcaps}, and @* -@ref{Fonts}. - -@table @kbd -@item @@r@{@var{text}@} -Print in roman font. - -@item @@sc@{@var{text}@} -Print in @sc{small caps} font. -@end table - -@c subheading Miscellaneous - -@noindent -See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* -see @ref{Customized Highlighting},@* -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{minus, , Inserting a Minus Sign},@* -see @ref{paragraphindent, , Paragraph Indenting},@* -see @ref{Cross Reference Commands},@* -see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* -see @ref{Custom Headings, , How to Make Your Own Headings}. - -@table @kbd -@item @@author @var{author} -Typeset author's name. - -@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -@c Define a highlighting command for Info. (Info only.) - -@item @@finalout -Produce cleaner printed output. - -@item @@footnotestyle @var{end-or-separate} -Specify footnote style. - -@item @@dmn@{@var{dimension}@} -Format a dimension. - -@item @@global@@let@var{new-cmd}=@var{existing-cmd} -Define a highlighting command for @TeX{}. (@TeX{} only.) - -@item @@lowersections -Reduce hierarchical level of sectioning commands. - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. - -@item @@minus@{@} -Generate a minus sign. - -@item @@paragraphindent @var{asis-or-number} -Specify paragraph indentation. - -@item @@raisesections -Raise hierarchical level of sectioning commands. - -@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} -Make a reference. In the printed manual, the -reference does not start with the word `see'. - -@item @@title @var{title} -Typeset @var{title} in the alternative -title page format. - -@item @@subtitle @var{subtitle} -Typeset @var{subtitle} in the alternative -title page format. - -@item @@today@{@} -Insert the current date. -@end table -@tex -% Switch width of first column of tables back to default value -\global\tableindent=.8in -@end tex -@end ignore - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include fdl.texi - - -@node Command and Variable Index -@unnumbered Command and Variable Index - -This is an alphabetical list of all the @@-commands, assorted Emacs Lisp -functions, and several variables. To make the list easier to use, the -commands are listed without their preceding @samp{@@}.@refill - -@printindex fn - - -@node General Index -@unnumbered General Index - -@printindex cp - - -@bye diff --git a/Build/source/utils/texinfo/doc/txi-cs.tex b/Build/source/utils/texinfo/doc/txi-cs.tex deleted file mode 100644 index 999e404cd0f..00000000000 --- a/Build/source/utils/texinfo/doc/txi-cs.tex +++ /dev/null @@ -1,73 +0,0 @@ -% $Id: txi-cs.tex,v 1.5 2007/07/01 19:06:03 karl Exp $ -% Czech translation for texinfo.tex. -% -% Copyright (C) 1999, 2000, 2007 Free Software Foundation. -% -% Authors: -% Vladimir Michl <Vladimir.Michl@mujweb.cz> -% Stepan Kasal <kasal@ucw.cz> -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -\gdef\putwordAppendix{Pøílohy} -\gdef\putwordChapter{Kapitola} -\gdef\putwordfile{soubor} -\gdef\putwordin{v~knize} -\gdef\putwordIndexIsEmpty{(Rejstøík je prázdný.)} -\gdef\putwordIndexNonexistent{(Rejstøík neexistuje.)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Promìnná pro instance tøídy} -\gdef\putwordMethodon{Metoda tøídy} -\gdef\putwordNoTitle{Bez nadpisu} -\gdef\putwordof{tøídy} -\global\let\putwordon\putwordof -\gdef\putwordpage{stránka} -\gdef\putwordsection{oddíl} -\gdef\putwordSection{Oddíl} -\gdef\putwordsee{viz} -\gdef\putwordSee{Viz} -\gdef\putwordShortTOC{Struèný obsah} -\gdef\putwordTOC{Obsah} -% -\gdef\putwordMJan{ledna} -\gdef\putwordMFeb{února} -\gdef\putwordMMar{bøezna} -\gdef\putwordMApr{dubna} -\gdef\putwordMMai{kvìtna} -\gdef\putwordMJun{èervna} -\gdef\putwordMJul{èervence} -\gdef\putwordMAug{srpna} -\gdef\putwordMSep{záøí} -\gdef\putwordMOct{øíjna} -\gdef\putwordMNov{listopadu} -\gdef\putwordMDec{prosince} -% -\gdef\putwordDefmac{Makro} -\gdef\putwordDefspec{Speciální forma} -\gdef\putwordDefvar{Promìnná} -\gdef\putwordDefopt{Volby} -\gdef\putwordDeffunc{Funkce} -% -% Redefine \today to produce Czech -% preferred dates such as 28. januar 1999. -% -\gdef\today{% - \number\day.\nobreak\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMai\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \penalty3000\relax\space\number\year} -% diff --git a/Build/source/utils/texinfo/doc/txi-de.tex b/Build/source/utils/texinfo/doc/txi-de.tex deleted file mode 100644 index 275429bb4b0..00000000000 --- a/Build/source/utils/texinfo/doc/txi-de.tex +++ /dev/null @@ -1,78 +0,0 @@ -% txi-de.tex -- adaptation to German for texinfo.tex. -% $Id: txi-de.tex,v 1.7 2007/07/01 22:32:12 karl Exp $ -% -% Copyright (C) 1999, 2007 Free Software Foundation, Inc. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the license, or (at -% your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% Written by Karl Heinz Marbaise, 18. January 1999, <kama@hippo.fido.de> -%% -%% german translation of the used words. -%% Don't use checking because if it is our turn they have -%% been defined. -\gdef\putwordAppendix{Anhang} -\gdef\putwordChapter{Kapitel} -\gdef\putwordfile{Datei} -\gdef\putwordin{in} -\gdef\putwordInfo{Info} -\gdef\putwordMethodon{Methode von} -\gdef\putwordon{auf} -\gdef\putwordof{von} -\gdef\putwordpage{Seite} -\gdef\putwordsection{Abschnitt} -\gdef\putwordSection{Abschnitt} -\gdef\putwordsee{siehe} -\gdef\putwordSee{Siehe} -\gdef\putwordShortTOC{Kurzverzeichnis} -\gdef\putwordTOC{Inhaltsverzeichnis} -%% -\gdef\putwordNoTitle{Kein Titel} -%% -%% New defintion for the output of months. -\gdef\putwordMJan{Januar} -\gdef\putwordMFeb{Februar} -\gdef\putwordMMar{M\"arz} -\gdef\putwordMApr{April} -\gdef\putwordMMai{Mai} -\gdef\putwordMJun{Juni} -\gdef\putwordMJul{Juli} -\gdef\putwordMAug{August} -\gdef\putwordMSep{September} -\gdef\putwordMOct{Oktober} -\gdef\putwordMNov{November} -\gdef\putwordMDec{Dezember} -%% -%% some hyphenation for german language. Might be changed. -\hyphenation{An-hang} -%%\hyphenation{mini-buf-fer mini-buf-fers} -%%\hyphenation{eshell} -%%\hyphenation{white-space} -%% -%% Index handling should also work correct in german -\gdef\putwordIndexNonexistent{(Index ist nicht vorhanden)} -\gdef\putwordIndexIsEmpty{(Der Index ist leer)} -%% -%% \defmac -\gdef\putwordDefmac{Makro} -%% \defspec -\gdef\putwordDefspec{Spezial Form} -%% \defivar -\gdef\putwordDefivar{exemplar Variable} -%% \defvar leave unchanged because no difference in -%% writing but in phonectics. -\gdef\putwordDefvar{Variable} -%% \defopt -\gdef\putwordDefopt{Benutzer Option} -%% \deffun -\gdef\putwordDeffunc{Funktion} diff --git a/Build/source/utils/texinfo/doc/txi-en.tex b/Build/source/utils/texinfo/doc/txi-en.tex deleted file mode 100644 index a81001c7be1..00000000000 --- a/Build/source/utils/texinfo/doc/txi-en.tex +++ /dev/null @@ -1,68 +0,0 @@ -% English non-translation for texinfo.tex. This is read when a source -% document says @documentlanguage en (which might happen after another -% @documentlanguage). The actual values are the same as defaults. -% $Id: txi-en.tex,v 1.5 2007/07/01 19:06:03 karl Exp $ -% -% Copyright (C) 1999, 2007 Free Software Foundation. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. - -\gdef\putwordAppendix{Appendix} -\gdef\putwordChapter{Chapter} -\gdef\putwordfile{file} -\gdef\putwordin{in} -\gdef\putwordIndexIsEmpty{(Index is empty)} -\gdef\putwordIndexNonexistent{(Index is nonexistent)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Instance Variable of} -\gdef\putwordMethodon{Method on} -\gdef\putwordNoTitle{No Title} -\gdef\putwordof{of} -\gdef\putwordon{on} -\gdef\putwordpage{page} -\gdef\putwordsection{section} -\gdef\putwordSection{Section} -\gdef\putwordsee{see} -\gdef\putwordSee{See} -\gdef\putwordShortTOC{Short Contents} -\gdef\putwordTOC{Table of Contents} -% -\gdef\putwordMJan{January} -\gdef\putwordMFeb{February} -\gdef\putwordMMar{March} -\gdef\putwordMApr{April} -\gdef\putwordMMay{May} -\gdef\putwordMJun{June} -\gdef\putwordMJul{July} -\gdef\putwordMAug{August} -\gdef\putwordMSep{September} -\gdef\putwordMOct{October} -\gdef\putwordMNov{November} -\gdef\putwordMDec{December} -% -\gdef\putwordDefmac{Macro} -\gdef\putwordDefspec{Special Form} -\gdef\putwordDefvar{Variable} -\gdef\putwordDefopt{User Option} -\gdef\putwordDeffunc{Function} - -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-es.tex b/Build/source/utils/texinfo/doc/txi-es.tex deleted file mode 100644 index 54b399815fc..00000000000 --- a/Build/source/utils/texinfo/doc/txi-es.tex +++ /dev/null @@ -1,59 +0,0 @@ -% txi-es.tex -- TeX macros to handle Spanish language documents. -% -% Copyright (C) 1999, 2007 by Adrian Perez Jorge -% -% This txi-es.tex file is free software; you can redistribute it and/or -% modify it under the terms of the GNU General Public License as -% published by the Free Software Foundation; either version 3 of the -% License, or (at your option) any later version. -% -% This txi-es.tex file is distributed in the hope that it will be -% useful, but WITHOUT ANY WARRANTY; without even the implied warranty -% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -% General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% Set up fixed words for Spanish. -% - -\gdef\putwordAppendix{Ap\'endice} -\gdef\putwordChapter{Cap\'{\char16{}}tulo} -\gdef\putwordfile{archivo} -\gdef\putwordIndexIsEmpty{(El \'Indice est\'a vac\'{\char16{}}o)} -\gdef\putwordIndexNonexistent{(No existe el \'Indice)} -\gdef\putwordInfo{Info} -\gdef\putwordMethodon{M\'etodo de} -\gdef\putwordNoTitle{Sin T\'{\char{16}}tulo} -\gdef\putwordof{de} -\gdef\putwordon{de} -\gdef\putwordpage{p\'agina} -\gdef\putwordsection{secci\'on} -\gdef\putwordSection{Secci\'on} -\gdef\putwordsee{v\'ease} -\gdef\putwordSee{V\'ease} -\gdef\putwordShortTOC{Resumen del Contenido} -\gdef\putwordTOC{\'Indice General} -% -\gdef\putwordMJan{enero} -\gdef\putwordMFeb{febrero} -\gdef\putwordMMar{marzo} -\gdef\putwordMApr{abril} -\gdef\putwordMMay{mayo} -\gdef\putwordMJun{junio} -\gdef\putwordMJul{julio} -\gdef\putwordMAug{agosto} -\gdef\putwordMSep{septiembre} -\gdef\putwordMOct{octubre} -\gdef\putwordMNov{noviembre} -\gdef\putwordMDec{diciembre} -% -\gdef\putwordDefmac{Macro} -\gdef\putwordDefspec{Forma Especial} -\gdef\putwordDefivar{Variable de Instancia} -\gdef\putwordDefvar{Variable} -\gdef\putwordDefopt{Opci\'on de Usuario} -\gdef\putwordDeffunc{Funci\'on} - -\endinput diff --git a/Build/source/utils/texinfo/doc/txi-fr.tex b/Build/source/utils/texinfo/doc/txi-fr.tex deleted file mode 100644 index c8665cfcfa2..00000000000 --- a/Build/source/utils/texinfo/doc/txi-fr.tex +++ /dev/null @@ -1,72 +0,0 @@ -% txi-fr.tex -- TeX macros to handle French language for texinfo.tex documents. -% $Id: txi-fr.tex,v 1.5 2007/07/01 19:06:03 karl Exp $ -% -% Copyright (C) 1999, 2007 Free Software Foundation. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. - -% Set up fixed words for French. -% Translated by Laurent Bourbeau <bourbeau@progiciels-bpi.ca> -% Translation date: le 10 décembre 1999. -% Transmitted to: Karl Berry <karl@cs.umb.edu> - -\gdef\putwordAppendix{Annexe} -\gdef\putwordChapter{Chapitre} -\gdef\putwordfile{fichier} -\gdef\putwordin{dans} -\gdef\putwordIndexIsEmpty{(Index est vide)} -\gdef\putwordIndexNonexistent{(Index n'existe pas)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Variable d'instance de} -\gdef\putwordMethodon{M\'ethode sur} -\gdef\putwordNoTitle{Sans Titre} -\gdef\putwordof{de} -\gdef\putwordon{sur} -\gdef\putwordpage{page} -\gdef\putwordsection{section} -\gdef\putwordSection{Section} -\gdef\putwordsee{voir} -\gdef\putwordSee{Voir} -\gdef\putwordShortTOC{Sommaire} -\gdef\putwordTOC{Table des mati\`eres} -% -\gdef\putwordMJan{janvier} -\gdef\putwordMFeb{f\'evrier} -\gdef\putwordMMar{mars} -\gdef\putwordMApr{avril} -\gdef\putwordMMay{mai} -\gdef\putwordMJun{juin} -\gdef\putwordMJul{juillet} -\gdef\putwordMAug{ao\^ut} -\gdef\putwordMSep{septembre} -\gdef\putwordMOct{octobre} -\gdef\putwordMNov{novembre} -\gdef\putwordMDec{d\'ecembre} -% -\gdef\putwordDefmac{Macro} -\gdef\putwordDefspec{Forme Sp\'eciale} -\gdef\putwordDefvar{Variable} -\gdef\putwordDefopt{Option de l'usager} -\gdef\putwordDeffunc{Fonction} - -% Produces Day Month Year style of output. -% French datation - for instance: 10 janvier 2000. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-it.tex b/Build/source/utils/texinfo/doc/txi-it.tex deleted file mode 100644 index 6ba6bd82767..00000000000 --- a/Build/source/utils/texinfo/doc/txi-it.tex +++ /dev/null @@ -1,68 +0,0 @@ -% English non-translation for texinfo.tex. This is read when a source -% document says @documentlanguage en (which might happen after another -% @documentlanguage). The actual values are the same as defaults. -% $Id: txi-it.tex,v 1.5 2007/07/01 19:06:04 karl Exp $ -% -% Copyright (C) 1999, 2007 Free Software Foundation. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. - -\gdef\putwordAppendix{Appendice} -\gdef\putwordChapter{Capitolo} -\gdef\putwordfile{file} -\gdef\putwordin{in} -\gdef\putwordIndexIsEmpty{(L'indice \'e vuoto)} -\gdef\putwordIndexNonexistent{(L'indice non esiste)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Variabile di istanza di} -\gdef\putwordMethodon{Metodo di} -\gdef\putwordNoTitle{Nessun titolo} -\gdef\putwordof{di} -\gdef\putwordon{su} -\gdef\putwordpage{pagina} -\gdef\putwordsection{sezione} -\gdef\putwordSection{Sezione} -\gdef\putwordsee{vedi} -\gdef\putwordSee{Vedi} -\gdef\putwordShortTOC{Sommario abbreviato} -\gdef\putwordTOC{Sommario} -% -\gdef\putwordMJan{Gennaio} -\gdef\putwordMFeb{Febbraio} -\gdef\putwordMMar{Marzo} -\gdef\putwordMApr{Aprile} -\gdef\putwordMMay{Maggio} -\gdef\putwordMJun{Giugno} -\gdef\putwordMJul{Luglio} -\gdef\putwordMAug{Agosto} -\gdef\putwordMSep{Settembre} -\gdef\putwordMOct{Ottobre} -\gdef\putwordMNov{Novembre} -\gdef\putwordMDec{Dicembre} -% -\gdef\putwordDefmac{Macro} -\gdef\putwordDefspec{Forma speciale} -\gdef\putwordDefvar{Variabile} -\gdef\putwordDefopt{Opzione} -\gdef\putwordDeffunc{Funzione} - -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-nb.tex b/Build/source/utils/texinfo/doc/txi-nb.tex deleted file mode 100644 index 9007d155232..00000000000 --- a/Build/source/utils/texinfo/doc/txi-nb.tex +++ /dev/null @@ -1,67 +0,0 @@ -% Norwegian translation for texinfo.tex (1999-10-29, GNU Texinfo 4.0). -% Enables the use of words like Kapittel instead of Chapter, etc. -% -% Copyright (C) 1999, 2007 Trond Endrest=F8l <endrestol@hotmail.com> -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -\gdef\putwordAppendix{Vedlegg} -\gdef\putwordChapter{Kapittel} -\gdef\putwordfile{fil} -\gdef\putwordIndexIsEmpty{(Indeks er tom)} -\gdef\putwordIndexNonexistent{(Indeks eksisterer ikke)} -\gdef\putwordInfo{Info} -\gdef\putwordMethodon{Metode p\aa} -\gdef\putwordNoTitle{Ingen tittel} -\gdef\putwordof{av} -\gdef\putwordon{p\aa} -\gdef\putwordpage{side} -\gdef\putwordsection{avsnitt} -\gdef\putwordSection{Avsnitt} -\gdef\putwordsee{se} -\gdef\putwordSee{Se} -\gdef\putwordShortTOC{Kort innholdsfortegnelse} -\gdef\putwordTOC{Innholdsfortegnelse} -% -\gdef\putwordMJan{januar} -\gdef\putwordMFeb{februar} -\gdef\putwordMMar{mars} -\gdef\putwordMApr{april} -\gdef\putwordMMay{mai} -\gdef\putwordMJun{juni} -\gdef\putwordMJul{juli} -\gdef\putwordMAug{august} -\gdef\putwordMSep{september} -\gdef\putwordMOct{oktober} -\gdef\putwordMNov{november} -\gdef\putwordMDec{desember} -% -\gdef\putwordDefmac{Makro} -\gdef\putwordDefspec{Spesiell form} -\gdef\putwordDefivar{Forekomstvariabel} -\gdef\putwordDefvar{Variabel} -\gdef\putwordDefopt{Brukervalg} -\gdef\putwordDeffunc{Funksjon} -% -% Redefine \today to produce Norwegian -% preferred dates such as 28. januar 1999. -% -\gdef\today{% - \number\day.\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-nl.tex b/Build/source/utils/texinfo/doc/txi-nl.tex deleted file mode 100644 index 9cdfbe87146..00000000000 --- a/Build/source/utils/texinfo/doc/txi-nl.tex +++ /dev/null @@ -1,67 +0,0 @@ -% Dutch translation for texinfo.tex. -% $Id: txi-nl.tex,v 1.5 2007/07/01 19:06:04 karl Exp $ -% -% Copyright (C) 1999, 2007 Free Software Foundation. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. - -% Set up fixed words if not already set. -\gdef\putwordAppendix{Appendix} -\gdef\putwordChapter{Hoofdstuk} -\gdef\putwordfile{bestand} -\gdef\putwordin{in} -\gdef\putwordIndexIsEmpty{(Index is leeg)} -\gdef\putwordIndexNonexistent{(Index bestaat niet)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Instantie Variabele van} -\gdef\putwordMethodon{Methode van} -\gdef\putwordNoTitle{Geen titel} -\gdef\putwordof{van} -\gdef\putwordon{op} -\gdef\putwordpage{pagina} -\gdef\putwordsection{sectie} -\gdef\putwordSection{Sectie} -\gdef\putwordsee{zie} -\gdef\putwordSee{Zie} -\gdef\putwordShortTOC{Korte inhoudsopgave} -\gdef\putwordTOC{Inhoudsopgave} -% -\gdef\putwordMJan{Januari} -\gdef\putwordMFeb{Februari} -\gdef\putwordMMar{Maart} -\gdef\putwordMApr{April} -\gdef\putwordMMay{Mei} -\gdef\putwordMJun{Juni} -\gdef\putwordMJul{Juli} -\gdef\putwordMAug{Augustus} -\gdef\putwordMSep{September} -\gdef\putwordMOct{Oktober} -\gdef\putwordMNov{November} -\gdef\putwordMDec{December} -% -\gdef\putwordDefmac{Macro} -\gdef\putwordDefspec{Speciale Vorm} -\gdef\putwordDefvar{Variabele} -\gdef\putwordDefopt{Gebruikers optie} -\gdef\putwordDeffunc{Functie} - -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-no.tex b/Build/source/utils/texinfo/doc/txi-no.tex deleted file mode 100644 index a4e589382ed..00000000000 --- a/Build/source/utils/texinfo/doc/txi-no.tex +++ /dev/null @@ -1,69 +0,0 @@ -% Norwegian translation for texinfo.tex (1999-10-29, GNU Texinfo 4.0). -% Enables the use of words like Kapittel instead of Chapter, etc. -% -% Copyright (C) 1999 Trond Endrest=F8l <endrestol@hotmail.com> -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 2 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program; if not, write to the Free Software -% Foundation, Inc., 59 Temple Place - Suite 330, Boston, -% MA 02111-1307, USA. -% -\gdef\putwordAppendix{Vedlegg} -\gdef\putwordChapter{Kapittel} -\gdef\putwordfile{fil} -\gdef\putwordIndexIsEmpty{(Indeks er tom)} -\gdef\putwordIndexNonexistent{(Indeks eksisterer ikke)} -\gdef\putwordInfo{Info} -\gdef\putwordMethodon{Metode p\aa} -\gdef\putwordNoTitle{Ingen tittel} -\gdef\putwordof{av} -\gdef\putwordon{p\aa} -\gdef\putwordpage{side} -\gdef\putwordsection{avsnitt} -\gdef\putwordSection{Avsnitt} -\gdef\putwordsee{se} -\gdef\putwordSee{Se} -\gdef\putwordShortTOC{Kort innholdsfortegnelse} -\gdef\putwordTOC{Innholdsfortegnelse} -% -\gdef\putwordMJan{januar} -\gdef\putwordMFeb{februar} -\gdef\putwordMMar{mars} -\gdef\putwordMApr{april} -\gdef\putwordMMay{mai} -\gdef\putwordMJun{juni} -\gdef\putwordMJul{juli} -\gdef\putwordMAug{august} -\gdef\putwordMSep{september} -\gdef\putwordMOct{oktober} -\gdef\putwordMNov{november} -\gdef\putwordMDec{desember} -% -\gdef\putwordDefmac{Makro} -\gdef\putwordDefspec{Spesiell form} -\gdef\putwordDefivar{Forekomstvariabel} -\gdef\putwordDefvar{Variabel} -\gdef\putwordDefopt{Brukervalg} -\gdef\putwordDeffunc{Funksjon} -% -% Redefine \today to produce Norwegian -% preferred dates such as 28. januar 1999. -% -\gdef\today{% - \number\day.\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-pl.tex b/Build/source/utils/texinfo/doc/txi-pl.tex deleted file mode 100644 index 5b33489a9f1..00000000000 --- a/Build/source/utils/texinfo/doc/txi-pl.tex +++ /dev/null @@ -1,70 +0,0 @@ -% txi-pl.tex -- adaptation to Polish for texinfo.tex. -% $Id: txi-pl.tex,v 1.6 2007/07/01 19:06:04 karl Exp $ -% -% Copyright (C) 2003, 2006, 2007 Free Software Foundation. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% Written by Wojciech Polak <polak@gnu.org> on 29-03-2003. -% Modified by Staszek Wawrykiewicz <staw@gust.org.pl> on 01-04-2003. -% -\gdef\putwordAppendix{Suplement} -\gdef\putwordChapter{Rozdzia³} -\gdef\putwordfile{plik} -\gdef\putwordin{w} -\gdef\putwordIndexIsEmpty{(Skorowidz jest pusty)} -\gdef\putwordIndexNonexistent{(Brak skorowidza)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Przyk³adowa zmienna} -\gdef\putwordMethodon{Metoda} -\gdef\putwordNoTitle{Brak tytu³u} -\gdef\putwordof{z} -\gdef\putwordon{na} -\gdef\putwordpage{strona} -\gdef\putwordsection{czê¶æ} -\gdef\putwordSection{Czê¶æ} -\gdef\putwordsee{zobacz} -\gdef\putwordSee{Zobacz} -\gdef\putwordShortTOC{Krótka zawarto¶æ} -\gdef\putwordTOC{Spis tre¶ci} -% -\gdef\putwordMJan{stycznia} -\gdef\putwordMFeb{lutego} -\gdef\putwordMMar{marca} -\gdef\putwordMApr{kwietnia} -\gdef\putwordMMay{maja} -\gdef\putwordMJun{czerwca} -\gdef\putwordMJul{lipca} -\gdef\putwordMAug{sierpnia} -\gdef\putwordMSep{wrze¶nia} -\gdef\putwordMOct{pa¼dziernika} -\gdef\putwordMNov{listopada} -\gdef\putwordMDec{grudnia} -% -\gdef\putwordDefmac{Makro} -\gdef\putwordDefspec{Specjalna forma} -\gdef\putwordDefvar{Zmienna} -\gdef\putwordDefopt{Opcja u¿ytkownika} -\gdef\putwordDeffunc{Funkcja} -% -% Produces Day Month Year style of output. -% -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-pt.tex b/Build/source/utils/texinfo/doc/txi-pt.tex deleted file mode 100644 index 4a61765a7d4..00000000000 --- a/Build/source/utils/texinfo/doc/txi-pt.tex +++ /dev/null @@ -1,68 +0,0 @@ -% txi-pt.tex -- adaptation to Portuguese for texinfo.tex. -% -% Copyright (C) 1999, 2007 Free Software Foundation, Inc. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or (at -% your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% Written by Lalo Martins <lalo@webcom.com> at 05 August 1999 -%% -%% Portuguese translation of the used words. -\gdef\putwordAppendix{Ap\^endice} -\gdef\putwordChapter{Cap\'\ptexi tulo} -\gdef\putwordfile{Data} -\gdef\putwordin{em} -\gdef\putwordInfo{Info} -\gdef\putwordMethodon{M\'etodo de} -\gdef\putwordon{em} -\gdef\putwordof{de} -\gdef\putwordpage{P\'agina} -\gdef\putwordsection{se\,c\~ao} -\gdef\putwordSection{Se\,c\~ao} -\gdef\putwordsee{veja} -\gdef\putwordSee{Veja} -\gdef\putwordShortTOC{Breve Sum\'ario} -\gdef\putwordTOC{Sum\'ario} -%% -\gdef\putwordNoTitle{Sem T\'\ptexi tulo} -%% -%% New defintion for the output of months. -\gdef\putwordMJan{Janeiro} -\gdef\putwordMFeb{Fevereiro} -\gdef\putwordMMar{Mar\,co} -\gdef\putwordMApr{Abril} -\gdef\putwordMMai{Maio} -\gdef\putwordMJun{Junho} -\gdef\putwordMJul{Julho} -\gdef\putwordMAug{Agosto} -\gdef\putwordMSep{Setembro} -\gdef\putwordMOct{Outubro} -\gdef\putwordMNov{Novembro} -\gdef\putwordMDec{Dezembro} -%% -%% Index handling should also work correct in german -\gdef\putwordIndexNonexistent{(\'Indice inexistente)} -\gdef\putwordIndexIsEmpty{(\'Indice vazio)} -%% -%% \defmac -\gdef\putwordDefmac{Macro} -%% \defspec -\gdef\putwordDefspec{Forma Especial} -%% \defivar -\gdef\putwordDefivar{Vari\'avel de Inst\^ancia} -%% \defvar -\gdef\putwordDefvar{Vari\'avel} -%% \defopt -\gdef\putwordDefopt{Op\,c\~ao de Usu\'ario} -%% \deffun -\gdef\putwordDeffunc{Fun\,c\~ao} diff --git a/Build/source/utils/texinfo/doc/txi-ru.tex b/Build/source/utils/texinfo/doc/txi-ru.tex deleted file mode 100644 index 5dd80f6acae..00000000000 --- a/Build/source/utils/texinfo/doc/txi-ru.tex +++ /dev/null @@ -1,71 +0,0 @@ -% Russian translation for texinfo.tex. -% -% Copyright (C) 2005, 2007 Free Software Foundation. -% -% Author: -% Sergey Poznyakoff -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. - -%\include plainenc -% -\gdef\putwordAppendix{ðÒÉÌÏÖÅÎÉÅ} -\gdef\putwordChapter{çÌÁ×Á} -\gdef\putwordfile{ÆÁÊÌ} -\gdef\putwordin{×} -\gdef\putwordIndexIsEmpty{(éÎÄÅËÓ ÐÕÓÔ)} -\gdef\putwordIndexNonexistent{(éÎÄÅËÓ ÎÅ ÓÕÝÅÓÔ×ÕÅÔ)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{ðÅÒÅÍÅÎÎÁÑ ËÌÁÓÓÁ} % hmm ?? -\gdef\putwordMethodon{íÅÔÏÄ} -\gdef\putwordNoTitle{âÅÚ ÚÁÇÌÁ×ÉÑ} -\gdef\putwordof{ÄÌÑ} % (??) ëÁÔÅÇÏÒÉÑ X ÄÌÑ ËÌÁÓÓÁ Y -\gdef\putwordon{ÎÁÄ} % ïÐÅÒÁÃÉÑ ÎÁÄ ... -\gdef\putwordpage{ÓÔÒÁÎÉÃÁ} -\gdef\putwordsection{ÒÁÚÄÅÌ} -\gdef\putwordSection{òÁÚÄÅÌ} -\gdef\putwordsee{ÓÍ.} -\gdef\putwordSee{óÍ.} -\gdef\putwordShortTOC{ëÒÁÔËÏÅ ÏÇÌÁ×ÌÅÎÉÅ} -\gdef\putwordTOC{ïÇÌÁ×ÌÅÎÉÅ} -% -%% íÅÓÑÃÙ ÉÓÐÏÌØÚÕÀÔÓÑ ÔÏÌØËÏ × ÒÏÄÉÔÅÌØÎÏÍ ÐÁÄÅÖÅ (ÓÍ. ÎÉÖÅ today) -\gdef\putwordMJan{ÑÎ×ÁÒÑ} -\gdef\putwordMFeb{ÆÅ×ÒÁÌÑ} -\gdef\putwordMMar{ÍÁÒÔÁ} -\gdef\putwordMApr{ÁÐÒÅÌÑ} -\gdef\putwordMMay{ÍÁÑ} -\gdef\putwordMJun{ÉÀÎØ} -\gdef\putwordMJul{ÉÀÌÑ} -\gdef\putwordMAug{Á×ÇÕÓÔÁ} -\gdef\putwordMSep{ÓÅÎÔÑÂÒÑ} -\gdef\putwordMOct{ÏËÔÑÂÒÑ} -\gdef\putwordMNov{ÎÏÑÂÒÑ} -\gdef\putwordMDec{ÄÅËÁÂÒÑ} -% -\gdef\putwordDefmac{íÁËÒÏÏÐÒÅÄÅÌÅÎÉÅ} -\gdef\putwordDefspec{ïÓÏÂÁÑ ÆÏÒÍÁ} -\gdef\putwordDefvar{ðÅÒÅÍÅÎÎÁÑ} -\gdef\putwordDefopt{ïÐÃÉÑ ÐÏÌØÚÏ×ÁÔÅÌÑ} -\gdef\putwordDeffunc{æÕÎËÃÉÑ} - -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-sr.tex b/Build/source/utils/texinfo/doc/txi-sr.tex deleted file mode 100644 index 9141a4b692a..00000000000 --- a/Build/source/utils/texinfo/doc/txi-sr.tex +++ /dev/null @@ -1,67 +0,0 @@ -% Serbian-latin translation for texinfo.tex. -% -% Copyright (C) 2005, 2007 Free Software Foundation. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% Created by Predrag Rakic. - -\gdef\putwordAppendix{Prilog} -\gdef\putwordChapter{Glava} -\gdef\putwordfile{datoteka} -\gdef\putwordin{u} -\gdef\putwordIndexIsEmpty{(Indeks je prazan)} -\gdef\putwordIndexNonexistent{(Indeks ne postoji)} -\gdef\putwordInfo{Info} -\gdef\putwordInstanceVariableof{Atribut klase} -\gdef\putwordMethodon{Metod klase} -\gdef\putwordNoTitle{Bez naslova} -\gdef\putwordof{} -\gdef\putwordon{} -\gdef\putwordpage{strana} -\gdef\putwordsection{poglavlje} -\gdef\putwordSection{Poglavlje} -\gdef\putwordsee{vidi} -\gdef\putwordSee{Vidi} -\gdef\putwordShortTOC{Kratak sadr\v{z}aj} -\gdef\putwordTOC{Sadr\v{z}aj} -% -\gdef\putwordMJan{Januar} -\gdef\putwordMFeb{Februar} -\gdef\putwordMMar{Mart} -\gdef\putwordMApr{April} -\gdef\putwordMMay{Maj} -\gdef\putwordMJun{Jun} -\gdef\putwordMJul{Jul} -\gdef\putwordMAug{Avgust} -\gdef\putwordMSep{Septembar} -\gdef\putwordMOct{Oktobar} -\gdef\putwordMNov{Novembar} -\gdef\putwordMDec{Decembar} -% -\gdef\putwordDefmac{Makro} -\gdef\putwordDefspec{Posebna forma} -\gdef\putwordDefvar{Promenljiva} -\gdef\putwordDefopt{Korisni\v{c}ka opcija} -\gdef\putwordDeffunc{Funkcija} - -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-tr.tex b/Build/source/utils/texinfo/doc/txi-tr.tex deleted file mode 100644 index 0bd7fcbea75..00000000000 --- a/Build/source/utils/texinfo/doc/txi-tr.tex +++ /dev/null @@ -1,81 +0,0 @@ -% txi-tr.tex -- adaptation to Turkish for texinfo.tex. -% $Id: txi-tr.tex,v 1.7 2007/07/01 22:32:12 karl Exp $ -% -% Copyright (C) 2003, 2007 Free Software Foundation, Inc. -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or (at -% your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% Written by Alper Ersoy, 5 January 2003, <aersoy@tfz.net> -% -%% -%% Turkish translations of the used words. -%% -%% -\gdef\putwordAppendix{Ek} -\gdef\putwordChapter{Kesim} -\gdef\putwordfile{dosya} -\gdef\putwordInfo{Bilgi} -\gdef\putwordpage{Sayfa} -\gdef\putwordsection{b\"ol\"um} -\gdef\putwordSection{B\"ol\"um} -\gdef\putwordsee{bkz.} -\gdef\putwordSee{Bkz.} -\gdef\putwordShortTOC{\dotaccent{I}\,cindekiler (K\dotless{i}saca)} -\gdef\putwordTOC{\dotaccent{I}\,cindekiler} -%% -%% This one really sucks :\ -\gdef\putwordMethodon{S\dotless{i}n\dotless{i}f:} -%% -%% I could not translate these ones, need examples :\ -%% If anybody out there is using these in turkish, please -%% don't hesitate to send me patches ;) -\gdef\putwordin{in} -\gdef\putwordon{on} -\gdef\putwordof{of} -%% -%% -\gdef\putwordNoTitle{Ba\,sl\dotless{i}s\dotless{i}z} -\gdef\putwordIndexNonexistent{(Dizin bulunmamakta)} -\gdef\putwordIndexIsEmpty{(Dizin bo\,s)} -%% -%% Months -\gdef\putwordMJan{Ocak} -\gdef\putwordMFeb{\,Subat} -\gdef\putwordMMar{Mart} -\gdef\putwordMApr{Nisan} -\gdef\putwordMMai{May\dotless{i}s} -\gdef\putwordMJun{Haziran} -\gdef\putwordMJul{Temmuz} -\gdef\putwordMAug{A\u{g}ustos} -\gdef\putwordMSep{Eyl\"ul} -\gdef\putwordMOct{Ekim} -\gdef\putwordMNov{Kas\dotless{i}m} -\gdef\putwordMDec{Aral\dotless{i}k} -%% -%% Definitions -\gdef\putwordDefmac{Makro} -\gdef\putwordDefspec{\"Ozel Yap\dotless{i}} -\gdef\putwordDefopt{Se\,cenek} -\gdef\putwordDefvar{De\u{g}i\,sken} -\gdef\putwordDeffunc{Fonksiyon} -%% -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/txi-uk.tex b/Build/source/utils/texinfo/doc/txi-uk.tex deleted file mode 100644 index 8eb8cfa85bb..00000000000 --- a/Build/source/utils/texinfo/doc/txi-uk.tex +++ /dev/null @@ -1,68 +0,0 @@ -% Ukrainian translation for texinfo.tex. -% -% Copyright (C) 2005, 2007 Free Software Foundation. -% -% Author: -% Sergey Poznyakoff -% -% This program is free software; you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation; either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. - -\gdef\putwordAppendix{äÏÄÁÔÏË} -\gdef\putwordChapter{òÏÚĦÌ} -\gdef\putwordfile{ÆÁÊÌ} -\gdef\putwordin{×} -\gdef\putwordIndexIsEmpty{(¶ÎÄÅËÓ ÐÕÓÔÉÊ)} -\gdef\putwordIndexNonexistent{(¶ÎÄÅËÓ ÎÅ ¦ÓÎÕ¤)} -\gdef\putwordInfo{ÆÁÊÌ Info} -\gdef\putwordInstanceVariableof{úͦÎÎÁ ËÌÁÓÕ} -\gdef\putwordMethodon{íÅÔÏÄ } -\gdef\putwordNoTitle{îÅÍÁ¤ ÎÁÚ×É} -\gdef\putwordof{ÄÌÑ} % ?? -\gdef\putwordon{Ú} % ïÐÅÒÁÃ¦Ñ Ú ËÌÁÓÏÍ ... -\gdef\putwordpage{ÓÔÏÒ¦ÎËÁ} -\gdef\putwordsection{ÞÁÓÔÉÎÁ} -\gdef\putwordSection{þÁÓÔÉÎÁ} -\gdef\putwordsee{ÄÉ×.} -\gdef\putwordSee{äÉ×.} -\gdef\putwordShortTOC{ëÏÒÏÔËÉÊ ÚͦÓÔ} -\gdef\putwordTOC{úͦÓÔ} -% -\gdef\putwordMJan{Ó¦ÞÎÑ} -\gdef\putwordMFeb{ÌÀÔÏÇÏ} -\gdef\putwordMMar{ÂÅÒÅÚÎÑ} -\gdef\putwordMApr{ËצÔÎÑ} -\gdef\putwordMMay{ÔÒÁ×ÎÑ} -\gdef\putwordMJun{ÞÅÒ×ÎÑ} -\gdef\putwordMJul{ÌÉÐÎÑ} -\gdef\putwordMAug{ÓÅÒÐÎÑ} -\gdef\putwordMSep{×ÅÒÅÓÎÑ} -\gdef\putwordMOct{ÖÏ×ÔÎÑ} -\gdef\putwordMNov{ÌÉÓÔÏÐÁÄÁ} -\gdef\putwordMDec{ÇÒÕÄÎÑ} -% -\gdef\putwordDefmac{íÁËÒÏÓ} -\gdef\putwordDefspec{óÐÅæÁÌØÎÁ ÆÏÒÍÁ} -\gdef\putwordDefvar{úͦÎÎÁ} -\gdef\putwordDefopt{ïÐÃ¦Ñ ËÏÒÉÓÔÕ×ÁÞÁ} -\gdef\putwordDeffunc{æÕÎËæÑ} - -% Produces Day Month Year style of output. -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} diff --git a/Build/source/utils/texinfo/doc/version-stnd.texi b/Build/source/utils/texinfo/doc/version-stnd.texi deleted file mode 100644 index a1b0be3185b..00000000000 --- a/Build/source/utils/texinfo/doc/version-stnd.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 5 March 2008 -@set UPDATED-MONTH March 2008 -@set EDITION 4.12 -@set VERSION 4.12 diff --git a/Build/source/utils/texinfo/doc/version.texi b/Build/source/utils/texinfo/doc/version.texi deleted file mode 100644 index da6f3285a4c..00000000000 --- a/Build/source/utils/texinfo/doc/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 9 April 2008 -@set UPDATED-MONTH April 2008 -@set EDITION 4.12 -@set VERSION 4.12 |