diff options
Diffstat (limited to 'Build/source/utils/texinfo/doc')
36 files changed, 35741 insertions, 0 deletions
diff --git a/Build/source/utils/texinfo/doc/Makefile.am b/Build/source/utils/texinfo/doc/Makefile.am new file mode 100644 index 00000000000..5e36cb74c86 --- /dev/null +++ b/Build/source/utils/texinfo/doc/Makefile.am @@ -0,0 +1,80 @@ +# $Id: Makefile.am,v 1.20 2004/11/18 01:10:59 karl 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 texi2dvi.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 +INSTALL_INFO = $(top_builddir)/$(native_tools)/util/install-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-no.tex txi-pl.tex txi-pt.tex txi-tr.tex + +# Include our texinfo.tex, not Automake's. +EXTRA_DIST = epsf.tex pdfcolor.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 and (if you" + @echo " use pdftex) pdfcolor.tex in TEXMF/tex/generic/dvips" + @echo " and TEXMF/pdftex/plain/misc/pdfcolor.tex respectively," + @echo " if your TeX installation did not include them." +endif + +texmf_texinfo = $(TEXMF)/tex/texinfo +texmf_dvips = $(TEXMF)/tex/generic/epsf +texmf_pdftex_misc = $(TEXMF)/tex/plain/pdfcolor +install-tex: + test -n "$(TEXMF)" || (echo "TEXMF must be set." >&2; exit 1) + $(mkinstalldirs) $(DESTDIR)$(texmf_texinfo) $(DESTDIR)$(texmf_dvips) $(DESTDIR)$(texmf_pdftex_misc) + $(INSTALL_DATA) $(srcdir)/texinfo.tex $(DESTDIR)$(texmf_texinfo)/texinfo.tex + $(INSTALL_DATA) $(srcdir)/epsf.tex $(DESTDIR)$(texmf_dvips)/epsf.tex + $(INSTALL_DATA) $(srcdir)/pdfcolor.tex $(DESTDIR)$(texmf_pdftex_misc)/pdfcolor.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. +if MAINTAINER_MODE +common_mandeps = $(top_srcdir)/configure.ac +info.1: $(top_srcdir)/info/info.c $(common_mandeps) + $(HELP2MAN) --name="read Info documents" `basename $@ .1` >$@ +infokey.1: $(top_srcdir)/info/infokey.c $(common_mandeps) + $(HELP2MAN) --name="compile customizations for Info" `basename $@ .1` >$@ +install-info.1: $(top_srcdir)/util/install-info.c $(common_mandeps) + $(HELP2MAN) --name="update info/dir entries" `basename $@ .1` >$@ +makeinfo.1: $(top_srcdir)/makeinfo/makeinfo.c $(common_mandeps) + $(HELP2MAN) --name="translate Texinfo documents" `basename $@ .1` >$@ +texi2dvi.1: $(top_srcdir)/util/texi2dvi $(common_mandeps) + $(HELP2MAN) --name="print Texinfo documents" `basename $@ .1` >$@ +texindex.1: $(top_srcdir)/util/texindex.c $(common_mandeps) + $(HELP2MAN) --name="sort Texinfo index files" `basename $@ .1` >$@ +endif + +# 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 new file mode 100644 index 00000000000..2c8efe54c21 --- /dev/null +++ b/Build/source/utils/texinfo/doc/Makefile.in @@ -0,0 +1,772 @@ +# Makefile.in generated by automake 1.9.4 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004 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.20 2004/11/18 01:10:59 karl 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. +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +top_builddir = .. +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +INSTALL = @INSTALL@ +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 mdate-sh \ + texinfo.tex +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/codeset.m4 \ + $(top_srcdir)/m4/gettext.m4 $(top_srcdir)/m4/glibc21.m4 \ + $(top_srcdir)/m4/iconv.m4 $(top_srcdir)/m4/intdiv0.m4 \ + $(top_srcdir)/m4/intmax.m4 $(top_srcdir)/m4/inttypes-pri.m4 \ + $(top_srcdir)/m4/inttypes.m4 $(top_srcdir)/m4/inttypes_h.m4 \ + $(top_srcdir)/m4/lcmessage.m4 $(top_srcdir)/m4/lib-ld.m4 \ + $(top_srcdir)/m4/lib-link.m4 $(top_srcdir)/m4/lib-prefix.m4 \ + $(top_srcdir)/m4/longdouble.m4 $(top_srcdir)/m4/longlong.m4 \ + $(top_srcdir)/m4/mkstemp.m4 $(top_srcdir)/m4/nls.m4 \ + $(top_srcdir)/m4/onceonly_2_57.m4 $(top_srcdir)/m4/po.m4 \ + $(top_srcdir)/m4/printf-posix.m4 $(top_srcdir)/m4/progtest.m4 \ + $(top_srcdir)/m4/signed.m4 $(top_srcdir)/m4/size_max.m4 \ + $(top_srcdir)/m4/stdint_h.m4 $(top_srcdir)/m4/strcase.m4 \ + $(top_srcdir)/m4/uintmax_t.m4 $(top_srcdir)/m4/ulonglong.m4 \ + $(top_srcdir)/m4/wchar_t.m4 $(top_srcdir)/m4/wint_t.m4 \ + $(top_srcdir)/m4/xsize.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +INFO_DEPS = texinfo info-stnd.info info.info +am__TEXINFO_TEX_DIR = $(srcdir) +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)" +man1dir = $(mandir)/man1 +man5dir = $(mandir)/man5 +NROFF = nroff +MANS = $(man_MANS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +AMDEP_FALSE = @AMDEP_FALSE@ +AMDEP_TRUE = @AMDEP_TRUE@ +AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BUILD_INCLUDED_LIBINTL = @BUILD_INCLUDED_LIBINTL@ +CATOBJEXT = @CATOBJEXT@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DATADIRNAME = @DATADIRNAME@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +GENCAT = @GENCAT@ +GLIBC21 = @GLIBC21@ +GMSGFMT = @GMSGFMT@ +HAVE_ASPRINTF = @HAVE_ASPRINTF@ +HAVE_POSIX_PRINTF = @HAVE_POSIX_PRINTF@ +HAVE_SNPRINTF = @HAVE_SNPRINTF@ +HAVE_WPRINTF = @HAVE_WPRINTF@ +HELP2MAN = @HELP2MAN@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INSTALL_WARNINGS_FALSE = @INSTALL_WARNINGS_FALSE@ +INSTALL_WARNINGS_TRUE = @INSTALL_WARNINGS_TRUE@ +INSTOBJEXT = @INSTOBJEXT@ +INTLBISON = @INTLBISON@ +INTLLIBS = @INTLLIBS@ +INTLOBJS = @INTLOBJS@ +INTL_LIBTOOL_SUFFIX_PREFIX = @INTL_LIBTOOL_SUFFIX_PREFIX@ +LDFLAGS = @LDFLAGS@ +LIBICONV = @LIBICONV@ +LIBINTL = @LIBINTL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LTLIBICONV = @LTLIBICONV@ +LTLIBINTL = @LTLIBINTL@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ +MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ + +# Use the programs built in our distribution, taking account of possible +# cross-compiling. +MAKEINFO = $(top_builddir)/$(native_tools)/makeinfo/makeinfo +MKINSTALLDIRS = @MKINSTALLDIRS@ +MSGFMT = @MSGFMT@ +MSGMERGE = @MSGMERGE@ +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@ +RANLIB = @RANLIB@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TERMLIBS = @TERMLIBS@ +TOOLS_ONLY_FALSE = @TOOLS_ONLY_FALSE@ +TOOLS_ONLY_TRUE = @TOOLS_ONLY_TRUE@ +USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +XGETTEXT = @XGETTEXT@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_RANLIB = @ac_ct_RANLIB@ +ac_ct_STRIP = @ac_ct_STRIP@ +am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ +am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ +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@ +datadir = @datadir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +native_tools = @native_tools@ +oldincludedir = @oldincludedir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ + +# 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 texi2dvi.1 \ + info.5 texinfo.5 + +INSTALL_INFO = $(top_builddir)/$(native_tools)/util/install-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-no.tex txi-pl.tex txi-pt.tex txi-tr.tex + + +# Include our texinfo.tex, not Automake's. +EXTRA_DIST = epsf.tex pdfcolor.tex texinfo.tex \ + fdl.texi \ + $(man_MANS) $(TXI_XLATE) + +texmf_texinfo = $(TEXMF)/tex/texinfo +texmf_dvips = $(TEXMF)/tex/generic/epsf +texmf_pdftex_misc = $(TEXMF)/tex/plain/pdfcolor + +# The man pages depend on the --help strings and the version number. +@MAINTAINER_MODE_TRUE@common_mandeps = $(top_srcdir)/configure.ac +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 && \ + 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; \ + 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) $(srcdir)/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 && \ + 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; \ + 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) $(srcdir)/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 && \ + 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; \ + 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: + $(DVIPS) -o $@ $< + +uninstall-info-am: + $(PRE_UNINSTALL) + @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)' --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 cd "$(DESTDIR)$(infodir)"; then \ + echo " 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 + +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)'; for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ + esac; \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test "$$dir" != "$$file" && test "$$dir" != "."; then \ + dir="/$$dir"; \ + $(mkdir_p) "$(distdir)$$dir"; \ + else \ + dir=''; \ + fi; \ + if test -d $$d/$$file; then \ + 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-exec-am: + +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 + +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-info-am uninstall-man + +uninstall-man: uninstall-man1 uninstall-man5 + +.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-exec install-exec-am install-info \ + install-info-am install-man install-man1 install-man5 \ + 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-info-am uninstall-man uninstall-man1 uninstall-man5 + + +@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 and (if you" +@INSTALL_WARNINGS_TRUE@ @echo " use pdftex) pdfcolor.tex in TEXMF/tex/generic/dvips" +@INSTALL_WARNINGS_TRUE@ @echo " and TEXMF/pdftex/plain/misc/pdfcolor.tex respectively," +@INSTALL_WARNINGS_TRUE@ @echo " if your TeX installation did not include them." +install-tex: + test -n "$(TEXMF)" || (echo "TEXMF must be set." >&2; exit 1) + $(mkinstalldirs) $(DESTDIR)$(texmf_texinfo) $(DESTDIR)$(texmf_dvips) $(DESTDIR)$(texmf_pdftex_misc) + $(INSTALL_DATA) $(srcdir)/texinfo.tex $(DESTDIR)$(texmf_texinfo)/texinfo.tex + $(INSTALL_DATA) $(srcdir)/epsf.tex $(DESTDIR)$(texmf_dvips)/epsf.tex + $(INSTALL_DATA) $(srcdir)/pdfcolor.tex $(DESTDIR)$(texmf_pdftex_misc)/pdfcolor.tex + for f in $(TXI_XLATE); do \ + $(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(texmf_texinfo)/$$f; done +@MAINTAINER_MODE_TRUE@info.1: $(top_srcdir)/info/info.c $(common_mandeps) +@MAINTAINER_MODE_TRUE@ $(HELP2MAN) --name="read Info documents" `basename $@ .1` >$@ +@MAINTAINER_MODE_TRUE@infokey.1: $(top_srcdir)/info/infokey.c $(common_mandeps) +@MAINTAINER_MODE_TRUE@ $(HELP2MAN) --name="compile customizations for Info" `basename $@ .1` >$@ +@MAINTAINER_MODE_TRUE@install-info.1: $(top_srcdir)/util/install-info.c $(common_mandeps) +@MAINTAINER_MODE_TRUE@ $(HELP2MAN) --name="update info/dir entries" `basename $@ .1` >$@ +@MAINTAINER_MODE_TRUE@makeinfo.1: $(top_srcdir)/makeinfo/makeinfo.c $(common_mandeps) +@MAINTAINER_MODE_TRUE@ $(HELP2MAN) --name="translate Texinfo documents" `basename $@ .1` >$@ +@MAINTAINER_MODE_TRUE@texi2dvi.1: $(top_srcdir)/util/texi2dvi $(common_mandeps) +@MAINTAINER_MODE_TRUE@ $(HELP2MAN) --name="print Texinfo documents" `basename $@ .1` >$@ +@MAINTAINER_MODE_TRUE@texindex.1: $(top_srcdir)/util/texindex.c $(common_mandeps) +@MAINTAINER_MODE_TRUE@ $(HELP2MAN) --name="sort Texinfo index files" `basename $@ .1` >$@ + +# 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 new file mode 100644 index 00000000000..63f1ba29219 --- /dev/null +++ b/Build/source/utils/texinfo/doc/README @@ -0,0 +1,44 @@ +$Id: README,v 1.4 2004/04/11 17:56:45 karl 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, TEXMF/tex/generic/dvips/ for epsf.tex, +and TEXMF/pdftex/plain/misc for pdfcolor.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 new file mode 100644 index 00000000000..db2cd2031bd --- /dev/null +++ b/Build/source/utils/texinfo/doc/epsf.tex @@ -0,0 +1,547 @@ +%%% ==================================================================== +%%% This file is freely redistributable and placed into the +%%% public domain by Tomas Rokicki. +%%% @TeX-file{ +%%% author = "Tom Rokicki", +%%% version = "2.7k", +%%% date = "19 July 1997", +%%% time = "10:00:05 MDT", +%%% filename = "epsf.tex", +%%% address = "Tom Rokicki +%%% Box 2081 +%%% Stanford, CA 94309 +%%% USA", +%%% telephone = "+1 415 855 9989", +%%% email = "rokicki@cs.stanford.edu (Internet)", +%%% codetable = "ISO/ASCII", +%%% 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 say +%%% +%%% \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 +%%% saying +%%% +%%% \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), say +%%% `\epsfverbosetrue'. +%%% +%%% If you only want to get the bounding box +%%% extents, without producing any output boxes +%%% or \special{}, then say +%%% \epsfgetbb{filename}. The extents will be +%%% saved in the macros \epsfllx \epsflly +%%% \epsfurx \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. +%%% --------------------------------------------- +%%% +%%% Modified to avoid verbosity, give help. +%%% --kb@cs.umb.edu, for Texinfo. +%%% } +%%% ==================================================================== +% +\ifx\epsfannounce\undefined \def\epsfannounce{\immediate\write16}\fi + \epsfannounce{This is `epsf.tex' v2.7k <10 July 1997>}% +% +\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}% +}% +% +\newhelp\epsfnoopenhelp{The PostScript image file must be findable by +TeX, i.e., somewhere in the TEXINPUTS (or equivalent) path.}% +% +\def\epsfgetbb#1{% +% +% The first thing we need to do is to open the +% PostScript file, if possible. +% + \openin\epsffilein=#1 + \ifeof\epsffilein + \errhelp = \epsfnoopenhelp + \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}% +}% +% +% 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\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\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\space + 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% +{% + \leavevmode % so we can put this inside + % a centered environment + \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 + \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 +}% +% +\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. + % + \leavevmode + \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 + }% + }}% + % + % 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\epsfrsize + \epsfxsize=\epsfysize \multiply\epsfxsize\epsftmp + \multiply\epsftmp\epsfrsize \advance\epsftsize-\epsftmp + \epsftmp=\epsfysize + \loop \advance\epsftsize\epsftsize \divide\epsftmp 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\epsftsize + \epsfysize=\epsfxsize \multiply\epsfysize\epsftmp + \multiply\epsftmp\epsftsize \advance\epsfrsize-\epsftmp + \epsftmp=\epsfxsize + \loop \advance\epsfrsize\epsfrsize \divide\epsftmp 2 + \ifnum \epsftmp>0 + \ifnum \epsfrsize<\epsftsize + \else + \advance\epsfrsize-\epsftsize \advance\epsfysize\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 new file mode 100644 index 00000000000..11737cc89bd --- /dev/null +++ b/Build/source/utils/texinfo/doc/fdl.texi @@ -0,0 +1,452 @@ + +@node GNU Free Documentation License +@appendixsec GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, 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 +@appendixsubsec 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...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 new file mode 100755 index 00000000000..ea180b70a89 --- /dev/null +++ b/Build/source/utils/texinfo/doc/help2man @@ -0,0 +1,559 @@ +#!/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 new file mode 100644 index 00000000000..1a1df6fb6d8 --- /dev/null +++ b/Build/source/utils/texinfo/doc/info-stnd.texi @@ -0,0 +1,2203 @@ +\input texinfo.tex @c -*-texinfo-*- +@comment $Id: info-stnd.texi,v 1.9 2004/12/14 16:58:15 karl 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 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.1 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 freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@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 (bfox@@gnu.org) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Info + +@insertcopying + +This documentation is different from the documentation for the Info +reader that is part of GNU Emacs. If you do not know how to use Info, +but have a working Info reader, you should read the Emacs documentation +first, as it includes more background information and a thorough tutorial. +@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. +* Copying This Manual:: The GNU Free Documentation License. +* Index:: Global index containing keystrokes, + command names, variable names, + and general concepts. +@end menu + + +@node What is Info +@chapter What is Info? + +@dfn{Info} is a program which is used to view Info files on an ASCII +terminal. @dfn{Info files} are the result of processing Texinfo files +with the program @code{makeinfo} or with one of the Emacs commands, such +as @code{M-x texinfo-format-buffer}. 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. + + +@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} +@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. Note that 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. + +@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''. + +@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}. @xref{Variables, +@code{scroll-behavior}}, for more information. + +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}; @xref{Variables, @code{scroll-behavior}}, for +more information. + +@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 +Read a string in the echo area and search for it. 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{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. + +@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. + +@item scroll-behavior +@vindex scroll-behavior +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 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 + +@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) + +For those whose editor/pager of choice is not Emacs and who are not +entirely satisfied with the --vi-keys option (@pxref{--vi-keys}), GNU +Info provides a way to define different key-to-command bindings and +variable settings from the defaults described in this document. + +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 Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@include fdl.texi + + +@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 new file mode 100644 index 00000000000..39ca1d32ac3 --- /dev/null +++ b/Build/source/utils/texinfo/doc/info.1 @@ -0,0 +1,89 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.34. +.TH INFO "1" "December 2004" "info 4.8" "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\-\-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\-w\fR, \fB\-\-where\fR, \fB\-\-location\fR +print physical location of Info file. +.TP +\fB\-\-vi\-keys\fR +use vi\-like and less\-like key bindings. +.TP +\fB\-\-version\fR +display version information and exit. +.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\-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 2004 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. diff --git a/Build/source/utils/texinfo/doc/info.5 b/Build/source/utils/texinfo/doc/info.5 new file mode 100644 index 00000000000..08fd289908f --- /dev/null +++ b/Build/source/utils/texinfo/doc/info.5 @@ -0,0 +1,72 @@ +.\" info(5) +.\" $Id: info.5,v 1.2 2004/04/11 17:56:45 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 new file mode 100644 index 00000000000..014e9165087 --- /dev/null +++ b/Build/source/utils/texinfo/doc/info.texi @@ -0,0 +1,1498 @@ +\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 (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 +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.1 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. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +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 expert-level Info commands, type @kbd{n} twice. This +brings you to @cite{Info for Experts}, skipping over the `Getting +Started' chapter. +@end ifinfo +@end ifnottex + +@menu +* Getting Started:: Getting started using an Info reader. +* Expert Info:: Info commands for experts. +* Creating an Info File:: How to make your own Info file. +* Index:: An index of topics, commands, and variables. +@end menu + +@node Getting Started, Expert Info, 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, and how to write an Info as distinct from a Texinfo +file. The third part briefly explains how to generate Info files from +Texinfo files. + +@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 you see the text @samp{--All----} near the bottom right corner +of the screen, it means the entire text you are looking at fits on the +screen. If you see @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 duplicated in a special typeface, +and the duplicate 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 middle + 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 the middle mouse button 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{Prev} (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 string @samp{--Top-----} rather than @samp{--All----} near +the bottom right corner 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 + + If your screen is very tall, all of this node might fit at once. In +that case, @kbd{b} won't do anything. But you could observe the +effect of the @kbd{b} key if you use a smaller window. + +@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 +a @kbd{?} (in Emacs it runs the @code{Info-summary} command) which +displays a brief list of commands. When you are finished looking at +the list, make it go away by typing a @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}. In Emacs, @kbd{m} runs the command @code{Info-menu}. + +@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, 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}.) + + 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'' (the Emacs command run by @kbd{u} is +@code{Info-up}). That puts you at the @emph{front} of the node---to +get back to where you were reading you have to type some @key{SPC}s. +(Some Info readers, such as the one built into Emacs, put you at the +same place where you were reading in @samp{Help-M}.) + + 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 + There are two ways to follow a cross reference. You can move the +cursor to it and press @key{RET}, just as in a menu. @key{RET} +follows the cross reference that the cursor is on. Or you can type +@kbd{f} and then specify the name of the cross reference (in this +case, @samp{Cross}) as an argument. In Emacs Info, @kbd{f} runs +@code{Info-follow-reference}, + + In the @kbd{f} command, you select the cross reference with its +name, so 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} and @kbd{M-@key{TAB}} key, 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 (shown in the stand-alone version) refers to the +file name. This file name appears in cross references and node names +if it differs from the current file. In Emacs, the file name is +hidden (along with other text). (Use @kbd{M-x visible-mode} to show +or hide it.) + + The remainder of this node applies only to the Emacs version. If +you use the stand-alone version, you can type @kbd{n} immediately. + + To some users, switching manuals is a much bigger switch than +switching sections. These users like to know that they are going to +be switching to another manual (and which one) before actually doing +so, especially given that, if one does not notice, Info commands like +@kbd{t} (see the next node) can have confusing results. + + If you put your mouse over the cross reference and if the cross +reference leads to a different manual, then the information appearing +in a separate box (tool tip) or in the echo area, will mention the +file the cross reference will carry you to (between parentheses). +This is also true for menu subtopic names. If you have a mouse, just +leave it over the @samp{Overview} cross reference above and watch what +happens. + + If you always like to have that information available without having +to move your mouse over the cross reference, set +@code{Info-hide-note-references} to a value other than t (@pxref{Emacs +Info Variables}). You might also want to do that if you have a lot of +cross references to files on remote machines and have non-permanent or +slow access, since otherwise you might not be able to distinguish +between local and remote links. + +@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; 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{Info Search}, for a full explanation. + +@kindex l @r{(Info mode)} +@findex Info-last +@cindex going back in Info mode + 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. + + In Emacs, @kbd{l} runs the command @code{Info-last}. + +@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 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}. + + Clicking @kbd{Mouse-2} on or near a cross reference also follows the +reference. 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. + +@format +>> Now type @kbd{n} to see the last node of the course. +@end format + + @xref{Expert Info}, 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 Expert Info +@chapter Info for Experts + + This chapter describes various Info commands for experts. (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}.) + + This chapter also explains how to write an Info as distinct from a +Texinfo file. (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.) @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU +Documentation Format}. + +@menu +* Advanced:: Advanced Info commands: g, e, and 1 - 9. +* Info Search:: How to search Info documents for specific subjects. +* 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 +* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. +@end menu + +@node Advanced, Info Search, , Expert Info +@comment node-name, next, previous, up +@section Advanced Info Commands + +Here are some more Info commands that make it easier to move around. + +@subheading @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{gAdvanced@key{RET}} would come back here. +@kbd{g} in Emacs runs the command @code{Info-goto-node}. + + 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}}. + +@subheading @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. In Emacs, +the digit keys run the command @code{Info-nth-menu-item}. + + 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. + +@subheading @kbd{e} makes Info document editable + +@kindex e @r{(Info mode)} +@findex Info-edit +@cindex edit Info document + The Info command @kbd{e} changes from Info mode to an ordinary +Emacs editing mode, so that you can edit the text of the current node. +Type @kbd{C-c C-c} to switch back to Info. The @kbd{e} command is allowed +only if the variable @code{Info-enable-edit} is non-@code{nil}. + + The @kbd{e} command only works in Emacs, where it runs the command +@code{Info-edit}. The stand-alone Info reader doesn't allow you to +edit the Info file, so typing @kbd{e} there goes to the end of the +current node. + +@subheading @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 another 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. + +@node Info Search, Add, Advanced, Expert Info +@comment node-name, next, previous, up +@section How to search Info documents for specific subjects + +@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 indices or its text. + +@kindex i @r{(Info mode)} +@findex Info-index + Since most subjects related to what the manual describes should be +indexed, you should try the index search first. 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 finds 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-f} key does, type +@kbd{i C - f @key{RET}}. Here @kbd{C-f} are 3 literal characters +@samp{C}, @samp{-}, and @samp{f}, not the ``Control-f'' command key +you type inside Emacs to run the command bound to @kbd{C-f}. + + In Emacs, @kbd{i} runs the command @code{Info-index}. + +@findex info-apropos +If you don't know what manual documents something, try the @kbd{M-x +info-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. + +@kindex s @r{(Info mode)} +@findex Info-search + The @kbd{s} command allows you to search a whole 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 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 do a @kbd{b} 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}. + + +@node Add, Menus, Info Search, 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 + + Usually, the way to create the nodes is with Texinfo (@pxref{Top,, +Overview of Texinfo, texinfo, Texinfo: The GNU Documentation Format}); +this has the advantage that you can also make a printed manual or HTML +from them. You would use the @samp{@@dircategory} and +@samp{@@direntry} commands to put the manual into the Info directory. +However, if you want to edit an Info file manually and install it +manually, here is how. + +@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 ``./'', +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, 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 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{Info Search}. + +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 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, Emacs Info Variables, 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 Emacs Info Variables, , Checking, Expert Info +@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 @file{~/.emacs} 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-fontify +When set to a non-@code{nil} value, enables highlighting of Info +files. The default is @code{t}. You can change how the highlighting +looks by customizing the faces @code{info-node}, @code{info-xref}, +@code{info-header-xref}, @code{info-header-node}, @code{info-menu-5}, +@code{info-menu-header}, and @code{info-title-@var{n}-face} (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-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-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 + +@item Info-enable-edit +Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command. A +non-@code{nil} value enables it. @xref{Add, Edit}. +@end vtable + + +@node Creating an Info File +@chapter Creating an Info File from a Texinfo File + +@code{makeinfo} is a utility that converts a Texinfo file into an Info +file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are +GNU Emacs functions that do the same. + +@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU +Documentation Format}, to learn how to write a Texinfo file. + +@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation +Format}, to learn how to create an Info file from a Texinfo file. + +@xref{Installing an Info File,,, texinfo, Texinfo: The GNU +Documentation Format}, to learn how to install an Info file after you +have created one. + +@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 new file mode 100644 index 00000000000..fb8f4634f40 --- /dev/null +++ b/Build/source/utils/texinfo/doc/infokey.1 @@ -0,0 +1,41 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.34. +.TH INFOKEY "1" "December 2004" "infokey 4.8" "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 2003 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. +.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 new file mode 100644 index 00000000000..004d5d0f97d --- /dev/null +++ b/Build/source/utils/texinfo/doc/install-info.1 @@ -0,0 +1,78 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.34. +.TH INSTALL-INFO "1" "December 2004" "install-info 4.8" "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 +Install or delete dir entries from INFO\-FILE in the Info directory file +DIR\-FILE. +.SH OPTIONS +.TP +\fB\-\-delete\fR +delete existing entries for INFO\-FILE from DIR\-FILE; +don't insert any new entries. +.TP +\fB\-\-dir\-file\fR=\fINAME\fR +specify file name of Info directory file. +This is equivalent to using the DIR\-FILE argument. +.TP +\fB\-\-entry\fR=\fITEXT\fR +insert TEXT as an Info directory entry. +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. +.TP +\fB\-\-help\fR +display this help and exit. +.TP +\fB\-\-info\-file\fR=\fIFILE\fR +specify Info file to install in the directory. +This is equivalent to using the INFO\-FILE argument. +.TP +\fB\-\-info\-dir\fR=\fIDIR\fR +same as \fB\-\-dir\-file\fR=\fIDIR\fR/dir. +.TP +\fB\-\-item\fR=\fITEXT\fR +same as \fB\-\-entry\fR TEXT. +An Info directory entry is actually a menu item. +.TP +\fB\-\-quiet\fR +suppress warnings. +.TP +\fB\-\-remove\fR +same as \fB\-\-delete\fR. +.TP +\fB\-\-section\fR=\fISEC\fR +put this file's entries in section 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. +.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 2004 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. +.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 new file mode 100644 index 00000000000..7b46491e0a6 --- /dev/null +++ b/Build/source/utils/texinfo/doc/makeinfo.1 @@ -0,0 +1,205 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.34. +.TH MAKEINFO "1" "December 2004" "makeinfo 4.8" "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\-\-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\-\-reference\-limit\fR=\fINUM\fR +warn about at most NUM references (default 1000). +.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 FILE +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 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 (directory if split HTML), +.SS "Options for Info and plain text:" +.TP +\fB\-\-enable\-encoding\fR +output accented and special characters in +Info output based on @documentencoding. +.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 +.IP +in which they are defined (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 \-. +.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. +.IP +Also, for the \fB\-\-no\-ifFORMAT\fR options, do process @ifnotFORMAT text. +.IP +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 +.IP +makeinfo \fB\-\-html\fR \fB\-\-no\-headers\fR foo.texi write html without node lines, menus +makeinfo \fB\-\-number\-sections\fR foo.texi write Info with numbered sections +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 2004 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. +.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 new file mode 100755 index 00000000000..881782eb55e --- /dev/null +++ b/Build/source/utils/texinfo/doc/mdate-sh @@ -0,0 +1,170 @@ +#!/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 new file mode 100644 index 00000000000..f09ecbcb750 --- /dev/null +++ b/Build/source/utils/texinfo/doc/pdfcolor.tex @@ -0,0 +1,158 @@ +% 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/stamp-1 b/Build/source/utils/texinfo/doc/stamp-1 new file mode 100644 index 00000000000..32973a788b2 --- /dev/null +++ b/Build/source/utils/texinfo/doc/stamp-1 @@ -0,0 +1,4 @@ +@set UPDATED 14 December 2004 +@set UPDATED-MONTH December 2004 +@set EDITION 4.8 +@set VERSION 4.8 diff --git a/Build/source/utils/texinfo/doc/stamp-vti b/Build/source/utils/texinfo/doc/stamp-vti new file mode 100644 index 00000000000..ae55f879d47 --- /dev/null +++ b/Build/source/utils/texinfo/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 29 December 2004 +@set UPDATED-MONTH December 2004 +@set EDITION 4.8 +@set VERSION 4.8 diff --git a/Build/source/utils/texinfo/doc/texi2dvi.1 b/Build/source/utils/texinfo/doc/texi2dvi.1 new file mode 100644 index 00000000000..41fae2f7d5e --- /dev/null +++ b/Build/source/utils/texinfo/doc/texi2dvi.1 @@ -0,0 +1,95 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.33. +.TH TEXI2DVI "1" "February 2005" "texi2dvi 1.39" "User Commands" +.SH NAME +texi2dvi \- print Texinfo documents +.SH SYNOPSIS +.B texi2dvi +[\fIOPTION\fR]... \fIFILE\fR... +.SH DESCRIPTION +Run each Texinfo or LaTeX 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 (LaTeX or Texinfo). +.PP +Makeinfo is used to perform Texinfo macro expansion before running TeX +when needed. +.SS "Operation modes:" +.TP +\fB\-b\fR, \fB\-\-batch\fR +no interaction +.TP +\fB\-c\fR, \fB\-\-clean\fR +remove all auxiliary files +.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\-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\-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 characters +.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 +.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 2005 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. +.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 new file mode 100644 index 00000000000..732e12b8874 --- /dev/null +++ b/Build/source/utils/texinfo/doc/texindex.1 @@ -0,0 +1,47 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.34. +.TH TEXINDEX "1" "December 2004" "texindex 4.8" "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\-k\fR, \fB\-\-keep\fR +keep temporary files around after processing +.TP +\fB\-\-no\-keep\fR +do not keep temporary files around after processing (default) +.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 2004 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. +.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 +should 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 new file mode 100644 index 00000000000..0ca35cac0d5 --- /dev/null +++ b/Build/source/utils/texinfo/doc/texinfo.5 @@ -0,0 +1,61 @@ +.\" texinfo(5) +.\" $Id: texinfo.5,v 1.2 2004/04/11 17:56:45 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 new file mode 100644 index 00000000000..8d20e47dee7 --- /dev/null +++ b/Build/source/utils/texinfo/doc/texinfo.tex @@ -0,0 +1,7217 @@ +% 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{2005-03-21.17} +% +% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 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 2, 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 texinfo.tex file; see the file COPYING. If not, write +% to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +% Boston, MA 02111-1307, USA. +% +% 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} + +\message{Basics,} +\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 + +% 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 + +% In some macros, we cannot use the `\? notation---the left quote is +% in some cases the escape char. +\chardef\backChar = `\\ +\chardef\colonChar = `\: +\chardef\commaChar = `\, +\chardef\dotChar = `\. +\chardef\exclamChar= `\! +\chardef\plusChar = `\+ +\chardef\questChar = `\? +\chardef\semiChar = `\; +\chardef\underChar = `\_ + +\chardef\spaceChar = `\ % +\chardef\spacecat = 10 +\def\spaceisspace{\catcode\spaceChar=\spacecat} + +{% for help with debugging. + % example usage: \expandafter\show\activebackslash + \catcode`\! = 0 \catcode`\\ = \active + !global!def!activebackslash{\} +} + +% 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 + +% 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). + \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \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. + % + \escapechar = `\\ % use backslash in output files. + \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. + \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 \oddfootingxxx.) + % The \baselineskip=24pt in plain's \makefootline has no effect. + \vskip 2\baselineskip + \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 \normalturnoffactive + \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 \unvbox#1 +\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\next{#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 occurence 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 + % We cannot use \next here, as it holds the macro to run; + % thus we 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 \next. +% (Similarily, 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\next\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 enviroments; they don't open a group. (The +% implementation of @end takes care not to call \endgroup in this +% special case.) + + +% At runtime, 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 +} + +% Evironment 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 \ptexi + \else\ifx\temp\jmacro \j + \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} + +% @! is an end-of-sentence bang. +\def\!{!\spacefactor=\endofsentencespacefactor} + +% @? is an end-of-sentence query. +\def\?{?\spacefactor=\endofsentencespacefactor} + +% @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 insert text of that file as input. +% +\def\include{\parseargusing\filenamecatcodes\includezzz} +\def\includezzz#1{% + \pushthisfilestack + \def\thisfile{#1}% + {% + \makevalueexpandable + \def\temp{\input #1 }% + \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\underChar = \active + \gdef\mathunderscore{% + \catcode\underChar=\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 + $\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 + } +} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{$\ptexbullet$} +\def\minus{$-$} + +% @dots{} outputs an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in a typewriter +% font as three actual period characters. +% +\def\dots{% + \leavevmode + \hbox to 1.5em{% + \hskip 0pt plus 0.25fil + .\hfil.\hfil.% + \hskip 0pt plus 0.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, to +% 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 we do). + +% double active backslashes. +% +{\catcode`\@=0 \catcode`\\=\active + @gdef@activebackslash{@catcode`@\=@active @otherbackslash} + @gdef@activebackslashdouble{% + @catcode@backChar=@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. I've +% tinkered with it a little for texinfo, but it's definitely from there. +% +% #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{(}{\backslashlparen}{#1}% + \HyPsdSubst{)}{\backslashrparen}{#1}% +} + +{\catcode\exclamChar = 0 \catcode\backChar = \other + !gdef!backslashlparen{\(}% + !gdef!backslashrparen{\)}% +} + +\ifpdf + \input pdfcolor + \pdfcatalog{/PageMode /UseOutlines}% + \def\dopdfimage#1#2#3{% + \def\imagewidth{#2}% + \def\imageheight{#3}% + % without \immediate, 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 + \ifx\empty\imagewidth\else width \imagewidth \fi + \ifx\empty\imageheight\else height \imageheight \fi + \ifnum\pdftexversion<13 + #1.pdf% + \else + {#1.pdf}% + \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. + \atdummies + \turnoffactive + \activebackslashdouble + \def\pdfdestname{#1}% + \backslashparens\pdfdestname + \pdfdest name{\pdfdestname} xyz% + }}% + % + % used to mark target names; must be expandable. + \def\pdfmkpgn#1{#1}% + % + \let\linkcolor = \Blue % was Cyan, but that seems light? + \def\endlink{\Black\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 + \activebackslash + \input \jobname.toc + \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 + \def\pdfurl#1{% + \begingroup + \normalturnoffactive\def\@{@}% + \makevalueexpandable + \leavevmode\Red + \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}} + \linkcolor #1\endlink} + \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} +\else + \let\pdfmkdest = \gobble + \let\pdfurl = \gobble + \let\endlink = \relax + \let\linkcolor = \relax + \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} +% +\def\setleading#1{% + \normalbaselineskip = #1\relax + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% 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 +\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} + +% Use cm as the default font prefix. +% To specify the font prefix, you must define \fontprefix +% 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} + +% Text fonts (11.2pt, magstep1). +\def\textnominalsize{11pt} +\edef\mainmagstep{\magstephalf} +\setfont\textrm\rmshape{10}{\mainmagstep} +\setfont\texttt\ttshape{10}{\mainmagstep} +\setfont\textbf\bfshape{10}{\mainmagstep} +\setfont\textit\itshape{10}{\mainmagstep} +\setfont\textsl\slshape{10}{\mainmagstep} +\setfont\textsf\sfshape{10}{\mainmagstep} +\setfont\textsc\scshape{10}{\mainmagstep} +\setfont\textttsl\ttslshape{10}{\mainmagstep} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun names and args. +\setfont\defbf\bfshape{10}{\magstep1} +\setfont\deftt\ttshape{10}{\magstep1} +\setfont\defttsl\ttslshape{10}{\magstep1} +\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} +\setfont\smalltt\ttshape{9}{1000} +\setfont\smallbf\bfshape{10}{900} +\setfont\smallit\itshape{9}{1000} +\setfont\smallsl\slshape{9}{1000} +\setfont\smallsf\sfshape{9}{1000} +\setfont\smallsc\scshape{10}{900} +\setfont\smallttsl\ttslshape{10}{900} +\font\smalli=cmmi9 +\font\smallsy=cmsy9 + +% Fonts for small examples (8pt). +\def\smallernominalsize{8pt} +\setfont\smallerrm\rmshape{8}{1000} +\setfont\smallertt\ttshape{8}{1000} +\setfont\smallerbf\bfshape{10}{800} +\setfont\smallerit\itshape{8}{1000} +\setfont\smallersl\slshape{8}{1000} +\setfont\smallersf\sfshape{8}{1000} +\setfont\smallersc\scshape{10}{800} +\setfont\smallerttsl\ttslshape{10}{800} +\font\smalleri=cmmi8 +\font\smallersy=cmsy8 + +% Fonts for title page (20.4pt): +\def\titlenominalsize{20pt} +\setfont\titlerm\rmbshape{12}{\magstep3} +\setfont\titleit\itbshape{10}{\magstep4} +\setfont\titlesl\slbshape{10}{\magstep4} +\setfont\titlett\ttbshape{12}{\magstep3} +\setfont\titlettsl\ttslshape{10}{\magstep4} +\setfont\titlesf\sfbshape{17}{\magstep1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\authorrm{\secrm} +\def\authortt{\sectt} + +% Chapter (and unnumbered) fonts (17.28pt). +\def\chapnominalsize{17pt} +\setfont\chaprm\rmbshape{12}{\magstep2} +\setfont\chapit\itbshape{10}{\magstep3} +\setfont\chapsl\slbshape{10}{\magstep3} +\setfont\chaptt\ttbshape{12}{\magstep2} +\setfont\chapttsl\ttslshape{10}{\magstep3} +\setfont\chapsf\sfbshape{17}{1000} +\let\chapbf=\chaprm +\setfont\chapsc\scbshape{10}{\magstep3} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 + +% Section fonts (14.4pt). +\def\secnominalsize{14pt} +\setfont\secrm\rmbshape{12}{\magstep1} +\setfont\secit\itbshape{10}{\magstep2} +\setfont\secsl\slbshape{10}{\magstep2} +\setfont\sectt\ttbshape{12}{\magstep1} +\setfont\secttsl\ttslshape{10}{\magstep2} +\setfont\secsf\sfbshape{12}{\magstep1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% Subsection fonts (13.15pt). +\def\ssecnominalsize{13pt} +\setfont\ssecrm\rmbshape{12}{\magstephalf} +\setfont\ssecit\itbshape{10}{1315} +\setfont\ssecsl\slbshape{10}{1315} +\setfont\ssectt\ttbshape{12}{\magstephalf} +\setfont\ssecttsl\ttslshape{10}{1315} +\setfont\ssecsf\sfbshape{12}{\magstephalf} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{1315} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled 1315 + +% Reduced fonts for @acro in text (10pt). +\def\reducednominalsize{10pt} +\setfont\reducedrm\rmshape{10}{1000} +\setfont\reducedtt\ttshape{10}{1000} +\setfont\reducedbf\bfshape{10}{1000} +\setfont\reducedit\itshape{10}{1000} +\setfont\reducedsl\slshape{10}{1000} +\setfont\reducedsf\sfshape{10}{1000} +\setfont\reducedsc\scshape{10}{1000} +\setfont\reducedttsl\ttslshape{10}{1000} +\font\reducedi=cmmi10 +\font\reducedsy=cmsy10 + +% 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. +% +\textfonts \rm + +% 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} +\setfont\shortcontbf\bfshape{10}{\magstep1} % no cmb12 +\setfont\shortcontsl\slshape{12}{1000} +\setfont\shortconttt\ttshape{12}{1000} + +%% 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} +\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}}}} +% 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 + % + \global\def\code{\begingroup + \catcode`\-=\active \catcode`\_=\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\arg{#1}% + \ifx\arg\keywordtrue + \allowcodebreakstrue + \else\ifx\arg\keywordfalse + \allowcodebreaksfalse + \else + \errhelp = \EMsimple + \errmessage{Unknown @allowcodebreaks option `\arg'}% + \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\arg{#1}% + \ifx\arg\worddistinct + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% + \else\ifx\arg\wordexample + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% + \else\ifx\arg\wordcode + \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \else + \errhelp = \EMsimple + \errmessage{Unknown @kbdinputstyle option `\arg'}% + \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 + +% @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 +} + +% @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}}% + }$% +} + +% 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 + + +\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 -\baselineskip + \global\advance\vsize by -\baselineskip +} + +\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} + + +% @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: + \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', which must be on a line + % by itself. + \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. + \obeylines % + \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. +\def\enddoignore{\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{% + \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 + % + % \definedummyword defines \#1 as \realbackslash #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{% + \expandafter\def\csname ##1\endcsname{\realbackslash ##1\space}% + }% + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{\realbackslash ##1}% + }% + \let\definedummyaccent\definedummyletter + % + % 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 + % + % (See comments in \indexdummies.) + \def\definedummyword##1{% + \expandafter\def\csname ##1\endcsname{@##1\space}% + }% + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{@##1}% + }% + \let\definedummyaccent\definedummyletter + % + % Do the redefinitions. + \commondummies +} + +% Called from \indexdummies and \atdummies. \definedummyword and +% \definedummyletter must be defined first. +% +\def\commondummies{% + % + \normalturnoffactive + % + \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{expansion}% + \definedummyword{minus}% + \definedummyword{pounds}% + \definedummyword{point}% + \definedummyword{print}% + \definedummyword{result}% + % + % Handle some cases of @value -- where it does not contain any + % (non-fully-expandable) commands. + \makevalueexpandable + % + % Normal spaces, not active ones. + \unsepspaces + % + % No macro expansion. + \turnoffmacros +} + +% \commondummiesnofonts: common to \commondummies and \indexnofonts. +% +% Better have this without active chars. +{ + \catcode`\~=\other + \gdef\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{samp}% + \definedummyword{strong}% + \definedummyword{tie}% + \definedummyword{uref}% + \definedummyword{url}% + \definedummyword{var}% + \definedummyword{verb}% + \definedummyword{w}% + } +} + +% \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{% + \expandafter\let\csname ##1\endcsname\asis + }% + % We can just ignore other control letters. + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{}% + }% + % 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\expansion{==>}% + \def\minus{-}% + \def\pounds{pounds}% + \def\point{.}% + \def\print{-|}% + \def\result{=>}% + % + % Don't write macro names. + \emptyusermacros +} + +\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}% + % + \ifvmode + \dosubindsanitize + \else + \dosubindwrite + \fi + }% + \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 + \escapechar=`\\ + \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: +% +% 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 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} +% +% ..., ready, GO: +% +\def\dosubindsanitize{% + % \lastskip and \lastpenalty cannot both be nonzero simultaneously. + \skip0 = \lastskip + \edef\lastskipmacro{\the\lastskip}% + \count255 = \lastpenalty + % + % If \lastskip is nonzero, that means the last item was a + % skip. And since a skip is discardable, that means this + % -\skip0 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-\skip0 + \fi + % + \dosubindwrite + % + \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\count255>9999 \penalty\count255 \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\skip0 + \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 + \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 frozes 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. + \def\tempa{{\rm }}% + \def\tempb{#1}% + \edef\tempc{\tempa}% + \edef\tempd{\tempb}% + \ifx\tempc\tempd + \ % + \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 \dotfill except takes at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \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{% + \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 this as the name of the chapter. +% page headings and footings can use it. @section does likewise. +% However, they are not reliable, because we don't use marks. +\def\thischapter{} +\def\thissection{} + +\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} +\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\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{% + \pchapsepmacro + {% + \chapfonts \rm + % + % Have to define \thissection 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\thissection{#1}% + \gdef\thischaptername{#1}% + % + % Only insert the separating space if we have a chapter/appendix + % number, and don't print the unnumbered ``number''. + \def\temptype{#2}% + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unnchap}% + \gdef\thischapter{#1}% + \else\ifx\temptype\Yomitfromtockeyword + \setbox0 = \hbox{}% contents like unnumbered, but no toc entry + \def\toctype{omit}% + \gdef\thischapter{}% + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% + \def\toctype{app}% + % We don't substitute the actual chapter name into \thischapter + % because we don't want its macros evaluated now. And we don't + % use \thissection because that changes with each section. + % + \xdef\thischapter{\putwordAppendix{} \appendixletter: + \noexpand\thischaptername}% + \else + \setbox0 = \hbox{#3\enspace}% + \def\toctype{numchap}% + \xdef\thischapter{\putwordChapter{} \the\chapno: + \noexpand\thischaptername}% + \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. + \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\sectionheading#1#2#3#4{% + {% + % Switch to the right set of fonts. + \csname #2fonts\endcsname \rm + % + % Insert space above the heading. + \csname #2headingbreak\endcsname + % + % Only insert the space after the number if we have a section number. + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unn}% + \gdef\thissection{#1}% + \else\ifx\temptype\Yomitfromtockeyword + % for @headings -- no section number, don't include in toc, + % and don't redefine \thissection. + \setbox0 = \hbox{}% + \def\toctype{omit}% + \let\sectionlevel=\empty + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{#4\enspace}% + \def\toctype{app}% + \gdef\thissection{#1}% + \else + \setbox0 = \hbox{#4\enspace}% + \def\toctype{num}% + \gdef\thissection{#1}% + \fi\fi\fi + % + % Write the toc entry (before \donoderef). See comments in \chfplain. + \writetocentry{\toctype\sectionlevel}{#1}{#4}% + % + % Write the node reference (= pdf destination for pdftex). + % Again, see comments in \chfplain. + \donoderef{#3}% + % + % 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 \turnoffactive + \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 \jobname.toc +} + +\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. + \def\thischapter{}% + \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 +} + + +% Normal (long) toc. +\def\contents{% + \startcontents{\putwordTOC}% + \openin 1 \jobname.toc + \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 \jobname.toc + \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, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% +\def\point{$\star$} +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} +\def\equiv{\leavevmode\lower.1ex\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 \tensf 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 + \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. +\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=\comment + \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 + % @cartouche defines \nonarrowing to inhibit narrowing + % at next level down. + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \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 + \smallexamplefonts \rm + \fi +} +\def\setsmalldispenv{% + \ifx\SETdispenvsize\nosmallword + \else + \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 + \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 + \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} +\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 + }% + } +\endgroup +\def\setupverbatim{% + \nonfillstart + \advance\leftskip by -\defbodyindent + % Easiest (and conventionally used) font for verbatim + \tt + \def\par{\leavevmode\egroup\box0\endgraf}% + \catcode`\`=\active + \tabexpand + % 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 + +% Start the processing of @deffn: +\def\startdefun{% + \ifnum\lastpenalty<10000 + \medbreak + \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 \defargscommonending, 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. + % + \ifnum\lastpenalty=10002 \penalty2000 \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 \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 10002 % 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 remainnig 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 +} +\def\badparencount{% + \errmessage{Unbalanced parentheses in @def}% + \global\parencount=0 +} +\def\badbrackcount{% + \errmessage{Unbalanced square braces 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? +\def\macrolist{} % List of all defined macros in the form + % \do\macro1\do\macro2... + +% 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 \. + +% 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 +} + +\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% + % Add the macroname to \macrolist + \toks0 = \expandafter{\macrolist\do}% + \xdef\macrolist{\the\toks0 + \expandafter\noexpand\csname\the\macname\endcsname}% + \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\do\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\do \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\next=#1\futurelet\nchar\braceorlinexxx} +\def\braceorlinexxx{% + \ifx\nchar\bgroup\else + \expandafter\parsearg + \fi \next} + +% We want to disable all macros during \shipout so that they are not +% expanded by \write. +\def\turnoffmacros{\begingroup \def\do##1{\let\noexpand##1=\relax}% + \edef\next{\macrolist}\expandafter\endgroup\next} + +% For \indexnofonts, 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. +% +\def\emptyusermacros{\begingroup + \def\do##1{\let\noexpand##1=\noexpand\asis}% + \edef\next{\macrolist}\expandafter\endgroup\next} + + +% @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 + \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 \thissection, +% 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 + \turnoffactive + \edef\writexrdef##1##2{% + \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef + ##1}{##2}}% these are parameters of \writexrdef + }% + \toks0 = \expandafter{\thissection}% + \immediate \writexrdef{title}{\the\toks0 }% + \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. + \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 + \leavevmode + \getfilename{#4}% + {\turnoffactive + % See comments at \activebackslashdouble. + {\activebackslashdouble \xdef\pdfxrefdest{#1}% + \backslashparens\pdfxrefdest}% + % + \ifnum\filenamelength>0 + \startlink attr{/Border [0 0 0]}% + goto file{\the\filename.pdf} name{\pdfxrefdest}% + \else + \startlink attr{/Border [0 0 0]}% + goto name{\pdfmkpgn{\pdfxrefdest}}% + \fi + }% + \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{% + \expandafter\gdef\csname XR#1\endcsname{#2}% remember this xref value. + % + % Was that xref control sequence that we just defined for a float? + \expandafter\iffloat\csname XR#1\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{#1}}% + \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. +% Similarily, 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\bigskip + % 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 + \line\bgroup\hss + \fi + % + % 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 \hss \egroup \bigbreak \fi % space after the 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 \thissection 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\thissection{\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 \turnoffactive + % 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 float, 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 +% \thissection 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,} +% and i18n. + +% @documentlanguage is usually given very early, just after +% @setfilename. If done too late, it may not override everything +% properly. Single argument is the language abbreviation. +% It would be nice if we could set up a hyphenation file here. +% +\parseargdef\documentlanguage{% + \tex % read txi-??.tex file in plain TeX. + % Read the file if it exists. + \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 + \endgroup +} +\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.} + + +% @documentencoding should change something in TeX eventually, most +% likely, but for now just recognize it. +\let\documentencoding = \comment + + +% Page size parameters. +% +\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, just 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 + \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{46\baselineskip}{6in}% + {\voffset}{.25in}% + {\bindingoffset}{36pt}% + {11in}{8.5in}% +}} + +% Use @smallbook to reset parameters for 7x9.5 (or so) format. +\def\smallbook{{\globaldefs = 1 + \parskip = 2pt plus 1pt + \textleading = 12pt + % + \internalpagesizes{7.5in}{5in}% + {\voffset}{.25in}% + {\bindingoffset}{16pt}% + {9.25in}{7in}% + % + \lispnarrowing = 0.3in + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = .5cm +}} + +% 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{51\baselineskip}{160mm} + {\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 + \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} + +\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 + +% \rawbackslash defines an active \ to do \backslashcurfont. +% \otherbackslash defines an active \ to be a literal `\' character with +% catcode other. +{\catcode`\\=\active + @gdef@rawbackslash{@let\=@backslashcurfont} + @gdef@otherbackslash{@let\=@realbackslash} +} + +% \realbackslash is an actual character `\' with catcode other, and +% \doublebackslash is two of them (for the pdf outlines). +{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\backslashcurfont}} + +\catcode`\\=\active + +% Used sometimes to turn off (effectively) the active characters +% even after parsing them. +@def@turnoffactive{% + @let"=@normaldoublequote + @let\=@realbackslash + @let~=@normaltilde + @let^=@normalcaret + @let_=@normalunderscore + @let|=@normalverticalbar + @let<=@normalless + @let>=@normalgreater + @let+=@normalplus + @let$=@normaldollar %$ font-lock fix + @unsepspaces +} + +% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of +% the literal character `\'. (Thus, \ is not expandable when this is in +% effect.) +% +@def@normalturnoffactive{@turnoffactive @let\=@normalbackslash} + +% 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 new file mode 100644 index 00000000000..15ef1dd0cab --- /dev/null +++ b/Build/source/utils/texinfo/doc/texinfo.txi @@ -0,0 +1,20513 @@ +\input texinfo.tex @c -*-texinfo-*- +@c $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 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 (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004 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.1 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 freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@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. +* 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 @* +59 Temple Place Suite 330 @* +Boston, MA 02111-1307 @* +USA @* +ISBN 1-882114-67-1 @c for version 4.0, September 1999. +@c ISBN 1-882114-65-5 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 + +@insertcopying + +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. +* Copying This Manual:: The GNU Free Documentation License. +* Command and Variable Index:: A menu containing commands and variables. +* Concept 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 Space:: How to insert the right amount of space + within a sentence. +* Inserting Accents:: How to insert accents and special characters. +* 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. +* minus:: How to insert a minus sign. +* math:: How to format a mathematical expression. +* 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. +* 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. +* 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:: + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual. + +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. + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual. + +@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}). + +When sending patches, if possible please do not encode or split them in +any way; it's much easier to deal with one plain text message, however +large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/, +GNU shar} is a convenient way of packaging multiple and/or binary files +for email. + + +@node Using Texinfo +@section Using Texinfo + +@cindex Using Texinfo in general +@cindex Texinfo, introduction to +@cindex Introduction to Texinfo + +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 @sc{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 +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 supporting arbitrary +scaling. It is intended to be platform-independent and easily +viewable, among other design goals; for a discussion, see +@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebeI.pdf}. 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 URI's 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 +@uref{ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex}. + +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 dots @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 @sc{ascii} characters except @samp{@@}, @samp{@{} and +@samp{@}} can appear in a Texinfo file and stand for themselves. +@samp{@@} is the escape character which introduces commands, 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 +@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 @sc{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. We +hope to eventually support the various quotation characters in +Unicode. + +@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 and most important, 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 causes GNU Emacs to insert multiple +spaces when you press the @key{TAB} key. + +@noindent +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 namea 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 contains commands for printing indices and +generating the table of contents, and 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@{@} 2004 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 also include the copying text again for +the benefit of online readers. Since the copying text begins with +a brief description of the manual, no other text is needed in this +case. The @samp{@@top} command itself helps @command{makeinfo} +determine the relationships between nodes. + +@example +@@ifnottex +@@node Top +@@top Short Sample + +@@insertcopying +@@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. @w{Robert J.@:} +Chassell greatly revised and extended the manual, starting with Edition +1.1. Brian Fox was responsible for the standalone Texinfo distribution +until version 3.8, and wrote the standalone @command{makeinfo} and +@command{info} 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 @w{David 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 strived 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 @sc{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 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 C-c @} +@itemx C-c 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 C-c ]} is easier than typing @kbd{C-c 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 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 is often 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 C-c @{ @r{Insert braces.} +C-c C-c ] +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} + +@@insertcopying +@@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. + +@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}). + +We also strongly recommend using @code{@@insertcopying} in the Top node +of your manual (@pxref{The Top Node}), although it is not required +legally. Here's why: + +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 *}). Therefore, an explicit @code{@@insertcopying} +in the Top node makes it apparent to readers that the manual is free. + +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). And +therefore again, the @code{@@insertcopying} in the Top node is valuable +because it makes the copying permissions visible and thus promotes +freedom. + +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 incantantion 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 pre-defined page +headings prior to defining your own. Write an @code{@@headings} command +immediately after the @code{@@end titlepage} command.@refill + +You can use @code{@@headings} as follows:@refill + +@table @code +@item @@headings off +Turn off printing of page headings.@refill + +@item @@headings single +Turn on page headings appropriate for single-sided printing. +@refill + +@item @@headings double +@itemx @@headings on +Turn on page headings appropriate for double-sided printing. The two +commands, @code{@@headings on} and @code{@@headings double}, are +synonymous.@refill + +@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:@refill + +@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.@refill + +You can also specify your own style of page heading and footing. +@xref{Headings, , Page Headings}, for more information.@refill + + +@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 the @code{@@insertcopying} command +(@pxref{Document Permissions}) to provide a brief description of the +manual (including the version number) and copying permissions, 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 also conventional 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 ifnottext}, 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 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 +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:: +* Concept 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 instead of by number.@refill + +For Info file output, the @code{@@unnumbered} and @code{@@appendix} +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 + +To create an appendix or an unnumbered chapter, 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.@refill + + +@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 +@comment node-name, next, previous, up +@section @code{@@section} +@findex section + +In a printed manual, an @code{@@section} command identifies a +numbered section within a chapter. The section title appears in the +table of contents. In Info, an @code{@@section} command provides a +title for a segment of text, underlined with @samp{=}.@refill + +This section is headed with an @code{@@section} command and looks like +this in the Texinfo file:@refill + +@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.@refill + +Thus, + +@example +@@section This is a section +@end example + +@noindent +produces + +@example +@group +This is a section +================= +@end group +@end example + +@noindent +in Info. + + +@node unnumberedsec appendixsec heading +@comment node-name, next, previous, up +@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. +(@xref{section, , @code{@@section}}.)@refill + +@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 + + +@node subsection +@comment node-name, next, previous, up +@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,@refill + +@example +@@subsection This is a subsection +@end example + +@noindent +produces + +@example +@group +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 +@comment node-name, next, previous, up +@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}}.)@refill + +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.@refill + +@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 + +In Info, `subsub' titles are underlined with periods. +For example,@refill + +@example +@@subsubsection This is a subsubsection +@end example + +@noindent +produces + +@example +@group +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 create a node, write an @code{@@node} command at the beginning of a +line, and follow it with up to four arguments, separated by commas, on +the rest of the same line. The first argument is required; it is the +name of this node. The subsequent arguments are the names of the +`Next', `Previous', and `Up' pointers, in that order, and may be omitted +if your Texinfo document is hierarchically organized (@pxref{makeinfo +Pointer Creation}). + +You may insert spaces before each name if you wish; the spaces are +ignored. You must write the name of the node and (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}.) + +@quotation Note +The GNU Emacs Texinfo mode updating commands work +only with Texinfo files in which @code{@@node} lines are followed by chapter +structuring lines. @xref{Updating Requirements}. +@end quotation + +@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. 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 that 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 printed 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:@refill + +@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}.)@refill + +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.@refill + +The template for a fully-written-out node line with `Next', `Previous', +and `Up' pointers looks like this:@refill + +@example +@@node @var{node-name}, @var{next}, @var{previous}, @var{up} +@end example + +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 Previous node of Top node +On the other hand, do not define the `Previous' node of the Top node to +be @samp{(dir)}, as it causes confusing behavior for users: if you are +in the Top node and hits @key{DEL} to go backwards, you wind up in the +middle of the some other entry in the @file{dir} file, which has nothing +to do with what you were reading. + +@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. + +For concreteness, here is an example with explicit pointers (which you +can maintain automatically with the texinfo mode commands): + +Or you can leave the pointers off entirely and let the tools implicitly +define them. This is recommended. Thus: + +@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. + +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. + +This implicit node pointer insertion feature in @code{makeinfo} +relieves you from the need to update menus and pointers manually or +with Texinfo mode commands. (@xref{Updating Nodes and Menus}.) + +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 the 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. +Spaces are always ignored after @code{@@anchor}. + +Anchor names and node names may not conflict. Anchors and nodes are +given similar treatment in some ways; for example, the @code{goto-node} +command in standalone Info takes either an anchor name or a node name as +an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) + + +@node 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 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 aside from not working with +@command{makeinfo}'s implicit pointer creation, it also makes the XML +output incorrect, since it does not reflect the true document +structure. So, unfortunately 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. + + +@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. If you include this argument, it becomes +the first part of the cross reference. It is usually omitted.@refill + +@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, see @@ref@{Hurricanes@}. +@end example + +@noindent produces (in Info): + +@example +For more information, see *Note Hurricanes::. +@end example + +@noindent and (in printed output): + +@quotation +For more information, see Section 8.2 [Hurricanes], page 123. +@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: + +@example +Sea surges are described in *Note Hurricanes::. +@end example + +As a general rule, 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. + + +@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 you use it @emph{only} inside parentheses +and you do @emph{not} type a comma or period (or anything else) after +the command's closing brace. 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'.@refill + +@item +The Info formatting commands automatically end the reference with a +closing colon or period.@refill +@end enumerate + +Because one type of formatting automatically inserts closing +punctuation and the other does not, you should use @code{@@pxref} +@emph{only} inside parentheses as part of another sentence. Also, you +yourself should not insert punctuation after the reference (or any +other text), as you do with @code{@@xref}. In the Info +output, such text would follow a period, which is grammatically wrong. + +@code{@@pxref} is designed so that the output looks right and works +right between parentheses 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.@refill + +@noindent +With one argument, a parenthetical cross reference looks like +this:@refill + +@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:@refill + +@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 + +@need 1500 +@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}}).@refill + +@quotation Caution +Use @code{@@pxref} only as a parenthetical +reference. Do not try to use @code{@@pxref} as a clause in a sentence. +It will look bad in either the Info file, the printed output, or +both.@refill +@end quotation + +Parenthetical cross references look best at the ends of sentences. +Although they technically work 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 +definitions. + +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(1)@} program @dots{} +@end example + +@noindent produces: +@display +The @uref{/man.cgi/1/ls,,ls(1)} program @dots{} +@end display + +@noindent but with HTML: +@example +The <a href="/man.cgi/1/ls">ls(1)</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{@@kenv}}. + +@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 @sc{ascii} control character.@refill +@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. + +@need 700 +For example, + +@example +The function returns @@code@{nil@}. +@end example + +@noindent +produces this in the printed manual: + +@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 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. + + +@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 +@comment node-name, next, previous, up +@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 + +@need 700 +For example, to produce @kbd{C-x @key{ESC}} you would type:@refill + +@example +@@kbd@{C-x @@key@{ESC@}@} +@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 DEL +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}. + +@c I don't think this is a good explanation. +@c I think it will puzzle readers more than it clarifies matters. -- rms. +@c In other words, use @code{@@kbd} for what you do, and use @code{@@key} +@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to +@c the beginning of the sentence. The @code{@@key@{META@}} key is often in +@c the lower left of the keyboard.''@refill + +@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 @sc{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 @sc{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 abbreivation 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, and for common abbreviations like +`etc.@:', we consider them to be overkill. + +@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 +@comment node-name, next, previous, up +@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 + +Texinfo 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 +rselects 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, when 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 with 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 output in a Texinfo manual. Here is an example; +the output you see is just the same as the input, with a line +@code{@@verbatim} before and a line @code{@@end verbatim} after. + +@verbatim +This is an example of text written in a @verbatim +block. No character substitutions are made. All commands +are ignored, until `<at>end verbatim'. + +In the printed manual, the text is typeset in a +fixed-width font, and not indented or filled. All +spaces and blank lines are significant, including tabs. +@end verbatim + +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 +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. + +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 reliably include files in other directories in a +distribution, for instance: + +@example +@@include @@value@{top_srcdir@}/NEWS +@end example + +@noindent (You still have to get @code{top_srcdir} defined in the +first place.) + + +@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 group +@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. + +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{@@listofloats} 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 basic 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 +@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript +format). +@item +@pindex pdftex@r{, and images} +PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). +@item +@code{makeinfo} 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 first thing in a paragraph, for +example if you want two images side-by-side, you must precede it with +@code{@@noindent} (@pxref{noindent,,@code{@@noindent}}). Otherwise it +will be displayed on a line by itself. 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 +When producing html, @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. If you want an empty +@code{alt} string, use @code{@@-}. 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. + +@cindex GIF images, unsupported due to patents +@cindex PNG image format +@cindex JPG 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. (We cannot support GIF format directly due to +software patents.) + +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. + +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 pounds currency symbol. +@item The minus sign. +@item Mathematical expressions. +@item Glyphs for evaluation, macros, errors, etc. +@item Footnotes. +@item Images. +@end itemize +@end iftex + +@menu +* Atsign Braces Comma:: Inserting @@ and @{@} and ,. +* Inserting Space:: How to insert the right amount of space + within a sentence. +* Inserting Accents:: How to insert accents and special characters. +* 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. +* minus:: How to insert a minus sign. +* math:: How to format a mathematical expression. +* 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.ppp + + +@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 chacter would confuse Texinfo's parsing for these +commands, you must use the command @samp{@comma{}} instead if you want +to have an actual comma in the output. 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 anywhere, there is no need for it +anywhere except in this unusual case. + + +@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. +* 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 +The s.o.p.@@: has three parts @dots{} +The s.o.p. has three parts @dots{} +@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{s.o.p.} in the second +line. +@end iftex + +@quotation +The s.o.p.@: has three parts @dots{}@* +The s.o.p. has three parts @dots{} +@end quotation + +@noindent +(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating +Procedure''.) + +@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 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. + +To get the true accented characters output in Info, and not just the +ASCII transliterations, you can use the @option{--enable-encoding} +option to @command{makeinfo} (@pxref{makeinfo options}). + +@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 {@@questiondown@{@}} {Output} {hacek/check/caron accent} +@item 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 {x@@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 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 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 + +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 + +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 + +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 + +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 relatively recently. In plain +Info, it is the word @samp{Euro }. (The space is included in the text +transliteration since typically there would be no space 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). + + +@node pounds +@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling +@findex pounds + +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 minus +@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign +@findex minus + +@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 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 + +Thus, the @code{@@math} command has no effect on the Info and HTML +output; @command{makeinfo} just reproduces the input, it does not try +to interpret the mathematics in any way. + +@code{@@math} implies @code{@@tex}. This not only makes it possible to +write superscripts and subscripts (as in the above example), but also +allows you to use any of the plain @TeX{} math control sequences. It's +conventional to use @samp{\} instead of @samp{@@} for these commands. +As in: +@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'll 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 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.@refill + +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. +* 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. +@end table + +Info output is not hyphenated, so these commands have no effect there. + + +@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 indenting manual. 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 function 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. + +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 specifed. + +@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 value + +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{cc}}: Set the Document Language + +@findex documentlanguage +@cindex Language, declaring +@cindex Document language, declaring + +The @code{@@documentlanguage} command declares the current document +language. Write it on a line by itself, with a two-letter ISO-639 +language code following (list is included below). If you have a +multilingual document, the intent is to be able to use this command +multiple times, to declare each language change. If the command is not +used at all, the default is @code{en} for English. + +@cindex @file{txi-@var{cc}.tex} +At present, this command is ignored in Info and HTML output. For +@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it +exists). Such a file appropriately redefines the various English words +used in @TeX{} output, such as `Chapter', `See', and so on. + +@cindex Hyphenation patterns, language-dependent +It would be good if this command also changed @TeX{}'s ideas of the +current hyphenation patterns (via the @TeX{} primitive +@code{\language}), but this is unfortunately not currently implemented. + +@cindex ISO 639 codes +@cindex Language codes +Hereare the valid language codes, from ISO-639. + +@multitable @columnfractions .07 .26 .07 .26 .07 .26 +@item +@code{aa} @tab Afar @tab +@code{ab} @tab Abkhazian @tab +@code{af} @tab Afrikaans +@item +@code{am} @tab Amharic @tab +@code{ar} @tab Arabic @tab +@code{as} @tab Assamese +@item +@code{ay} @tab Aymara @tab +@code{az} @tab Azerbaijani @tab +@code{ba} @tab Bashkir +@item +@code{be} @tab Byelorussian @tab +@code{bg} @tab Bulgarian @tab +@code{bh} @tab Bihari +@item +@code{bi} @tab Bislama @tab +@code{bn} @tab Bengali; Bangla @tab +@code{bo} @tab Tibetan +@item +@code{br} @tab Breton @tab +@code{ca} @tab Catalan @tab +@code{co} @tab Corsican +@item +@code{cs} @tab Czech @tab +@code{cy} @tab Welsh @tab +@code{da} @tab Danish +@item +@code{de} @tab German @tab +@code{dz} @tab Bhutani @tab +@code{el} @tab Greek +@item +@code{en} @tab English @tab +@code{eo} @tab Esperanto @tab +@code{es} @tab Spanish +@item +@code{et} @tab Estonian @tab +@code{eu} @tab Basque @tab +@code{fa} @tab Persian +@item +@code{fi} @tab Finnish @tab +@code{fj} @tab Fiji @tab +@code{fo} @tab Faroese +@item +@code{fr} @tab French @tab +@code{fy} @tab Frisian @tab +@code{ga} @tab Irish +@item +@code{gd} @tab Scots Gaelic @tab +@code{gl} @tab Galician @tab +@code{gn} @tab Guarani +@item +@code{gu} @tab Gujarati @tab +@code{ha} @tab Hausa @tab +@code{he} @tab Hebrew +@item +@code{hi} @tab Hindi @tab +@code{hr} @tab Croatian @tab +@code{hu} @tab Hungarian +@item +@code{hy} @tab Armenian @tab +@code{ia} @tab Interlingua @tab +@code{id} @tab Indonesian +@item +@code{ie} @tab Interlingue @tab +@code{ik} @tab Inupiak @tab +@code{is} @tab Icelandic +@item +@code{it} @tab Italian @tab +@code{iu} @tab Inuktitut @tab +@code{ja} @tab Japanese +@item +@code{jw} @tab Javanese @tab +@code{ka} @tab Georgian @tab +@code{kk} @tab Kazakh +@item +@code{kl} @tab Greenlandic @tab +@code{km} @tab Cambodian @tab +@code{kn} @tab Kannada +@item +@code{ks} @tab Kashmiri @tab +@code{ko} @tab Korean @tab +@code{ku} @tab Kurdish +@item +@code{ky} @tab Kirghiz @tab +@code{la} @tab Latin @tab +@code{ln} @tab Lingala +@item +@code{lt} @tab Lithuanian @tab +@code{lo} @tab Laothian @tab +@code{lv} @tab Latvian, Lettish +@item +@code{mg} @tab Malagasy @tab +@code{mi} @tab Maori @tab +@code{mk} @tab Macedonian +@item +@code{ml} @tab Malayalam @tab +@code{mn} @tab Mongolian @tab +@code{mo} @tab Moldavian +@item +@code{mr} @tab Marathi @tab +@code{ms} @tab Malay @tab +@code{mt} @tab Maltese +@item +@code{my} @tab Burmese @tab +@code{na} @tab Nauru @tab +@code{ne} @tab Nepali +@item +@code{nl} @tab Dutch @tab +@code{no} @tab Norwegian @tab +@code{oc} @tab Occitan +@item +@code{om} @tab (Afan) Oromo @tab +@code{or} @tab Oriya @tab +@code{pa} @tab Punjabi +@item +@code{pl} @tab Polish @tab +@code{ps} @tab Pashto, Pushto @tab +@code{pt} @tab Portuguese +@item +@code{qu} @tab Quechua @tab +@code{rm} @tab Rhaeto-Romance @tab +@code{rn} @tab Kirundi +@item +@code{ro} @tab Romanian @tab +@code{ru} @tab Russian @tab +@code{rw} @tab Kinyarwanda +@item +@code{sa} @tab Sanskrit @tab +@code{sd} @tab Sindhi @tab +@code{sg} @tab Sangro +@item +@code{sh} @tab Serbo-Croatian @tab +@code{si} @tab Sinhalese @tab +@code{sk} @tab Slovak +@item +@code{sl} @tab Slovenian @tab +@code{sm} @tab Samoan @tab +@code{sn} @tab Shona +@item +@code{so} @tab Somali @tab +@code{sq} @tab Albanian @tab +@code{sr} @tab Serbian +@item +@code{ss} @tab Siswati @tab +@code{st} @tab Sesotho @tab +@code{su} @tab Sundanese +@item +@code{sv} @tab Swedish @tab +@code{sw} @tab Swahili @tab +@code{ta} @tab Tamil +@item +@code{te} @tab Telugu @tab +@code{tg} @tab Tajik @tab +@code{th} @tab Thai +@item +@code{ti} @tab Tigrinya @tab +@code{tk} @tab Turkmen @tab +@code{tl} @tab Tagalog +@item +@code{tn} @tab Setswana @tab +@code{to} @tab Tonga @tab +@code{tr} @tab Turkish +@item +@code{ts} @tab Tsonga @tab +@code{tt} @tab Tatar @tab +@code{tw} @tab Twi +@item +@code{ug} @tab Uighur @tab +@code{uk} @tab Ukrainian @tab +@code{ur} @tab Urdu +@item +@code{uz} @tab Uzbek @tab +@code{vi} @tab Vietnamese @tab +@code{vo} @tab Volapuk +@item +@code{wo} @tab Wolof @tab +@code{xh} @tab Xhosa @tab +@code{yi} @tab Yiddish +@item +@code{yo} @tab Yoruba @tab +@code{za} @tab Zhuang @tab +@code{zh} @tab Chinese +@item +@code{zu} @tab Zulu +@end multitable + + +@node documentencoding +@section @code{@@documentencoding @var{enc}}: Set Input Encoding + +@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. + +At present, Texinfo supports only these encodings: + +@table @code +@item US-ASCII +This has no particular effect, but it's included for completeness. + +@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. + +A full description of the encodings is beyond our scope here; +one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. +@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, if the option @option{--enable-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 + +@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 all other cases, it is recognized but ignored. + + +@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 +@cindex Braces, in macro arguments +To insert a comma, brace, or backslash in an argument, prepend a +backslash, as in + +@example +@@@var{macname} @{\\\@{\@}\,@} +@end example + +@noindent +which will pass the (almost certainly error-producing) argument +@samp{\@{@},} to @var{macname}. 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 pre-defined macro +(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the +enclosure definition will override the built-in definition. + +An enclosure command defined this way takes one argument in braces; this +is intended for new markup commands (@pxref{Marking Text}). + +@findex phoo +For example, you can write: + +@example +@@definfoenclose phoo,//,\\ +@end example + +@noindent +near the beginning of a Texinfo file to define @code{@@phoo} as an Info +formatting command that inserts `//' before and `\\' after the argument +to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you +want `//bar\\' highlighted in Info. + +Also, for @TeX{} formatting, you could write + +@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. + +Perhaps the most 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{}}). + +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}. + +@cindex @LaTeX{}, processing with @command{texi2dvi} +@command{texi2dvi} can also be used to process @LaTeX{} files; simply +run @samp{texi2dvi filename.ext}. + +@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}. + +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}). + +@pindex pdfcolor.tex@r{, installing} +Likewise for @file{pdfcolor.tex}, if it is not already installed and you +use pdftex. + +@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 + +(@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}; this simply executes the +@command{texi2dvi} script with the @option{--pdf} option +(@pxref{Format with texi2dvi}). If for some reason you want to +process 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. +59 Temple Place Suite 330 +Boston, MA @ @ 02111-1307 +USA +Telephone: @w{+1-617-542-5942} +Fax: (including Japan) @w{+1-617-542-2652} +Free Dial Fax (in Japan): +@w{ } @w{ } @w{ } 0031-13-2473 (KDD) +@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) +Electronic mail: @code{gnu@@gnu.org} +@end group +@end display + +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 --docbook +@opindex --docbook +Generate Docbook output rather than Info. + +@item --enable-encoding +@opindex --enable-encoding +Output accented and special characters in Info or plain text output +based on @samp{@@documentencoding}. +@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting Accents}. + +@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 --reference-limit=@var{limit} +@itemx -r @var{limit} +@opindex --reference-limit=@var{limit} +@opindex -r @var{limit} +Set the value of the number of references to a node that +@code{makeinfo} will make without reporting a warning. If a node has more +than this number of references in it, @code{makeinfo} will make the +references but also report a warning. The default is 1000. + +@item --split-size=@var{num} +@opindex --split-size=@var{num} +Keep Info files to at most @var{num} characters; default is 300,000. + +@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. + +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). 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 --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. + +@item --dir-file=@var{name} +@itemx -d @var{name} +@opindex --dir-file=@var{name} +@opindex -d @var{name} +Specify file name of the Info directory file. This is equivalent to +using the @var{dir-file} argument. + +@item --entry=@var{text} +@itemx -e @var{text} +@opindex --entry=@var{text} +@opindex -e @var{text} +Insert @var{text} as an Info directory entry; @var{text} should have the +form of an Info menu item line plus zero or more extra lines starting +with whitespace. If you specify more than one entry, they are all +added. If you don't specify any entries, they are determined from +information in the Info file itself. + +@item --help +@itemx -h +@opindex --help +@opindex -h +Display a usage message listing basic usage and all available options, +then exit successfully. + +@item --info-file=@var{file} +@itemx -i @var{file} +@opindex --info-file=@var{file} +@opindex -i @var{file} +Specify Info file to install in the directory. +Equivalent to using the @var{info-file} argument. + +@item --info-dir=@var{dir} +@itemx -D @var{dir} +@opindex --info-dir=@var{dir} +@opindex -D @var{dir} +Specify the directory where the directory file @file{dir} resides. +Equivalent to @samp{--dir-file=@var{dir}/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 --quiet +@opindex --quiet +Suppress warnings. + +@item --remove +@itemx -r +@opindex --remove +@opindex -r +Same as @samp{--delete}. + +@item --section=@var{sec} +@itemx -s @var{sec} +@opindex --section=@var{sec} +@opindex -s @var{sec} +Put this file's entries in section @var{sec} of the directory. If you +specify more than one section, all the entries are added in each of the +sections. If you don't specify any sections, they are determined from +information in the Info file itself. + +@item --version +@itemx -V +@opindex --version +@opindex -V +@cindex Version number, 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 the +@option{--css-include=@var{file}} option to @command{makeinfo}. This +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 each +manual is either available as a monolithic file @file{manual.html}, or a +split subdirectory @file{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+2217 +@item @code{@@pounds} @tab U+00A3 +@item @code{@@print} @tab @samp{-|} +@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 + +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.) + +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 @@: +Indicate to @TeX{} that an immediately preceding period, question +mark, exclamation mark, or colon does not end a sentence. Prevent +@TeX{} from inserting extra whitespace as it does at the end of a +sentence. The command has no effect on the Info file output. +@xref{Not Ending a Sentence}. + +@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 @@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, , Making a Two-column Table}.@refill + +@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 @@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 @sc{ascii} control character. Insert actual control character +into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill +@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 @@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 @@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}}.@refill + +@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}}.@refill + +@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}}.@refill + +@item @@noindent +Prevent text from being indented as if it were a new paragraph. +@xref{noindent, , @code{@@noindent}}.@refill + +@item @@novalidate +Suppress validation of node references, omit creation of auxiliary files +with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}. + +@item @@O@{@} +@itemx @@o@{@} +Generate the uppercase and lowercase O-with-slash letters, respectively: +@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 @@thisfile +@itemx @@thispage +@itemx @@thistitle +Only allowed in a heading or footing. Stands for the number and name of +the current chapter (in the format `Chapter 1: Title'), the chapter name +only, the filename, the current page number, and the title of the +document, respectively. @xref{Custom Headings, , How to Make Your Own +Headings}.@refill + +@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, and never take any +argument. The two characters (@@ and the other one) are complete in +themselves; none is followed by braces. The non-alphabetic commands +are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}}, +@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and +@code{@@@}}.@refill + +@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 (C) 2004 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 (see rcsintro(1)) version control +systems, which expand it into a string such as: +@example +$Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 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 your manual has invariant sections (again, see the license itself for +details), then don't forget to 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.128 2004/12/29 15:06:41 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{} 2004 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.1 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 freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@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 + +@insertcopying +@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 Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@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{} 2004 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{} 2004 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.@refill + +@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:@refill + +@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.@refill + +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.@refill + +@need 950 +Here are the six heading and footing commands:@refill + +@findex everyheading +@findex everyfooting +@table @code +@item @@everyheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} + +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.@refill + +@findex evenheading +@findex evenfooting +@findex oddheading +@findex oddfooting +@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} + +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.@refill + +@need 1000 +Here are the @samp{@@this@dots{}} commands:@refill + +@table @code +@findex thispage +@item @@thispage +Expands to the current page number.@refill +@c !!! Karl Berry says that `thissection' can fail on page breaks. +@ignore +@item @@thissection +Expands to the name of the current section.@refill +@end ignore + +@findex thischaptername +@item @@thischaptername +Expands to the name of the current chapter.@refill + +@findex thischapter +@item @@thischapter +Expands to the number and name of the current +chapter, in the format `Chapter 1: Title'.@refill + +@findex thistitle +@item @@thistitle +Expands to the name of the document, as specified by the +@code{@@settitle} command.@refill + +@findex thisfile +@item @@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.)@refill +@end table + +@noindent +You can also use the @code{@@today@{@}} command, which expands to the +current date, in `1 Jan 1900' format.@refill +@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:@refill + +@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.@refill + + +@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 Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@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 Concept Index +@unnumbered Concept Index + +@printindex cp + + +@bye diff --git a/Build/source/utils/texinfo/doc/txi-cs.tex b/Build/source/utils/texinfo/doc/txi-cs.tex new file mode 100644 index 00000000000..cdbc3c0d226 --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-cs.tex @@ -0,0 +1,74 @@ +% $Id: txi-cs.tex,v 1.3 2004/04/11 17:56:45 karl Exp $ +% Czech translation for texinfo.tex. +% +% Copyright (C) 1999, 2000 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 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{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 new file mode 100644 index 00000000000..f3726c3677a --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-de.tex @@ -0,0 +1,79 @@ +% txi-de.tex -- adaptation to German for texinfo.tex. +% $Id: txi-de.tex,v 1.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 1999 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 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 new file mode 100644 index 00000000000..721c49a49f1 --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-en.tex @@ -0,0 +1,69 @@ +% 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.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 1999 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 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{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 new file mode 100644 index 00000000000..334e2d1e109 --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-es.tex @@ -0,0 +1,58 @@ +% txi-es.tex -- TeX macros to handle Spanish language documents. +% +% Copyright (C) 1999 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 2, 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. +% + +% +% 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 new file mode 100644 index 00000000000..0a83f04ac0d --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-fr.tex @@ -0,0 +1,73 @@ +% txi-fr.tex -- TeX macros to handle French language for texinfo.tex documents. +% $Id: txi-fr.tex,v 1.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 1999 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 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. + +% 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 new file mode 100644 index 00000000000..28e51eaa3f0 --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-it.tex @@ -0,0 +1,69 @@ +% 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.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 1999 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 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{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-nl.tex b/Build/source/utils/texinfo/doc/txi-nl.tex new file mode 100644 index 00000000000..aab69f7ecb0 --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-nl.tex @@ -0,0 +1,68 @@ +% Dutch translation for texinfo.tex. +% $Id: txi-nl.tex,v 1.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 1999 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 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. + +% 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 new file mode 100644 index 00000000000..a4e589382ed --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-no.tex @@ -0,0 +1,69 @@ +% 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 new file mode 100644 index 00000000000..b5895a2942d --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-pl.tex @@ -0,0 +1,73 @@ +% txi-pl.tex -- adaptation to Polish for texinfo.tex. +% $Id: txi-pl.tex,v 1.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 2003 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 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. +% +% Written by Wojciech Polak <polak@gnu.org> on 29-03-2003. +% Modified by Staszek Wawrykiewicz <staw@gust.org.pl> on 01-04-2003. +% +\prefixing +\gdef\putwordAppendix{Suplement} +\gdef\putwordChapter{Rozdzia/l} +\gdef\putwordfile{plik} +\gdef\putwordin{w} +\gdef\putwordIndexIsEmpty{(Skorowidz jest pusty)} +\gdef\putwordIndexNonexistent{(Brak skorowidza)} +\gdef\putwordInfo{Info} +\gdef\putwordInstanceVariableof{Przyk/ladowa zmienna} +\gdef\putwordMethodon{Metoda} +\gdef\putwordNoTitle{Brak tytu/lu} +\gdef\putwordof{z} +\gdef\putwordon{na} +\gdef\putwordpage{strona} +\gdef\putwordsection{cz/e/s/c} +\gdef\putwordSection{Cz/e/s/c} +\gdef\putwordsee{zobacz} +\gdef\putwordSee{Zobacz} +\gdef\putwordShortTOC{Kr/otka zawarto/s/c} +\gdef\putwordTOC{Spis tre/sci} +% +\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/snia} +\gdef\putwordMOct{pa/xdziernika} +\gdef\putwordMNov{listopada} +\gdef\putwordMDec{grudnia} +% +\gdef\putwordDefmac{Makro} +\gdef\putwordDefspec{Specjalna forma} +\gdef\putwordDefvar{Zmienna} +\gdef\putwordDefopt{Opcja u/zytkownika} +\gdef\putwordDeffunc{Funkcja} +\nonprefixing +% +% 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 new file mode 100644 index 00000000000..c65bc5e1d5a --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-pt.tex @@ -0,0 +1,69 @@ +% txi-pt.tex -- adaptation to Portuguese for texinfo.tex. +% +% Copyright (C) 1999 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 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-tr.tex b/Build/source/utils/texinfo/doc/txi-tr.tex new file mode 100644 index 00000000000..eafba9f9848 --- /dev/null +++ b/Build/source/utils/texinfo/doc/txi-tr.tex @@ -0,0 +1,82 @@ +% txi-en.tex -- adaptation to Turkish for texinfo.tex. +% $Id: txi-tr.tex,v 1.3 2004/04/11 17:56:45 karl Exp $ +% +% Copyright (C) 2003 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 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/version-stnd.texi b/Build/source/utils/texinfo/doc/version-stnd.texi new file mode 100644 index 00000000000..32973a788b2 --- /dev/null +++ b/Build/source/utils/texinfo/doc/version-stnd.texi @@ -0,0 +1,4 @@ +@set UPDATED 14 December 2004 +@set UPDATED-MONTH December 2004 +@set EDITION 4.8 +@set VERSION 4.8 diff --git a/Build/source/utils/texinfo/doc/version.texi b/Build/source/utils/texinfo/doc/version.texi new file mode 100644 index 00000000000..ae55f879d47 --- /dev/null +++ b/Build/source/utils/texinfo/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 29 December 2004 +@set UPDATED-MONTH December 2004 +@set EDITION 4.8 +@set VERSION 4.8 diff --git a/Build/source/utils/texinfo/doc/win32.mak b/Build/source/utils/texinfo/doc/win32.mak new file mode 100644 index 00000000000..97c0c22df89 --- /dev/null +++ b/Build/source/utils/texinfo/doc/win32.mak @@ -0,0 +1,41 @@ +################################################################################ +# +# Makefile : TeXInfo / Doc +# Author : Fabrice Popineau <Fabrice.Popineau@supelec.fr> +# Platform : Win32, Microsoft VC++ 6.0, depends upon fpTeX 0.5 sources +# Time-stamp: <03/08/14 21:22:55 popineau> +# +################################################################################ +root_srcdir = ..\..\.. +!ifdef DEVELOPMENT +INCLUDE=$(INCLUDE);$(root_srcdir)\texk.development +!else +INCLUDE=$(INCLUDE);$(root_srcdir)\texk +!endif + +# Copyright (C) 1994, 1995, 1996, 1997 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy, distribute and modify it. + +!include <msvc/common.mak> + +default: all + +all: + +infofiles = info-stnd.info info.info texinfo.info +pdfdocfiles = info-stnd.pdf info.pdf texinfo.pdf +htmldocfiles = info-stnd.html info.html texinfo.html +docsubdir = texinfo + +install:: install-doc + +depend:: + +!include <msvc/install.mak> +!include <msvc/clean.mak> + +# +# Local Variables: +# mode: makefile +# End:
\ No newline at end of file |