From 15da023077f02380356169c9b5f4a62a6dc51f63 Mon Sep 17 00:00:00 2001 From: markm Date: Thu, 14 Jan 1999 19:35:19 +0000 Subject: Upgrade texinfo to the latest-and-greatest. This has big improvements to the .info file utility support and much recent OSS requires its features. --- contrib/texinfo/doc/Makefile.am | 57 + contrib/texinfo/doc/Makefile.in | 332 + contrib/texinfo/doc/README | 27 + contrib/texinfo/doc/epsf.tex | 546 ++ contrib/texinfo/doc/info-stnd.texi | 1373 +++ contrib/texinfo/doc/info.texi | 911 ++ contrib/texinfo/doc/macro.texi | 177 + contrib/texinfo/doc/texinfo.tex | 4977 ++++++++++ contrib/texinfo/doc/texinfo.txi | 17280 +++++++++++++++++++++++++++++++++++ contrib/texinfo/doc/userdoc.texi | 1270 +++ 10 files changed, 26950 insertions(+) create mode 100644 contrib/texinfo/doc/Makefile.am create mode 100644 contrib/texinfo/doc/Makefile.in create mode 100644 contrib/texinfo/doc/README create mode 100644 contrib/texinfo/doc/epsf.tex create mode 100644 contrib/texinfo/doc/info-stnd.texi create mode 100644 contrib/texinfo/doc/info.texi create mode 100644 contrib/texinfo/doc/macro.texi create mode 100644 contrib/texinfo/doc/texinfo.tex create mode 100644 contrib/texinfo/doc/texinfo.txi create mode 100644 contrib/texinfo/doc/userdoc.texi (limited to 'contrib/texinfo/doc') diff --git a/contrib/texinfo/doc/Makefile.am b/contrib/texinfo/doc/Makefile.am new file mode 100644 index 0000000..8d53acd --- /dev/null +++ b/contrib/texinfo/doc/Makefile.am @@ -0,0 +1,57 @@ +## Makefile.am for texinfo/emacs. +## $Id: Makefile.am,v 1.12 1998/02/27 21:46:23 karl Exp $ +## Run automake in .. to produce Makefile.in from this. + +info_TEXINFOS = info-stnd.texi info.texi texinfo.txi + +# Use the programs built in our distribution. +MAKEINFO = ../makeinfo/makeinfo +INSTALL_INFO = ../util/install-info + +# Include our texinfo.tex, not Automake's. +EXTRA_DIST = macro.texi userdoc.texi epsf.tex texinfo.tex + +# We try to discover this via configure just to give a better help message. +TEXMF = @TEXMF@ + +install-data-local: + @echo "WARNING: You must install texinfo.tex and epsf.tex manually," + @echo "WARNING: perhaps in $(TEXMF)/tex/texinfo/" + @echo "WARNING: and $(TEXMF)/tex/generic/dvips/ respectively." + @echo "WARNING: See doc/README for some considerations." + +# Do not create info files for distribution. +dist-info: + +# Do not try to build the info files in $(srcdir), +# since we don't distribute them. +.texi.info: + $(MAKEINFO) -I$(srcdir) `echo $< | sed 's,.*/,,'` +texinfo: $(srcdir)/texinfo.txi + $(MAKEINFO) -I$(srcdir) texinfo.txi + +# Similarly, Do not try to install the info files from $(srcdir). +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + $(mkinstalldirs) $(infodir) + @for file in $(INFO_DEPS); do \ + d=.; \ + for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ + if test -f $$d/$$ifile; then \ + echo " $(INSTALL_DATA) $$d/$$ifile $(infodir)/$$ifile"; \ + $(INSTALL_DATA) $$d/$$ifile $(infodir)/$$ifile; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if $(SHELL) -c '$(INSTALL_INFO) --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + for file in $(INFO_DEPS); do \ + echo " $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/$$file";\ + $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/$$file || :;\ + done; \ + else : ; fi + + +# Remove the info files at make distclean. +distclean-aminfo: + rm -f texinfo texinfo-* info*.info* diff --git a/contrib/texinfo/doc/Makefile.in b/contrib/texinfo/doc/Makefile.in new file mode 100644 index 0000000..c021d3e --- /dev/null +++ b/contrib/texinfo/doc/Makefile.in @@ -0,0 +1,332 @@ +# Makefile.in generated automatically by automake 1.2f from Makefile.am + +# Copyright (C) 1994, 1995, 1996, 1997, 1998 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. + + +SHELL = /bin/sh + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +bindir = @bindir@ +sbindir = @sbindir@ +libexecdir = @libexecdir@ +datadir = @datadir@ +sysconfdir = @sysconfdir@ +sharedstatedir = @sharedstatedir@ +localstatedir = @localstatedir@ +libdir = @libdir@ +infodir = @infodir@ +mandir = @mandir@ +includedir = @includedir@ +oldincludedir = /usr/include + +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ + +top_builddir = .. + +ACLOCAL = @ACLOCAL@ +AUTOCONF = @AUTOCONF@ +AUTOMAKE = @AUTOMAKE@ +AUTOHEADER = @AUTOHEADER@ + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +transform = @program_transform_name@ + +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +CATALOGS = @CATALOGS@ +CATOBJEXT = @CATOBJEXT@ +CC = @CC@ +DATADIRNAME = @DATADIRNAME@ +GENCAT = @GENCAT@ +GMOFILES = @GMOFILES@ +GMSGFMT = @GMSGFMT@ +GT_NO = @GT_NO@ +GT_YES = @GT_YES@ +INCLUDE_LOCALE_H = @INCLUDE_LOCALE_H@ +INSTOBJEXT = @INSTOBJEXT@ +INTLDEPS = @INTLDEPS@ +INTLLIBS = @INTLLIBS@ +INTLOBJS = @INTLOBJS@ +MKINSTALLDIRS = @MKINSTALLDIRS@ +MSGFMT = @MSGFMT@ +PACKAGE = @PACKAGE@ +POFILES = @POFILES@ +POSUB = @POSUB@ +RANLIB = @RANLIB@ +TERMLIBS = @TERMLIBS@ +TEXCONFIG = @TEXCONFIG@ +USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +l = @l@ + +info_TEXINFOS = info-stnd.texi info.texi texinfo.txi + +# Use the programs built in our distribution. +MAKEINFO = ../makeinfo/makeinfo +INSTALL_INFO = ../util/install-info + +# Include our texinfo.tex, not Automake's. +EXTRA_DIST = macro.texi userdoc.texi epsf.tex texinfo.tex + +# We try to discover this via configure just to give a better help message. +TEXMF = @TEXMF@ +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = ../config.h +CONFIG_CLEAN_FILES = +TEXI2DVI = texi2dvi +TEXINFO_TEX = $(srcdir)/texinfo.tex +INFO_DEPS = info-stnd.info info.info texinfo +DVIS = info-stnd.dvi info.dvi texinfo.dvi +TEXINFOS = info-stnd.texi info.texi texinfo.txi +DIST_COMMON = README $(info_TEXINFOS) Makefile.am Makefile.in \ +texinfo.tex + + +DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) + +TAR = tar +GZIP = --best +default: all + +.SUFFIXES: +.SUFFIXES: .dvi .info .ps .texi .texinfo .txi +$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) + cd $(top_srcdir) && $(AUTOMAKE) --gnu --include-deps doc/Makefile + +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + cd $(top_builddir) \ + && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status + + +info-stnd.info: info-stnd.texi +info-stnd.dvi: info-stnd.texi + + +info.info: info.texi $(info_TEXINFOS) +info.dvi: info.texi $(info_TEXINFOS) + + +texinfo: texinfo.txi +texinfo.dvi: texinfo.txi + + +DVIPS = dvips + +.texi.dvi: + TEXINPUTS=$(srcdir):$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.texi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo.dvi: + TEXINPUTS=$(srcdir):$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.txi.dvi: + TEXINPUTS=$(srcdir):$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` +.dvi.ps: + $(DVIPS) $< -o $@ + +uninstall-info: + $(PRE_UNINSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + ii=yes; \ + else ii=; fi; \ + for file in $(INFO_DEPS); do \ + test -z "$ii" \ + || install-info --info-dir=$(infodir) --remove $$file; \ + done + @$(NORMAL_UNINSTALL) + for file in $(INFO_DEPS); do \ + (cd $(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \ + done + +mostlyclean-aminfo: + -rm -f info-stnd.aux info-stnd.cp info-stnd.cps info-stnd.dvi \ + info-stnd.fn info-stnd.fns info-stnd.ky info-stnd.kys \ + info-stnd.ps info-stnd.log info-stnd.pg info-stnd.toc \ + info-stnd.tp info-stnd.tps info-stnd.vr info-stnd.vrs \ + info-stnd.op info-stnd.tr info-stnd.cv info-stnd.cn info.aux \ + info.cp info.cps info.dvi info.fn info.fns info.ky info.kys \ + info.ps info.log info.pg info.toc info.tp info.tps info.vr \ + info.vrs info.op info.tr info.cv info.cn texinfo.aux \ + texinfo.cp texinfo.cps texinfo.dvi texinfo.fn texinfo.fns \ + texinfo.ky texinfo.kys texinfo.ps texinfo.log texinfo.pg \ + texinfo.toc texinfo.tp texinfo.tps texinfo.vr texinfo.vrs \ + texinfo.op texinfo.tr texinfo.cv texinfo.cn + +clean-aminfo: + +distclean-aminfo: + +maintainer-clean-aminfo: + for i in $(INFO_DEPS); do \ + rm -f $$i; \ + if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ + rm -f $$i-[0-9]*; \ + fi; \ + done +tags: TAGS +TAGS: + + +distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir) + +subdir = doc + +distdir: $(DISTFILES) + @for file in $(DISTFILES); do \ + d=$(srcdir); \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file; \ + done + $(MAKE) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info +info: $(INFO_DEPS) +dvi: $(DVIS) +check: all + $(MAKE) +installcheck: +install-exec: + @$(NORMAL_INSTALL) + +install-data: install-info-am install-data-local + @$(NORMAL_INSTALL) + +install: install-exec install-data all + @: + +uninstall: uninstall-info + +all: Makefile $(INFO_DEPS) + +install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' INSTALL_SCRIPT='$(INSTALL_PROGRAM)' install +installdirs: + $(mkinstalldirs) $(infodir) + + +mostlyclean-generic: + -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES) + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -rm -f Makefile $(DISTCLEANFILES) + -rm -f config.cache config.log stamp-h stamp-h[0-9]* + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) + -test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES) +mostlyclean: mostlyclean-aminfo mostlyclean-generic + +clean: clean-aminfo clean-generic mostlyclean + +distclean: distclean-aminfo distclean-generic clean + -rm -f config.status + +maintainer-clean: maintainer-clean-aminfo maintainer-clean-generic \ + distclean + @echo "This command is intended for maintainers to use;" + @echo "it deletes files that may require special tools to rebuild." + +.PHONY: default install-info-am uninstall-info mostlyclean-aminfo \ +distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir info \ +dvi installcheck install-exec install-data install uninstall all \ +installdirs mostlyclean-generic distclean-generic clean-generic \ +maintainer-clean-generic clean mostlyclean distclean maintainer-clean + + +install-data-local: + @echo "WARNING: You must install texinfo.tex and epsf.tex manually," + @echo "WARNING: perhaps in $(TEXMF)/tex/texinfo/" + @echo "WARNING: and $(TEXMF)/tex/generic/dvips/ respectively." + @echo "WARNING: See doc/README for some considerations." + +# Do not create info files for distribution. +dist-info: + +# Do not try to build the info files in $(srcdir), +# since we don't distribute them. +.texi.info: + $(MAKEINFO) -I$(srcdir) `echo $< | sed 's,.*/,,'` +texinfo: $(srcdir)/texinfo.txi + $(MAKEINFO) -I$(srcdir) texinfo.txi + +# Similarly, Do not try to install the info files from $(srcdir). +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + $(mkinstalldirs) $(infodir) + @for file in $(INFO_DEPS); do \ + d=.; \ + for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ + if test -f $$d/$$ifile; then \ + echo " $(INSTALL_DATA) $$d/$$ifile $(infodir)/$$ifile"; \ + $(INSTALL_DATA) $$d/$$ifile $(infodir)/$$ifile; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if $(SHELL) -c '$(INSTALL_INFO) --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + for file in $(INFO_DEPS); do \ + echo " $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/$$file";\ + $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/$$file || :;\ + done; \ + else : ; fi + +# Remove the info files at make distclean. +distclean-aminfo: + rm -f texinfo texinfo-* info*.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/contrib/texinfo/doc/README b/contrib/texinfo/doc/README new file mode 100644 index 0000000..fe8e654 --- /dev/null +++ b/contrib/texinfo/doc/README @@ -0,0 +1,27 @@ +This directory contains documentation on the Texinfo system and the TeX +sources needed to process Texinfo sources. (Use texi2dvi 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://www.tug.org/tds/), this will be the directory +/tex/texinfo/ for texinfo.tex and /tex/plain/dvips/ for +epsf.tex. If you use the default installation paths, will be +/usr/local/share/texmf. If you have teTeX, you can find by +running: + texconfig confall | grep \^TEXMF= +(The configure script tries to do this for you.) + +You can get the latest texinfo.tex from +ftp://ftp.tug.org/tex/texinfo.tex +ftp://ftp.cs.umb.edu/pub/tex/texinfo.tex +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/contrib/texinfo/doc/epsf.tex b/contrib/texinfo/doc/epsf.tex new file mode 100644 index 0000000..4f9dded --- /dev/null +++ b/contrib/texinfo/doc/epsf.tex @@ -0,0 +1,546 @@ +%%% ==================================================================== +%%% 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= \epsfbox{filename.ps} +%%% or +%%% \epsfysize= \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 +%%% , 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 +%%% , 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 +%%% , 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 +%%% , 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 +%%% , 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 +%%% , 13 July 1993 [2.5]. +%%% Add \epsfframethickness for control of +%%% \epsfframe frame lines. +%%% +%%% --------------------------------------------- +%%% Revised by Nelson H. F. Beebe +%%% , 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 +%%% , 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 + 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/contrib/texinfo/doc/info-stnd.texi b/contrib/texinfo/doc/info-stnd.texi new file mode 100644 index 0000000..9eb6836d --- /dev/null +++ b/contrib/texinfo/doc/info-stnd.texi @@ -0,0 +1,1373 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename info-stnd.info +@settitle GNU Info +@set InfoProgVer 2.11 +@paragraphindent none +@footnotestyle end +@synindex vr cp +@synindex fn cp +@synindex ky cp +@comment %**end of header +@comment $Id: info-stnd.texi,v 1.3 1997/07/06 21:49:30 karl Exp $ + +@dircategory Texinfo documentation system +@direntry +* info program: (info-stnd). Standalone Info-reading program. +@end direntry + +@ifinfo +This file documents GNU Info, a program for viewing the on-line formatted +versions of Texinfo files. 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 that documentation first. + +Copyright @copyright{} 1992, 93, 96, 97 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``Copying'' and ``GNU General Public License'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Free Software Foundation. +@end ifinfo + +@titlepage +@title GNU Info User's Guide +@subtitle For GNU Info version @value{InfoProgVer} +@author Brian J. Fox (bfox@@ai.mit.edu) +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1997 Free Software Foundation + +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 also that the +sections entitled ``Copying'' and ``GNU General Public License'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, What is Info, , (dir) +@top The GNU Info Program + +This file documents GNU Info, a program for viewing the on-line +formatted versions of Texinfo files, version @value{InfoProgVer}. This +documentation is different from the documentation for the Info reader +that is part of GNU Emacs. +@end ifinfo + +@menu +* What is Info:: +* Options:: Options you can pass on the command line. +* Cursor Commands:: Commands which move the cursor within a node. +* Scrolling Commands:: Commands for moving the node around + in a window. +* 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. +* GNU Info Global Index:: Global index containing keystrokes, + command names, variable names, + and general concepts. +@end menu + +@node What is Info, Options, Top, Top +@chapter What is Info? + +@iftex +This file documents GNU Info, a program for viewing the on-line formatted +versions of Texinfo files, version @value{InfoProgVer}. +@end iftex + +@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.@refill + +@node Options, Cursor Commands, What is Info, Top +@chapter Command Line Options +@cindex command line options +@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-name} @var{option-value}] @var{menu-item}@dots{} +@end example + +The following @var{option-names} are available when invoking Info from +the shell: + +@table @code +@cindex directory path +@item --directory @var{directory-path} +@itemx -d @var{directory-path} +Add @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. +Alternatively, you may specify a value for the environment variable +@code{INFOPATH}; if @code{--directory} is not given, the value of +@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon +separated list of directory names. If you do not supply @code{INFOPATH} +or @code{--directory-path}, Info uses a default path. + +@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. + +@item --index-search @var{string} +@cindex index search, selecting +@cindex online help, using Info as +Go to the index entry @var{string} in the Info file specified with +@samp{--file}. If no such entry, print @samp{no entries found} and exit +with nonzero status. This can used from another program as a way to +provide online help. + +@item --node @var{nodename} +@itemx -n @var{nodename} +@cindex node, selecting +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 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. + +@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 --help +@itemx -h +Produces a relatively brief description of the available Info options. + +@item --version +@cindex version information +Prints the version information of Info and exits. + +@item @var{menu-item} +@cindex menu, following +Info treats its remaining arguments as the names of menu items. The +first argument is a menu item in the initial node visited, while +the second argument is a menu item in the first argument's node. +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 + +@node Cursor Commands, Scrolling Commands, Options, Top +@chapter Moving the Cursor +@cindex cursor, moving + +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{Characters, , Character +Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the +notation. + +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 an @dfn{numeric} argument (@pxref{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 @code{C-n} (@code{next-line}) +@kindex C-n +@findex next-line +Move the cursor down to the next line. + +@item @code{C-p} (@code{prev-line}) +@kindex C-p +@findex prev-line +Move the cursor up to the previous line. + +@item @code{C-a} (@code{beginning-of-line}) +@kindex C-a, in Info windows +@findex beginning-of-line +Move the cursor to the start of the current line. + +@item @code{C-e} (@code{end-of-line}) +@kindex C-e, in Info windows +@findex end-of-line +Move the cursor to the end of the current line. + +@item @code{C-f} (@code{forward-char}) +@kindex C-f, in Info windows +@findex forward-char +Move the cursor forward a character. + +@item @code{C-b} (@code{backward-char}) +@kindex C-b, in Info windows +@findex backward-char +Move the cursor backward a character. + +@item @code{M-f} (@code{forward-word}) +@kindex M-f, in Info windows +@findex forward-word +Move the cursor forward a word. + +@item @code{M-b} (@code{backward-word}) +@kindex M-b, in Info windows +@findex backward-word +Move the cursor backward a word. + +@item @code{M-<} (@code{beginning-of-node}) +@itemx @code{b} +@kindex b, in Info windows +@kindex M-< +@findex beginning-of-node +Move the cursor to the start of the current node. + +@item @code{M->} (@code{end-of-node}) +@kindex M-> +@findex end-of-node +Move the cursor to the end of the current node. + +@item @code{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, Node Commands, Cursor Commands, Top +@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. + +@table @asis +@item @code{SPC} (@code{scroll-forward}) +@itemx @code{C-v} +@kindex SPC, in Info windows +@kindex C-v +@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. + +@item @code{DEL} (@code{scroll-backward}) +@itemx @code{M-v} +@kindex DEL, in Info windows +@kindex M-v +@findex scroll-backward +Shift the text in this window down. The inverse of +@code{scroll-forward}. +@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. + +@table @asis +@item @code{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 @code{C-x 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. +@end table + +@node Node Commands, Searching Commands, Scrolling Commands, Top +@chapter Selecting a New 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}. + +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 @code{n} (@code{next-node}) +@kindex n +@findex next-node +Select the `Next' node. + +@item @code{p} (@code{prev-node}) +@kindex p +@findex prev-node +Select the `Prev' node. + +@item @code{u} (@code{up-node}) +@kindex u +@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 through the list of already visited nodes for this +window. @samp{l} with a negative numeric argument moves forward through +the history of nodes for this window, so you can quickly step between +two adjacent (in viewing history) nodes. + +@table @asis +@item @code{l} (@code{history-node}) +@kindex l +@findex history-node +Select the most recently selected node in this window. +@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 @code{t} (@code{top-node}) +@kindex t +@findex top-node +Select the node @samp{Top} in the current Info file. + +@item @code{d} (@code{dir-node}) +@kindex d +@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 @code{<} (@code{first-node}) +@kindex < +@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. + +@item @code{>} (@code{last-node}) +@kindex > +@findex last-node +Select the last node which appears in this file. + +@item @code{]} (@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 @code{[} (@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 +@item @code{g} (@code{goto-node}) +@kindex g +@findex goto-node +Read the name of a node and select it. No completion is done while +reading the node name, since the desired node may reside in a separate +file. The node must be typed exactly as it appears in the Info file. A +file name may be included as with any node specification, for example + +@example +@code{g(emacs)Buffers} +@end example + +finds the node @samp{Buffers} in the Info file @file{emacs}. + +@item @code{C-x 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 @code{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 @code{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 @code{C-x 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, Xref Commands, Node Commands, Top +@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 @code{s} (@code{search}) +@kindex s +@findex search +Read a string in the echo area and search for it. + +@item @code{C-s} (@code{isearch-forward}) +@kindex C-s +@findex isearch-forward +Interactively search forward through the Info file for a string as you +type it. + +@item @code{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. + +@item @code{i} (@code{index-search}) +@kindex i +@findex index-search +Look up a string in the indices for this Info file, and select a node +where the found index entry points to. + +@item @code{,} (@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. +@end table + +The most basic searching command is @samp{s} (@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. + +@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. + +@node Xref Commands, Window Commands, Searching Commands, Top +@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, Selecting Xrefs, , Xref Commands +@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, , Parts of an Xref, Xref Commands +@section Selecting Xrefs + +The following table lists the Info commands which operate on menu items. + +@table @asis +@item @code{1} (@code{menu-digit}) +@itemx @code{2} @dots{} @code{9} +@cindex 1 @dots{} 9, in Info windows +@kindex 1 @dots{} 9, in Info windows +@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. + +@item @code{0} (@code{last-menu-item}) +@kindex 0, in Info windows +@findex last-menu-item +Select the last item in the current node's menu. + +@item @code{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. + +@item @code{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 note cross references. + +@table @asis +@item @code{f} (@code{xref-item}) +@itemx @code{r} +@kindex f +@kindex r +@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. +@end table + +Finally, the next few commands operate on menu or note references alike: + +@table @asis +@item @code{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 @code{M-TAB} (@code{move-to-prev-xref}) +@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. + +@item @code{RET} (@code{select-reference-this-line}) +@kindex RET, in Info windows +@findex select-reference-this-line +Select the menu item or note reference appearing on this line. +@end table + +@node Window Commands, Printing Nodes, Xref Commands, Top +@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, Basic Windows, , Window Commands +@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 + +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, The Echo Area, The Mode Line, Window Commands +@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 @code{C-x 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 @code{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 @code{C-x 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, please @pxref{Variables, , automatic-tiling} for more +information. + +@item @code{C-x 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 @code{C-x 1} (@code{keep-one-window}) +@kindex C-x 1 +@findex keep-one-window +Delete all of the windows excepting the current one. + +@item @code{ESC 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 @code{C-x ^} (@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 @code{C-x 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, , Basic Windows, Window Commands +@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 @code{C-f} (@code{echo-area-forward}) +@kindex C-f, in the echo area +@findex echo-area-forward +Move forward a character. + +@item @code{C-b} (@code{echo-area-backward}) +@kindex C-b, in the echo area +@findex echo-area-backward +Move backward a character. + +@item @code{C-a} (@code{echo-area-beg-of-line}) +@kindex C-a, in the echo area +@findex echo-area-beg-of-line +Move to the start of the input line. + +@item @code{C-e} (@code{echo-area-end-of-line}) +@kindex C-e, in the echo area +@findex echo-area-end-of-line +Move to the end of the input line. + +@item @code{M-f} (@code{echo-area-forward-word}) +@kindex M-f, in the echo area +@findex echo-area-forward-word +Move forward a word. + +@item @code{M-b} (@code{echo-area-backward-word}) +@kindex M-b, in the echo area +@findex echo-area-backward-word +Move backward a word. + +@item @code{C-d} (@code{echo-area-delete}) +@kindex C-d, in the echo area +@findex echo-area-delete +Delete the character under the cursor. + +@item @code{DEL} (@code{echo-area-rubout}) +@kindex DEL, in the echo area +@findex echo-area-rubout +Delete the character behind the cursor. + +@item @code{C-g} (@code{echo-area-abort}) +@kindex C-g, in the echo area +@findex echo-area-abort +Cancel or quit the current operation. If completion is being read, +@samp{C-g} discards the text of the input line which does not match any +completion. If the input line is empty, @samp{C-g} aborts the calling +function. + +@item @code{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 @code{C-q} (@code{echo-area-quoted-insert}) +@kindex C-q, in the echo area +@findex echo-area-quoted-insert +Insert the next character verbatim. This is how you can insert control +characters into a search string, for example. + +@item @var{printing character} (@code{echo-area-insert}) +@kindex printing characters, in the echo area +@findex echo-area-insert +Insert the character. + +@item @code{M-TAB} (@code{echo-area-tab-insert}) +@kindex M-TAB, in the echo area +@findex echo-area-tab-insert +Insert a TAB character. + +@item @code{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. For an in depth discussion of killing and yanking, +@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} + +@table @asis +@item @code{M-d} (@code{echo-area-kill-word}) +@kindex M-d, in the echo area +@findex echo-area-kill-word +Kill the word following the cursor. + +@item @code{M-DEL} (@code{echo-area-backward-kill-word}) +@kindex M-DEL, in the echo area +@findex echo-area-backward-kill-word +Kill the word preceding the cursor. + +@item @code{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 @code{C-x 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 @code{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 @code{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 + +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 @code{TAB} (@code{echo-area-complete}) +@itemx @code{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 @code{?} (@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{?}, the possible +completions would contain: + +@example +@group +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 @code{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, Miscellaneous Commands, Window Commands, Top +@chapter Printing Out Nodes +@cindex printing + +You may wish to print out the contents of a node as a quick reference +document for later use. Info provides you with a command for doing +this. 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. + +@table @asis +@item @code{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}. +@end table + +@node Miscellaneous Commands, Variables, Printing Nodes, Top +@chapter Miscellaneous Commands + +GNU Info contains several commands which self-document GNU Info: + +@table @asis +@item @code{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 @code{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 @code{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 @code{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 @code{C-h} (@code{get-help-window}) +@itemx @code{?} +@kindex C-h +@kindex ?, in Info windows +@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 @code{h} (@code{get-info-help-node}) +@kindex h +@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 @code{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. + +@item @code{M-1} (@code{add-digit-to-numeric-arg}) +@itemx @code{M-2} @dots{} @code{M-9} +@kindex M-1 @dots{} M-9 +@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 +@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 @code{C-g} (@code{abort-key}) +@cindex cancelling typeahead +@cindex cancelling the current operation +@kindex C-g, in Info windows +@findex abort-key +Cancel current operation. +@end table + +The @samp{q} command of Info simply quits running Info. + +@table @asis +@item @code{q} (@code{quit}) +@cindex quitting +@kindex q +@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 @code{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 + +Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + +@table @asis +@item @code{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, GNU Info Global Index, Miscellaneous Commands, Top +@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. + +@table @asis +@item @code{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; 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 @code{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. +This variable is @code{On} 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 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}. + +@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 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 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 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. +@end table + + + +@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 GNU Info Global Index, , Variables, Top +@appendix Global Index + +@printindex cp + +@contents +@bye diff --git a/contrib/texinfo/doc/info.texi b/contrib/texinfo/doc/info.texi new file mode 100644 index 0000000..f7cb1cd --- /dev/null +++ b/contrib/texinfo/doc/info.texi @@ -0,0 +1,911 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename info.info +@settitle Info 1.0 +@comment %**end of header +@comment $Id: info.texi,v 1.4 1997/07/10 21:58:11 karl Exp $ + +@dircategory Texinfo documentation system +@direntry +* Info: (info). Documentation browsing system. +@end direntry + +@ifinfo +This file describes how to use Info, +the on-line, menu-driven GNU documentation system. + +Copyright (C) 1989, 92, 96, 97 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end ifinfo + +@titlepage +@title Info +@subtitle The online, menu-driven GNU documentation system +@author Brian Fox +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1989, 1992, 1993, 1996, 1997 Free Software +Foundation, Inc. +@sp 2 + +Published by the Free Software Foundation @* +59 Temple Place - Suite 330 @* +Boston, MA 02111-1307, USA. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Getting Started, , (dir) +@top Info: An Introduction + +Info is a program for reading documentation, which you are using now. + +To learn how to use Info, type the command @kbd{h}. It brings you +to a programmed instruction sequence. + +@c Need to make sure that `Info-help' goes to the right node, +@c which is the first node of the first chapter. (It should.) +@c (Info-find-node "info" +@c (if (< (window-height) 23) +@c "Help-Small-Screen" +@c "Help"))) + +To learn advanced Info commands, type @kbd{n} twice. This brings you to +@cite{Info for Experts}, skipping over the `Getting Started' chapter. +@end ifinfo + +@menu +* Getting Started:: Getting started using an Info reader. +* Advanced Info:: Advanced commands within Info. +* Create an Info File:: How to make your own Info file. +* The Standalone Info Program: (info-stnd.info). +@end menu + +@node Getting Started, Advanced Info, Top, Top +@comment node-name, next, previous, up +@chapter Getting Started + +This first part of the 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 is about how to generate Info files from +Texinfo files. + +@iftex +This manual is primarily designed for use on a computer, so that you can +try Info commands while reading about them. Reading it on paper 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. + +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 +small stand-alone program designed just to read Info files. + +@item +Type @code{emacs} at the command line; then type @kbd{C-h i} (Control +@kbd{h}, followed by @kbd{i}). This approach uses the Info mode of the +Emacs program, an editor with many other capabilities. +@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 iftex + +@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, Rubout, B and ^L commands. +* Help-M:: Menus +* Help-Adv:: Some advanced Info commands +* Help-Q:: Quitting Info +@end menu + +@node Help-Small-Screen, Help, , Getting Started +@comment node-name, next, previous, up +@section Starting Info on a Small Screen + +@iftex +(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 iftex + +Since your terminal has an unusually 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----} at 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 the Space bar, @key{SPC}. To move +back up, press the key labeled @samp{Backspace} or @key{Delete}. + +@ifinfo +Here are 40 lines of junk, so you can try Spaces and Deletes and +see what they do. At the end are instructions of what you should do +next. + +This is line 17 @* +This is line 18 @* +This is line 19 @* +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 @* + +If you have managed to get here, go back to the beginning with +Delete, and come back here again, then you understand Space and +Delete. 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. + + 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 top line of a node is its @dfn{header}. This node's header (look at +it now) says that it is the node named @samp{Help} in the file +@file{info}. It 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. + + Besides a @samp{Next}, a node can have a @samp{Previous} or an @samp{Up}. +This node has a @samp{Previous} but no @samp{Up}, as you can see. + + Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. + +>> Type @samp{n} to move there. Type just one character; + do not type the quotes and do not type a @key{RET} afterward. + +@samp{>>} in the margin means it is really time to try a command. + +@node Help-P, Help-^L, Help, Getting Started +@comment node-name, next, previous, up +@section Returning to the Previous node + +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}. + +>> But do not do that yet. First, try the @kbd{p} command, which takes + you to the @samp{Previous} node. When you get there, you can do an + @kbd{n} again to return here. + + This all probably seems insultingly simple so far, but @emph{do not} be +led into skimming. Things will get more complicated soon. Also, +do not try a new command until you are told it is time to. Otherwise, +you may make Info skip past an important warning that was coming up. + +>> Now do an @kbd{n} to get to the node @samp{Help-^L} and learn more. + +@node Help-^L, Help-M, Help-P, Getting Started +@comment node-name, next, previous, up +@section The Space, Delete, B and ^L commands. + + This node's header tells you that you are now at node @samp{Help-^L}, and +that @kbd{p} would get you back to @samp{Help-P}. The node's title is +underlined; it says what the node is about (most nodes have titles). + + 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. + + The Space, 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. +Space moves forward, to show what was below the bottom of the screen. +Delete 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). + +>> Now try typing a Space (afterward, type a Delete to return here). + + When you type the space, the two lines that were at the bottom of +the screen appear at the top, followed by more lines. Delete 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 type Space when there is no more to see, it rings the +bell and otherwise does nothing. The same goes for Delete when +the header of the node is visible. + + If your screen is ever garbaged, you can tell Info to print it out +again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down ``Control'' and +type an @key{L} or @kbd{l}). + +>> Type @kbd{C-l} now. + + To move back to the beginning of the node you are on, you can type +a lot of Deletes. You can also type simply @kbd{b} for beginning. +>> 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, with Spaces. + + If your screen is very tall, all of this node might fit at once. +In that case, "b" won't do anything. Sorry; what can we do? + + You have just learned a considerable number of commands. If you +want to use one but have trouble remembering which, you should type +a @key{?} which prints out a brief list of commands. When you are +finished looking at the list, make it go away by pressing @key{SPC} +repeatedly. + +>> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of +>> the list until finished. + + From now on, you will encounter large nodes without warning, and +will be expected to know how to use Space and Delete 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. + +>> Now type @kbd{n} to see the description of the @kbd{m} command. + +@node Help-M, Help-Adv, Help-^L, Getting Started +@comment node-name, next, previous, up +@section Menus + +Menus and the @kbd{m} command + + With only the @kbd{n} and @kbd{p} 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 @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{:}), the name of the node that talks +about that subtopic, 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: FOO's Node This tells about FOO +@end example + +The subtopic name is Foo, and the node describing it is @samp{FOO's Node}. +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 @samp{* Menu:}.]] + + 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}. + +>> Now use Spaces to find the menu in this node, then come back to + the front with a @kbd{b} and some Spaces. 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. + + The command to go to one of the subnodes is @kbd{m}---but @emph{do +not do it yet!} Before you use @kbd{m}, you must understand the +difference between commands and arguments. So far, you have learned +several commands that do not need arguments. When you type one, Info +processes it and is instantly ready for another command. The @kbd{m} +command is different: it is incomplete without the @dfn{name of the +subtopic}. Once you have typed @kbd{m}, Info tries to read the +subtopic name. + + Now look for the line containing many dashes near the bottom of the +screen. There is one more line beneath that one, but usually it is +blank. If it is empty, Info is ready for a command, such as @kbd{n} +or @kbd{b} or Space or @kbd{m}. If that line contains text ending +in a colon, it mean Info is trying to read the @dfn{argument} to a +command. At such times, commands do not work, because Info tries to +use them as the argument. You must either type the argument and +finish the command you started, or type @kbd{Control-g} to cancel the +command. When you have done one of those things, the line becomes +blank again. + + 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}. + + 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. + + You can also use the @dfn{completion} feature to help enter the subtopic +name. If you type the Tab key after entering part of a name, it will +magically fill in more of the name---as much as follows uniquely from +what 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 Return, and it stands for +the subtopic of the line you are on. + +Here is a menu to give you a chance to practice. + +* Menu: The menu starts here. + +This menu gives you three ways of going to one place, Help-FOO. + +* Foo: Help-FOO. A node you can visit for fun.@* +* Bar: Help-FOO. Strange! two ways to get to the same place.@* +* Help-FOO:: And yet another!@* + + +>> Now type just an @kbd{m} and see what happens: + + 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 Control-g. + +>> Try that now; notice the bottom line clear. + +>> Then type another @kbd{m}. + +>> Now type @samp{BAR} item name. Do not type Return yet. + + While you are typing the item name, you can use the Delete key to +cancel one character at a time if you make a mistake. + +>> Type one to cancel the @samp{R}. You could type another @samp{R} to + replace it. You do not have to, since @samp{BA} is a valid abbreviation. + +>> Now you are ready to go. Type a @key{RET}. + + After visiting Help-FOO, you should return here. + +>> Type @kbd{n} to see more commands. + +@c If a menu appears at the end of this node, remove it. +@c It is an accident of the menu updating command. + +Here is another way to get to Help-FOO, a menu. You can ignore this +if you want, or else try it (but then please come back to here). + +@menu +* Help-FOO:: +@end menu + +@node Help-FOO, , , Help-M +@comment node-name, next, previous, up +@subsection The @kbd{u} command + + Congratulations! This is the node @samp{Help-FOO}. Unlike the other +nodes you have seen, this one has an @samp{Up}: @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'' + + You can go back to the node @samp{Help-M} by typing the command +@kbd{u} for ``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. + +>> Now type @kbd{u} to move back up to @samp{Help-M}. + +@node Help-Adv, Help-Q, Help-M, Getting Started +@comment node-name, next, previous, up +@section Some advanced Info commands + + The course is almost over, so please stick with it to the end. + + 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. + + If you have been following directions, ad @kbd{l} command now will get +you back to @samp{Help-M}. Another @kbd{l} command would undo the +@kbd{u} and get you back to @samp{Help-FOO}. Another @kbd{l} would undo +the @kbd{m} and get you back to @samp{Help-M}. + +>> Try typing three @kbd{l}'s, pausing in between to see what each + @kbd{l} does. + +Then follow directions again and you will end up back here. + + 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, to +@samp{Help-M}). + + The @samp{d} command 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. + +>> Try doing a @samp{d}, then do an @kbd{l} to return here (yes, + @emph{do} return). + + Sometimes, in Info documentation, you will see a cross reference. +Cross references look like this: @xref{Help-Cross, Cross}. That is a +real, live cross reference which is named @samp{Cross} and points at +the node named @samp{Help-Cross}. + + If you wish to follow a cross reference, you must use the @samp{f} +command. The @samp{f} must be followed by the cross reference name +(in this case, @samp{Cross}). While you enter the name, you can use the +Delete 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 @samp{f} command; you can complete among +all the cross reference names in the current node by typing a Tab. + +>> Type @samp{f}, followed by @samp{Cross}, and a @key{RET}. + + To get a list of all the cross references in the current node, you can +type @kbd{?} after an @samp{f}. The @samp{f} continues to await a +cross reference name even after printing the list, so if you don't +actually want to follow a reference, you should type a @kbd{Control-g} +to cancel the @samp{f}. + +>> Type "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. + +>> Now type @kbd{n} to see the last node of the course. + +@c If a menu appears at the end of this node, remove it. +@c It is an accident of the menu updating command. + +@node Help-Cross, , , Help-Adv +@comment node-name, next, previous, up +@unnumberedsubsec 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 Info. So you cannot expect +the footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing back to +where you came from. In general, the @kbd{l} (el) command is the only +way to get back there. + +>> Type @kbd{l} to return to the node where the cross reference was. + +@node Help-Q, , Help-Adv, Getting Started +@comment node-name, next, previous, up +@section Quitting Info + + To get out of Info, back to what you were doing before, type @kbd{q} +for @dfn{Quit}. + + This is the end of the course on using Info. There are some other +commands that are meant for experienced users; they are useful, and 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. + +>> Type @samp{d} to go to the Info directory node; then type + @samp{mInfo} and Return, to get to the node about Info and + see what other help is available. + +@node Advanced Info, Create an Info File, Getting Started, Top +@comment node-name, next, previous, up +@chapter Info for Experts + +This chapter describes various advanced Info commands, and 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 @emph{both} to generate an +Info file and to make a printed manual. @xref{Top,, Overview of +Texinfo, texinfo, Texinfo: The GNU Documentation Format}.) + +@menu +* Expert:: Advanced Info commands: g, s, e, and 1 - 5. +* 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 tag tables for Info files. +* Checking:: Checking an Info File +* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. +@end menu + +@node Expert, Add, , Advanced Info +@comment node-name, next, previous, up +@section Advanced Info Commands + +@kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{9}, and @kbd{e} + +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 (its directory node). +@kbd{gExpert@key{RET}} would come back here. + +Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. + +To go to a node in another file, you can include the filename 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 +node @samp{Top} in the file @file{dir}. + +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(FILENAME)@key{RET}}. + +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 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). + +If you grudge the system each character of type-in it requires, you +might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ... +@kbd{9}. They are short for the @kbd{m} command together with an +argument. @kbd{1} goes through the first item in the current node's +menu; @kbd{2} goes through the second item, etc. + +If you display supports multiple fonts, and you are using Emacs' Info +mode to read Info files, the @samp{*} for the fifth menu item is +underlines, and so is the @samp{*} for the ninth item; these underlines +make it easy to see at a glance which number to use for an item. + +On ordinary terminals, you won't have underlining. If you need to +actually count items, it is better to use @kbd{m} instead, and specify +the name. + +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}. + +@node Add, Menus, Expert, Advanced 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 from them. However, +if hyou want to edit an Info file, here is how. + + The new node can live in an existing documentation file, or in a new +one. It must have a @key{^_} character before it (invisible to the +user; this node has one but you cannot see it), and it ends with either +a @key{^_}, a @key{^L}, or the end of file. Note: If you put in a +@key{^L} to end a new node, be sure that there is a @key{^_} after it +to start the next one, since @key{^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 @key{^L} @emph{right after} the @key{^_}. + + The @key{^_} starting a node must be followed by a newline or a +@key{^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{Top}, which points at all the documentation for Info. The @samp{Next} +node is @samp{Menus}. + + The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up}, and @dfn{Next}, +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. + + 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 Info file directory 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 Directory node is @file{(dir)}. The @samp{Top} node +of a document file listed in the Directory should have an @samp{Up: +(dir)} in it. + + 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 filename, since Info when searching for a node does not +expect one 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, Advanced 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. + + A menu begins with a line starting with @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--the +argument that the user must give to the @kbd{m} command 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{* 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 on that file directory, but they do not have to; and +files on 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, Advanced Info +@comment node-name, next, previous, up +@section Creating Cross References + + 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 @kbd{*}. +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 + +They are just examples. The places they ``lead to'' do not really exist! + +@node Tags, Checking, Cross-refs, Advanced Info +@comment node-name, next, previous, up +@section Tag Tables for Info Files + + You can speed up the access to nodes of a large Info file by giving +it a tag table. Unlike the tag table for a program, the tag table for +an Info file lives inside the file itself and is used +automatically whenever Info reads in the file. + + To make a tag 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. + + Once the Info file has a tag table, you must make certain it is up +to date. If, 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 tag table, Info will no longer be able to find that +node. To update the tag table, use the @code{Info-tagify} command again. + + An Info file tag table appears at the end of the file and looks like +this: + +@example +^_ +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 Delete character, and the character position in the file of the +beginning of the node. + +@node Checking, Emacs Info Variables, Tags, Advanced Info +@comment node-name, next, previous, up +@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. + + 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, Advanced Info +@section Emacs Info-mode Variables + +The following variables may modify the behaviour 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}. + +@vtable @code +@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}. + +@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. + +@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). + +@item Info-directory +The standard directory for Info documentation files. Only used when the +function @code{Info-directory} is called. +@end vtable + +@node Create an Info File, , Advanced Info, Top +@comment node-name, next, previous, up +@chapter Creating an Info File from a Makeinfo 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{Create an Info File, , Creating an Info File, texinfo, the Texinfo +Manual}, to learn how to create an Info file from a Texinfo file. + +@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU Documentation +Format}, to learn how to write a Texinfo file. + +@bye diff --git a/contrib/texinfo/doc/macro.texi b/contrib/texinfo/doc/macro.texi new file mode 100644 index 0000000..8a3fe80 --- /dev/null +++ b/contrib/texinfo/doc/macro.texi @@ -0,0 +1,177 @@ +@c This file is included in makeinfo.texi. +@c +@ifinfo +@comment Here are some useful examples of the macro facility. + +@c Simply insert the right version of the texinfo name. +@macro texinfo{} +TeXinfo +@end macro + +@macro dfn{text} +@dfn{\text\} +@cpindex \text\ +@end macro + +@c Define a macro which expands to a pretty version of the name of the +@c Makeinfo program. +@macro makeinfo{} +@code{Makeinfo} +@end macro + +@c Define a macro which is used to define other macros. This one makes +@c a macro which creates a node and gives it a sectioning command. Note +@c that the created macro uses the original definition within the +@c expansion text. This takes advantage of the non-recursion feature of +@c macro execution. +@macro node_define{orig-name} +@macro \orig-name\{title} +@node \title\ +@\orig-name\ \title\ +@end macro +@end macro + +@c Now actually define a new set of sectioning commands. +@node_define {chapter} +@node_define {section} +@node_define {subsection} +@end ifinfo + +@chapter The Macro Facility + +This chapter describes the new macro facility. + +A @dfn{macro} is a command that you define in terms of other commands. +It doesn't exist as a @texinfo{} command until you define it as part of +the input file to @makeinfo{}. Once the command exists, it behaves much +as any other @texinfo{} command. Macros are a useful way to ease the +details and tedium of writing a `correct' info file. The following +sections explain how to write and invoke macros. + +@menu +* How to Use Macros in @texinfo{}:: + How to use the macro facility. + +* Using Macros Recursively:: + How to write a macro which does (or doesn't) recurse. + +* Using @texinfo{} Macros As Arguments:: + Passing a macro as an argument. +@end menu + +@section How to Use Macros in @texinfo{} + +Using macros in @texinfo{} is easy. First you define the macro. After +that, the macro command is available as a normal @texinfo{} command. +Here is what a definition looks like: + +@example +@@macro @var{name}@{@var{arg1}, @var{@dots{}} @var{argn}@} +@var{@texinfo{} commands@dots{}} +@@end macro +@end example + +The arguments that you specify that the macro takes are expanded with +the actual parameters used when calling the macro if they are seen +surrounded by backslashes. For example, here is a definition of +@code{@@codeitem}, a macro which can be used wherever @code{@@item} can +be used, but which surrounds its argument with @code{@@code@{@dots{}@}}. + +@example +@@macro codeitem@{item@} +@@item @@code@{\item\@} +@@end macro +@end example + +When the macro is expanded, all of the text between the @code{@@macro} +and @code{@@end macro} is inserted into the document at the expansion +point, with the actual parameters substituted for the named parameters. +So, a call to the above macro might look like: + +@example +@@codeitem@{Foo@} +@end example + +and @makeinfo{} would execute the following code: + +@example +@@item @@code@{Foo@} +@end example + +A special case is made for macros which only take a single argument, and +which are invoked without any brace characters (i.e., +@samp{@{}@dots{}@samp{@}}) surrounding an argument; the rest of the line +is supplied as is as the sole argument to the macro. This special case +allows one to redefine some standard @texinfo{} commands without +modifying the input file. Along with the non-recursive action of macro +invocation, one can easily redefine the sectioning commands to also +provide index entries: + +@example +@@macro chapter@{name@} +@@chapter \name\ +@@findex \name\ +@@end macro +@end example + +Thus, the text: + +@example +@@chapter strlen +@end example + +will expand to: + +@example +@@chapter strlen +@@findex strlen +@end example + +@section Using Macros Recursively + +Normally, while a particular macro is executing, any call to that macro +will be seen as a call to a builtin @texinfo{} command. This allows one +to redefine a builtin @texinfo{} command as a macro, and then use that +command within the definition of the macro itself. For example, one +might wish to make sure that whereever a term was defined with +@code{@@dfn@{@dots{}@}}, the location of the definition would appear +in the concept index for the manual. Here is a macro which redefines +@code{@@dfn} to do just that: + +@example +@@macro dfn@{text@} +@@dfn@{\text\@} +@@cpindex \text\ +@@end macro +@end example + +Note that we used the builtin @texinfo{} command @code{@@dfn} within our +overriding macro definition. + +This behaviour itself can be overridden for macro execution by writing a +special @dfn{macro control command} in the definition of the macro. The +command is considered special because it doesn't affect the output text +directly, rather, it affects the way in which the macro is defined. One +such special command is @code{@@allow-recursion}. + +@example +@@macro silly@{arg@} +@@allow-recursion +\arg\ +@@end macro +@end example + +Now @code{@@silly} is a macro that can be used within a call to itself: + +@example +This text @@silly@{@@silly@{some text@}@} is ``some text''. +@end example + +@section Using @texinfo{} Macros As Arguments + +@printindex cp +How to use @texinfo{} macros as arguments to other @texinfo{} macros. + +@bye + + diff --git a/contrib/texinfo/doc/texinfo.tex b/contrib/texinfo/doc/texinfo.tex new file mode 100644 index 0000000..3ce4715 --- /dev/null +++ b/contrib/texinfo/doc/texinfo.tex @@ -0,0 +1,4977 @@ +% texinfo.tex -- TeX macros to handle Texinfo files. +% $Id: texinfo.tex,v 2.227 1998/02/25 22:54:34 karl Exp $ +% +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98 +% 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. +% +% In other words, you are welcome to use, share and improve this program. +% You are forbidden to forbid anyone else to use, share and improve +% what you give them. Help stamp out software-hoarding! +% +% Please try the latest version of texinfo.tex before submitting bug +% reports; you can get the latest version from: +% ftp://ftp.cs.umb.edu/pub/tex/texinfo.tex +% /home/gd/gnu/doc/texinfo.tex on the GNU machines. +% +% Send bug reports to bug-texinfo@gnu.org. +% Please include a precise test case in each bug report, +% including a complete document with which we can reproduce the problem. +% +% Texinfo macros (with @macro) are *not* supported by texinfo.tex. You +% have to run makeinfo -E to expand macros first; the texi2dvi script +% does this. + + +% Make it possible to create a .fmt file just by loading this file: +% if the underlying format is not loaded, start by loading it now. +% Added by gildea November 1993. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi + +% This automatically updates the version number based on RCS. +\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} +\deftexinfoversion$Revision: 2.227 $ +\message{Loading texinfo package [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]}\message{} + \catcode`+=\active \catcode`\_=\active} + +% Save some parts of plain tex 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\ptexi=\i +\let\ptexlbrace=\{ +\let\ptexrbrace=\} +\let\ptexstar=\* +\let\ptext=\t + +% 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\ } +} + + +\message{Basics,} +\chardef\other=12 + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Set up fixed words for English. +\ifx\putwordChapter\undefined{\gdef\putwordChapter{Chapter}}\fi% +\def\putwordInfo{Info}% +\ifx\putwordSee\undefined{\gdef\putwordSee{See}}\fi% +\ifx\putwordsee\undefined{\gdef\putwordsee{see}}\fi% +\ifx\putwordfile\undefined{\gdef\putwordfile{file}}\fi% +\ifx\putwordpage\undefined{\gdef\putwordpage{page}}\fi% +\ifx\putwordsection\undefined{\gdef\putwordsection{section}}\fi% +\ifx\putwordSection\undefined{\gdef\putwordSection{Section}}\fi% +\ifx\putwordTableofContents\undefined{\gdef\putwordTableofContents{Table of Contents}}\fi% +\ifx\putwordShortContents\undefined{\gdef\putwordShortContents{Short Contents}}\fi% +\ifx\putwordAppendix\undefined{\gdef\putwordAppendix{Appendix}}\fi% + +% Ignore a token. +% +\def\gobble#1{} + +\hyphenation{ap-pen-dix} +\hyphenation{mini-buf-fer mini-buf-fers} +\hyphenation{eshell} +\hyphenation{white-space} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen \bindingoffset +\newdimen \normaloffset +\newdimen\pagewidth \newdimen\pageheight + +% 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. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{\tracingcommands2 \tracingstats2 + \tracingpages1 \tracingoutput1 \tracinglostchars1 + \tracingmacros2 \tracingparagraphs1 \tracingrestores1 + \showboxbreadth\maxdimen\showboxdepth\maxdimen +}% + +% 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\cornerlong \newdimen\cornerthick +\newdimen\topandbottommargin +\newdimen\outerhsize \newdimen\outervsize +\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks +\outerhsize=7in +%\outervsize=9.5in +% Alternative @smallbook page size is 9.25in +\outervsize=9.25in +\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{% + \ifcropmarks \vbox to \outervsize\bgroup + \hsize = \outerhsize + \line{\ewtop\hfil\ewtop}% + \nointerlineskip + \line{% + \vbox{\moveleft\cornerthick\nstop}% + \hfill + \vbox{\moveright\cornerthick\nstop}% + }% + \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 + \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 \turnoffactive + \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#1{% + \let\next = #1% + \begingroup + \obeylines + \futurelet\temp\parseargx +} + +% If the next token is an obeyed space (from an @example environment or +% the like), remove it and recurse. Otherwise, we're done. +\def\parseargx{% + % \obeyedspace is defined far below, after the definition of \sepspaces. + \ifx\obeyedspace\temp + \expandafter\parseargdiscardspace + \else + \expandafter\parseargline + \fi +} + +% Remove a single space (as the delimiter token to the macro call). +{\obeyspaces % + \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + % + % First remove any @c comment, then any @comment. + % Result of each macro is put in \toks0. + \argremovec #1\c\relax % + \expandafter\argremovecomment \the\toks0 \comment\relax % + % + % Call the caller's macro, saved as \next in \parsearg. + \expandafter\next\expandafter{\the\toks0}% + }% +} + +% Since all \c{,omment} does is throw away the argument, we can let TeX +% do that for us. The \relax here is matched by the \relax in the call +% in \parseargline; it could be more or less anything, its purpose is +% just to delimit the argument to the \c. +\def\argremovec#1\c#2\relax{\toks0 = {#1}} +\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} + +% \argremovec{,omment} might leave us with trailing spaces, though; e.g., +% @end itemize @c foo +% will have two active spaces as part of the argument with the +% `itemize'. Here we remove all active spaces from #1, and assign the +% result to \toks0. +% +% This loses if there are any *other* active characters besides spaces +% in the argument -- _ ^ +, for example -- since they get expanded. +% Fortunately, Texinfo does not define any such commands. (If it ever +% does, the catcode of the characters in questionwill have to be changed +% here.) But this means we cannot call \removeactivespaces as part of +% \argremovec{,omment}, since @c uses \parsearg, and thus the argument +% that \parsearg gets might well have any character at all in it. +% +\def\removeactivespaces#1{% + \begingroup + \ignoreactivespaces + \edef\temp{#1}% + \global\toks0 = \expandafter{\temp}% + \endgroup +} + +% Change the active space to expand to nothing. +% +\begingroup + \obeyspaces + \gdef\ignoreactivespaces{\obeyspaces\let =\empty} +\endgroup + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +%% These are used to keep @begin/@end levels from running away +%% Call \inENV within environments (after a \begingroup) +\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} +\def\ENVcheck{% +\ifENV\errmessage{Still within an environment. Type Return to continue.} +\endgroup\fi} % This is not perfect, but it should reduce lossage + +% @begin foo is the same as @foo, for now. +\newhelp\EMsimple{Type to continue.} + +\outer\def\begin{\parsearg\beginxxx} + +\def\beginxxx #1{% +\expandafter\ifx\csname #1\endcsname\relax +{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else +\csname #1\endcsname\fi} + +% @end foo executes the definition of \Efoo. +% +\def\end{\parsearg\endxxx} +\def\endxxx #1{% + \removeactivespaces{#1}% + \edef\endthing{\the\toks0}% + % + \expandafter\ifx\csname E\endthing\endcsname\relax + \expandafter\ifx\csname \endthing\endcsname\relax + % There's no \foo, i.e., no ``environment'' foo. + \errhelp = \EMsimple + \errmessage{Undefined command `@end \endthing'}% + \else + \unmatchedenderror\endthing + \fi + \else + % Everything's ok; the right environment has been started. + \csname E\endthing\endcsname + \fi +} + +% There is an environment #1, but it hasn't been started. Give an error. +% +\def\unmatchedenderror#1{% + \errhelp = \EMsimple + \errmessage{This `@end #1' doesn't have a matching `@#1'}% +} + +% Define the control sequence \E#1 to give an unmatched @end error. +% +\def\defineunmatchedend#1{% + \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% +} + + +% Single-spacing is done by various environments (specifically, in +% \nonfillstart and \quotations). +\newskip\singlespaceskip \singlespaceskip = 12.5pt +\def\singlespace{% + % Why was this kern here? It messes up equalizing space above and below + % environments. --karl, 6may93 + %{\advance \baselineskip by -\singlespaceskip + %\kern \baselineskip}% + \setleading \singlespaceskip +} + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt \char '100}} + +% 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 \char '173}} +\def\myrbrace {{\tt \char '175}} +\let\{=\mylbrace +\let\}=\myrbrace +\begingroup + % Definitions to produce actual \{ & \} command in an index. + \catcode`\{ = 12 \catcode`\} = 12 + \catcode`\[ = 1 \catcode`\] = 2 + \catcode`\@ = 0 \catcode`\\ = 12 + @gdef@lbracecmd[\{]% + @gdef@rbracecmd[\}]% +@endgroup + +% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent +% Others are defined by plain TeX: @` @' @" @^ @~ @= @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 +% Plain TeX defines: @AA @AE @O @OE @L (and lowercase versions) @ss. +\def\questiondown{?`} +\def\exclamdown{!`} + +% 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 +} + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\hfil\break\hbox{}\ignorespaces} + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=3000 } + +% @! is an end-of-sentence bang. +\def\!{!\spacefactor=3000 } + +% @? is an end-of-sentence query. +\def\?{?\spacefactor=3000 } + +% @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. +% +\def\group{\begingroup + \ifnum\catcode13=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + % + % The \vtop we start below 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. (See p.82 of + % the TeXbook.) Thus, space below is not quite equal to space + % above. But it's pretty close. + \def\Egroup{% + \egroup % End the \vtop. + \endgroup % End the \group. + }% + % + \vtop\bgroup + % We have to put a strut on the last line in case the @group is in + % the midst of an example, rather than completely enclosing it. + % Otherwise, the interline space between the last line of the group + % and the first line afterwards is too small. But we can't put the + % strut in \Egroup, since there it would be on a line by itself. + % Hence this just inserts a strut at the beginning of each line. + \everypar = {\strut}% + % + % Since we have a strut on every line, we don't need any of TeX's + % normal interline spacing. + \offinterlineskip + % + % OK, but now we have to do something about blank + % lines in the input in @example-like environments, which normally + % just turn into \lisppar, which will insert no space now that we've + % turned off the interline space. Simplest is to make them be an + % empty paragraph. + \ifx\par\lisppar + \edef\par{\leavevmode \par}% + % + % Reset ^^M's definition to new definition of \par. + \obeylines + \fi + % + % 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 +} +% +% 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 + +\def\need{\parsearg\needx} + +% Old definition--didn't work. +%\def\needx #1{\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\penalty 10000 +%\prevdepth=-1000pt +%}} + +\def\needx#1{% + % Go into vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % Don't add any leading before our big empty box, but allow a page + % break, since the best break might be right here. + \allowbreak + \nointerlineskip + \vtop to #1\mil{\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 +} + +% @br forces paragraph break + +\let\br = \par + +% @dots{} output 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{\hbox to 1.5em{% + \hskip 0pt plus 0.25fil minus 0.25fil + .\hss.\hss.% + \hskip 0pt plus 0.5fil minus 0.5fil +}} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \hbox to 2em{% + \hskip 0pt plus 0.25fil minus 0.25fil + .\hss.\hss.\hss.% + \hskip 0pt plus 0.5fil minus 0.5fil + }% + \spacefactor=3000 +} + + +% @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. +\def\exdent{\parsearg\exdentyyy} +\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} + +% This defn is used inside nofill environments such as @example. +\def\nofillexdent{\parsearg\nofillexdentyyy} +\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount +\leftline{\hskip\leftskip{\rm#1}}}} + +% @inmargin{TEXT} puts TEXT in the margin next to the current paragraph. + +\def\inmargin#1{% +\strut\vadjust{\nobreak\kern-\strutdepth + \vtop to \strutdepth{\baselineskip\strutdepth\vss + \llap{\rightskip=\inmarginspacing \vbox{\noindent #1}}\null}}} +\newskip\inmarginspacing \inmarginspacing=1cm +\def\strutdepth{\dp\strutbox} + +%\hbox{{\rm#1}}\hfil\break}} + +% @include file insert text of that file as input. +% Allow normal characters that we make active in the argument (a file name). +\def\include{\begingroup + \catcode`\\=12 + \catcode`~=12 + \catcode`^=12 + \catcode`_=12 + \catcode`|=12 + \catcode`<=12 + \catcode`>=12 + \catcode`+=12 + \parsearg\includezzz} +% Restore active chars for included file. +\def\includezzz#1{\endgroup\begingroup + % Read the included file in a group so nested @include's work. + \def\thisfile{#1}% + \input\thisfile +\endgroup} + +\def\thisfile{} + +% @center line outputs that line, centered + +\def\center{\parsearg\centerzzz} +\def\centerzzz #1{{\advance\hsize by -\leftskip +\advance\hsize by -\rightskip +\centerline{#1}}} + +% @sp n outputs n lines of vertical space + +\def\sp{\parsearg\spxxx} +\def\spxxx #1{\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{\catcode 64=\other \catcode 123=\other \catcode 125=\other% +\parsearg \commentxxx} + +\def\commentxxx #1{\catcode 64=0 \catcode 123=1 \catcode 125=2 } + +\let\c=\comment + +% @paragraphindent is defined for the Info formatting commands only. +\let\paragraphindent=\comment + +% Prevent errors for section commands. +% Used in @ignore and in failing conditionals. +\def\ignoresections{% +\let\chapter=\relax +\let\unnumbered=\relax +\let\top=\relax +\let\unnumberedsec=\relax +\let\unnumberedsection=\relax +\let\unnumberedsubsec=\relax +\let\unnumberedsubsection=\relax +\let\unnumberedsubsubsec=\relax +\let\unnumberedsubsubsection=\relax +\let\section=\relax +\let\subsec=\relax +\let\subsubsec=\relax +\let\subsection=\relax +\let\subsubsection=\relax +\let\appendix=\relax +\let\appendixsec=\relax +\let\appendixsection=\relax +\let\appendixsubsec=\relax +\let\appendixsubsection=\relax +\let\appendixsubsubsec=\relax +\let\appendixsubsubsection=\relax +\let\contents=\relax +\let\smallbook=\relax +\let\titlepage=\relax +} + +% Used in nested conditionals, where we have to parse the Texinfo source +% and so want to turn off most commands, in case they are used +% incorrectly. +% +\def\ignoremorecommands{% + \let\defcodeindex = \relax + \let\defcv = \relax + \let\deffn = \relax + \let\deffnx = \relax + \let\defindex = \relax + \let\defivar = \relax + \let\defmac = \relax + \let\defmethod = \relax + \let\defop = \relax + \let\defopt = \relax + \let\defspec = \relax + \let\deftp = \relax + \let\deftypefn = \relax + \let\deftypefun = \relax + \let\deftypevar = \relax + \let\deftypevr = \relax + \let\defun = \relax + \let\defvar = \relax + \let\defvr = \relax + \let\ref = \relax + \let\xref = \relax + \let\printindex = \relax + \let\pxref = \relax + \let\settitle = \relax + \let\setchapternewpage = \relax + \let\setchapterstyle = \relax + \let\everyheading = \relax + \let\evenheading = \relax + \let\oddheading = \relax + \let\everyfooting = \relax + \let\evenfooting = \relax + \let\oddfooting = \relax + \let\headings = \relax + \let\include = \relax + \let\lowersections = \relax + \let\down = \relax + \let\raisesections = \relax + \let\up = \relax + \let\set = \relax + \let\clear = \relax + \let\item = \relax +} + +% Ignore @ignore ... @end ignore. +% +\def\ignore{\doignore{ignore}} + +% Ignore @ifinfo, @ifhtml, @ifnottex, @html, @menu, and @direntry text. +% +\def\ifinfo{\doignore{ifinfo}} +\def\ifhtml{\doignore{ifhtml}} +\def\ifnottex{\doignore{ifnottex}} +\def\html{\doignore{html}} +\def\menu{\doignore{menu}} +\def\direntry{\doignore{direntry}} + +% Also ignore @macro ... @end macro. The user must run texi2dvi, +% which runs makeinfo to do macro expansion. Ignore @unmacro, too. +\def\macro{\doignore{macro}} +\let\unmacro = \comment + + +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. +\let\dircategory = \comment + +% Ignore text until a line `@end #1'. +% +\def\doignore#1{\begingroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define a command to swallow text until we reach `@end #1'. + \long\def\doignoretext##1\end #1{\enddoignore}% + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \catcode32 = 10 + % + % Ignore braces, too, so mismatched braces don't cause trouble. + \catcode`\{ = 9 + \catcode`\} = 9 + % + % And now expand that command. + \doignoretext +} + +% What we do to finish off ignored text. +% +\def\enddoignore{\endgroup\ignorespaces}% + +\newif\ifwarnedobs\warnedobsfalse +\def\obstexwarn{% + \ifwarnedobs\relax\else + % We need to warn folks that they may have trouble with TeX 3.0. + % This uses \immediate\write16 rather than \message to get newlines. + \immediate\write16{} + \immediate\write16{***WARNING*** for users of Unix TeX 3.0!} + \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} + \immediate\write16{If you are running another version of TeX, relax.} + \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} + \immediate\write16{ Then upgrade your TeX installation if you can.} + \immediate\write16{ (See ftp://ftp.gnu.ai.mit.edu/pub/gnu/TeX.README.)} + \immediate\write16{If you are stuck with version 3.0, run the} + \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} + \immediate\write16{ to use a workaround.} + \immediate\write16{} + \global\warnedobstrue + \fi +} + +% **In TeX 3.0, setting text in \nullfont hangs tex. For a +% workaround (which requires the file ``dummy.tfm'' to be installed), +% uncomment the following line: +%%%%%\font\nullfont=dummy\let\obstexwarn=\relax + +% Ignore text, except that we keep track of conditional commands for +% purposes of nesting, up to an `@end #1' command. +% +\def\nestedignore#1{% + \obstexwarn + % We must actually expand the ignored text to look for the @end + % command, so that nested ignore constructs work. Thus, we put the + % text into a \vbox and then do nothing with the result. To minimize + % the change of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook: make the current font be a dummy font. + % + \setbox0 = \vbox\bgroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define `@end #1' to end the box, which will in turn undefine the + % @end command again. + \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% + % + % We are going to be parsing Texinfo commands. Most cause no + % trouble when they are used incorrectly, but some commands do + % complicated argument parsing or otherwise get confused, so we + % undefine them. + % + % We can't do anything about stray @-signs, unfortunately; + % they'll produce `undefined control sequence' errors. + \ignoremorecommands + % + % Set the current font to be \nullfont, a TeX primitive, and define + % all the font commands to also use \nullfont. We don't use + % dummy.tfm, as suggested in the TeXbook, because not all sites + % might have that installed. Therefore, math mode will still + % produce output, but that should be an extremely small amount of + % stuff compared to the main input. + % + \nullfont + \let\tenrm = \nullfont \let\tenit = \nullfont \let\tensl = \nullfont + \let\tenbf = \nullfont \let\tentt = \nullfont \let\smallcaps = \nullfont + \let\tensf = \nullfont + % Similarly for index fonts (mostly for their use in + % smallexample) + \let\indrm = \nullfont \let\indit = \nullfont \let\indsl = \nullfont + \let\indbf = \nullfont \let\indtt = \nullfont \let\indsc = \nullfont + \let\indsf = \nullfont + % + % Don't complain when characters are missing from the fonts. + \tracinglostchars = 0 + % + % Don't bother to do space factor calculations. + \frenchspacing + % + % Don't report underfull hboxes. + \hbadness = 10000 + % + % Do minimal line-breaking. + \pretolerance = 10000 + % + % Do not execute instructions in @tex + \def\tex{\doignore{tex}}% +} + +% @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. Make sure the catcode of space is correct to avoid +% losing inside @example, for instance. +% +\def\set{\begingroup\catcode` =10 + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \parsearg\setxxx} +\def\setxxx#1{\setyyy#1 \endsetyyy} +\def\setyyy#1 #2\endsetyyy{% + \def\temp{#2}% + \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty + \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. + \fi + \endgroup +} +% Can't use \xdef to pre-expand #2 and save some time, since \temp or +% \next or other control sequences that we've defined might get us into +% an infinite loop. Consider `@set foo @cite{bar}'. +\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\def\clear{\parsearg\clearxxx} +\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} + +% @value{foo} gets the text saved in variable foo. +% +\def\value{\begingroup + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \valuexxx} +\def\valuexxx#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}}% + \else + \csname SET#1\endcsname + \fi +\endgroup} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +\def\ifset{\parsearg\ifsetxxx} +\def\ifsetxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifsetfail + \else + \expandafter\ifsetsucceed + \fi +} +\def\ifsetsucceed{\conditionalsucceed{ifset}} +\def\ifsetfail{\nestedignore{ifset}} +\defineunmatchedend{ifset} + +% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +\def\ifclear{\parsearg\ifclearxxx} +\def\ifclearxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifclearsucceed + \else + \expandafter\ifclearfail + \fi +} +\def\ifclearsucceed{\conditionalsucceed{ifclear}} +\def\ifclearfail{\nestedignore{ifclear}} +\defineunmatchedend{ifclear} + +% @iftex, @ifnothtml, @ifnotinfo always succeed; we read the text +% following, through the first @end iftex (etc.). Make `@end iftex' +% (etc.) valid only after an @iftex. +% +\def\iftex{\conditionalsucceed{iftex}} +\def\ifnothtml{\conditionalsucceed{ifnothtml}} +\def\ifnotinfo{\conditionalsucceed{ifnotinfo}} +\defineunmatchedend{iftex} +\defineunmatchedend{ifnothtml} +\defineunmatchedend{ifnotinfo} + +% We can't just want to start a group at @iftex (for example) and end it +% at @end iftex, since then @set commands inside the conditional have no +% effect (they'd get reverted at the end of the group). So we must +% define \Eiftex to redefine itself to be its previous value. (We can't +% just define it to fail again with an ``unmatched end'' error, since +% the @ifset might be nested.) +% +\def\conditionalsucceed#1{% + \edef\temp{% + % Remember the current value of \E#1. + \let\nece{prevE#1} = \nece{E#1}% + % + % At the `@end #1', redefine \E#1 to be its previous value. + \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% + }% + \temp +} + +% We need to expand lots of \csname's, but we don't want to expand the +% control sequences after we've constructed them. +% +\def\nece#1{\expandafter\noexpand\csname#1\endcsname} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math means output in math mode. +% We don't use $'s directly in the definition of \math because control +% sequences like \math are expanded when the toc file is written. Then, +% we read the toc file back, the $'s will be normal characters (as they +% should be, according to the definition of Texinfo). So we must use a +% control sequence to switch into and out of math mode. +% +% This isn't quite enough for @math to work properly in indices, but it +% seems unlikely it will ever be needed there. +% +\let\implicitmath = $ +\def\math#1{\implicitmath #1\implicitmath} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{\implicitmath\ptexbullet\implicitmath} +\def\minus{\implicitmath-\implicitmath} + +\def\node{\ENVcheck\parsearg\nodezzz} +\def\nodezzz#1{\nodexxx [#1,]} +\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} +\let\nwnode=\node +\let\lastnode=\relax + +\def\donoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\setref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\unnumbnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\unnumbsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\appendixnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +% @refill is a no-op. +\let\refill=\relax + +% @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{% + \readauxfile + \opencontents + \openindices + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. + % Just to be on the safe side, close the input stream before the \input. + \openin 1 texinfo.cnf + \ifeof1 \let\temp=\relax \else \def\temp{\input texinfo.cnf }\fi + \closein1 + \temp + % + \comment % Ignore the actual filename. +} + +% @bye. +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + +% \def\macro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\macroxxx} +% \def\macroxxx#1#2 \end macro{% +% \expandafter\gdef\macrotemp#1{#2}% +% \endgroup} + +%\def\linemacro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\linemacroxxx} +%\def\linemacroxxx#1#2 \end linemacro{% +%\let\parsearg=\relax +%\edef\macrotempx{\csname M\butfirst\expandafter\string\macrotemp\endcsname}% +%\expandafter\xdef\macrotemp{\parsearg\macrotempx}% +%\expandafter\gdef\macrotempx#1{#2}% +%\endgroup} + +%\def\butfirst#1{} + + +\message{fonts,} + +% Font-change commands. + +% Texinfo supports the sans serif font style, which plain TeX does not. +% So we set up a \sf analogous to plain's \rm, etc. +\newfam\sffam +\def\sf{\fam=\sffam \tensf} +\let\li = \sf % Sometimes we call it \li, not \sf. + +% We don't need math for this one. +\def\ttsl{\tenttsl} + +% Use Computer Modern fonts at \magstephalf (11pt). +\newcount\mainmagstep +\mainmagstep=\magstephalf + +% 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} + +\ifx\bigger\relax +\let\mainmagstep=\magstep1 +\setfont\textrm\rmshape{12}{1000} +\setfont\texttt\ttshape{12}{1000} +\else +\setfont\textrm\rmshape{10}{\mainmagstep} +\setfont\texttt\ttshape{10}{\mainmagstep} +\fi +% Instead of cmb10, you many want to use cmbx10. +% cmbx10 is a prettier font on its own, but cmb10 +% looks better when embedded in a line with cmr10. +\setfont\textbf\bfshape{10}{\mainmagstep} +\setfont\textit\itshape{10}{\mainmagstep} +\setfont\textsl\slshape{10}{\mainmagstep} +\setfont\textsf\sfshape{10}{\mainmagstep} +\setfont\textsc\scshape{10}{\mainmagstep} +\setfont\textttsl\ttslshape{10}{\mainmagstep} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun, etc. +\setfont\defbf\bxshape{10}{\magstep1} %was 1314 +\setfont\deftt\ttshape{10}{\magstep1} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} + +% Fonts for indices and small examples (9pt). +% We actually use the slanted font rather than the italic, +% because texinfo normally uses the slanted fonts for that. +% Do not make many font distinctions in general in the index, since they +% aren't very useful. +\setfont\ninett\ttshape{9}{1000} +\setfont\indrm\rmshape{9}{1000} +\setfont\indit\slshape{9}{1000} +\let\indsl=\indit +\let\indtt=\ninett +\let\indttsl=\ninett +\let\indsf=\indrm +\let\indbf=\indrm +\setfont\indsc\scshape{10}{900} +\font\indi=cmmi9 +\font\indsy=cmsy9 + +% Fonts for title page: +\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} + +% Chapter (and unnumbered) fonts (17.28pt). +\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). +\setfont\secrm\rmbshape{12}{\magstep1} +\setfont\secit\itbshape{10}{\magstep2} +\setfont\secsl\slbshape{10}{\magstep2} +\setfont\sectt\ttbshape{12}{\magstep1} +\setfont\secttsl\ttslshape{10}{\magstep2} +\setfont\secsf\sfbshape{12}{\magstep1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad. +% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded. +% \setfont\ssecsl\slshape{10}{\magstep1} +% \setfont\ssectt\ttshape{10}{\magstep1} +% \setfont\ssecsf\sfshape{10}{\magstep1} + +%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than +%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1. +%\setfont\ssectt\ttshape{10}{1315} +%\setfont\ssecsf\sfshape{10}{1315} + +%\let\ssecbf=\ssecrm + +% Subsection fonts (13.15pt). +\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}{\magstep1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled 1315 +% The smallcaps and symbol fonts should actually be scaled \magstep1.5, +% but that is not a standard magnification. + +% 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, 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 so that font changes will continue to work +% in math mode, where it is the current \fam that is relevant in most +% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam +% \tenbf}, for example. By redefining \tenbf, we obviate the need to +% redefine \bf itself. +\def\textfonts{% + \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl + \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl + \resetmathfonts} +\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 + \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 + \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 + \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 + \resetmathfonts \setleading{15pt}} +\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf? +\def\indexfonts{% + \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl + \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy \let\tenttsl=\indttsl + \resetmathfonts \setleading{12pt}} + +% Set up the default fonts, so we can use them for creating boxes. +% +\textfonts + +% 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\bxshape{12}{1000} +\setfont\shortcontsl\slshape{12}{1000} + +%% Add scribe-like font environments, plus @l for inline lisp (usually sans +%% serif) and @ii for TeX italic + +% \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\/\fi\fi\fi} +\def\smartitalic#1{{\sl #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\var=\smartitalic +\let\dfn=\smartitalic +\let\emph=\smartitalic +\let\cite=\smartitalic + +\def\b#1{{\bf #1}} +\let\strong=\b + +% 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 = `- } + +\def\t#1{% + {\tt \rawbackslash \frenchspacing #1}% + \null +} +\let\ttfont=\t +\def\samp#1{`\tclose{#1}'\null} +\setfont\smallrm\rmshape{8}{1000} +\font\smallsy=cmsy9 +\def\key#1{{\smallrm\textfont2=\smallsy \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} + +\let\file=\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 + \frenchspacing + #1% + }% + \null +} + +% We *must* turn on hyphenation at `-' and `_' in \code. +% Otherwise, it is too hard to avoid overfull hboxes +% in the Emacs manual, the Library manual, etc. + +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate at a dash. +% -- rms. +{ +\catcode`\-=\active +\catcode`\_=\active +\catcode`\|=\active +\global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} +% The following is used by \doprintindex to insure that long function names +% wrap around. It is necessary for - and _ to be active before the index is +% read from the file, as \entry parses the arguments long before \code is +% ever called. -- mycroft +% _ is always active; and it shouldn't be \let = to an _ that is a +% subscript character anyway. Then, @cindex @samp{_} (for example) +% fails. --karl +\global\def\indexbreaks{% + \catcode`\-=\active \let-\realdash +} +} + +\def\realdash{-} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{\ifusingtt{\normalunderscore\discretionary{}{}{}}{\_}} +\def\codex #1{\tclose{#1}\endgroup} + +%\let\exp=\tclose %Was temporary + +% @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). +\def\kbdinputstyle{\parsearg\kbdinputstylexxx} +\def\kbdinputstylexxx#1{% + \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}% + \fi\fi\fi +} +\def\worddistinct{distinct} +\def\wordexample{example} +\def\wordcode{code} + +% Default is kbdinputdistinct. (Too much of a hassle to call the macro, +% the catcodes are wrong for parsearg to work.) +\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl} + +\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} + +% @url. Quotes do not seem necessary, so use \code. +\let\url=\code + +% @uref (abbreviation for `urlref') takes an optional second argument +% specifying the text to display. First (mandatory) arg is the url. +% Perhaps eventually put in a hypertex \special here. +% +\def\uref#1{\urefxxx #1,,\finish} +\def\urefxxx#1,#2,#3\finish{% + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \unhbox0\ (\code{#1})% + \else + \code{#1}% + \fi +} + +% rms does not like the angle brackets --karl, 17may97. +% So now @email is just like @uref. +%\def\email#1{\angleleft{\tt #1}\angleright} +\let\email=\uref + +% 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} + +\def\r#1{{\rm #1}} % roman font +% Use of \lowercase was suggested. +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +% @pounds{} is a sterling sign. +\def\pounds{{\it\$}} + + +\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 + +\def\shorttitlepage{\parsearg\shorttitlepagezzz} +\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\def\titlepage{\begingroup \parindent=0pt \textfonts + \let\subtitlerm=\tenrm +% I deinstalled the following change because \cmr12 is undefined. +% This change was not in the ChangeLog anyway. --rms. +% \let\subtitlerm=\cmr12 + \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% + % + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + % + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % + % Now you can print the title using @title. + \def\title{\parsearg\titlezzz}% + \def\titlezzz##1{\leftline{\titlefonts\rm ##1} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Now you can put text using @subtitle. + \def\subtitle{\parsearg\subtitlezzz}% + \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% + % + % @author should come last, but may come many times. + \def\author{\parsearg\authorzzz}% + \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi + {\authorfont \leftline{##1}}}% + % + % 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 + \oldpage + \let\page = \oldpage + \hbox{}}% +% \def\page{\oldpage \hbox{}} +} + +\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 + \HEADINGSon +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks \evenheadline % Token sequence for heading line of even pages +\newtoks \oddheadline % Token sequence for heading line of odd pages +\newtoks \evenfootline % Token sequence for footing line of even pages +\newtoks \oddfootline % Token sequence for footing line of 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\oddheading{\parsearg\oddheadingxxx} +\def\everyheading{\parsearg\everyheadingxxx} + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\oddfooting{\parsearg\oddfootingxxx} +\def\everyfooting{\parsearg\everyfootingxxx} + +{\catcode`\@=0 % + +\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} +\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} +\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyheadingxxx#1{\oddheadingxxx{#1}\evenheadingxxx{#1}}% + +\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} +\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} +\gdef\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 +} + +\gdef\everyfootingxxx#1{\oddfootingxxx{#1}\evenfootingxxx{#1}} +% +}% unbind the catcode of @. + +% @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 +% Produces Day Month Year style of output. +\def\today{\number\day\space +\ifcase\month\or +January\or February\or March\or April\or May\or June\or +July\or August\or September\or October\or November\or December\fi +\space\number\year} + +% Use this if you want the Month Day, Year style of output. +%\def\today{\ifcase\month\or +%January\or February\or March\or April\or May\or June\or +%July\or August\or September\or October\or November\or December\fi +%\space\number\day, \number\year} + +% @settitle line... specifies the title of the document, for headings +% It generates no output of its own + +\def\thistitle{No Title} +\def\settitle{\parsearg\settitlezzz} +\def\settitlezzz #1{\gdef\thistitle{#1}} + + +\message{tables,} + +% @tabs -- simple alignment + +% These don't work. For one thing, \+ is defined as outer. +% So these macros cannot even be defined. + +%\def\tabs{\parsearg\tabszzz} +%\def\tabszzz #1{\settabs\+#1\cr} +%\def\tabline{\parsearg\tablinezzz} +%\def\tablinezzz #1{\+#1\cr} +%\def\&{&} + +% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(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, @vtable, 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\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} +\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} + +\def\internalBkitem{\smallbreak \parsearg\kitemzzz} +\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} + +\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% + \itemzzz {#1}} + +\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% + \itemzzz {#1}} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemfont{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % Be sure we are not still in the middle of a paragraph. + %{\parskip = 0in + %\par + %}% + % + % 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. Unfortunately + % we can't prevent a possible page break at the following + % \baselineskip glue. + \nobreak + \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. Since that + % text will be indented by \tableindent, we make the item text be in + % a zero-width box. + \noindent + \rlap{\hskip -\tableindent\box0}\ignorespaces% + \endgroup% + \itemxneedsnegativevskiptrue% + \fi +} + +\def\item{\errmessage{@item while not in a table}} +\def\itemx{\errmessage{@itemx while not in a table}} +\def\kitem{\errmessage{@kitem while not in a table}} +\def\kitemx{\errmessage{@kitemx while not in a table}} +\def\xitem{\errmessage{@xitem while not in a table}} +\def\xitemx{\errmessage{@xitemx while not in a table}} + +%% Contains a kludge to get @end[description] to work +\def\description{\tablez{\dontindex}{1}{}{}{}{}} + +\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} +{\obeylines\obeyspaces% +\gdef\tablex #1^^M{% +\tabley\dontindex#1 \endtabley}} + +\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} +{\obeylines\obeyspaces% +\gdef\ftablex #1^^M{% +\tabley\fnitemindex#1 \endtabley +\def\Eftable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} +{\obeylines\obeyspaces% +\gdef\vtablex #1^^M{% +\tabley\vritemindex#1 \endtabley +\def\Evtable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\dontindex #1{} +\def\fnitemindex #1{\doind {fn}{\code{#1}}}% +\def\vritemindex #1{\doind {vr}{\code{#1}}}% + +{\obeyspaces % +\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% +\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} + +\def\tablez #1#2#3#4#5#6{% +\aboveenvbreak % +\begingroup % +\def\Edescription{\Etable}% Necessary kludge. +\let\itemindex=#1% +\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % +\ifnum 0#4>0 \tableindent=#4\mil \fi % +\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % +\def\itemfont{#2}% +\itemmax=\tableindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \tableindent % +\exdentamount=\tableindent +\parindent = 0pt +\parskip = \smallskipamount +\ifdim \parskip=0pt \parskip=2pt \fi% +\def\Etable{\endgraf\afterenvbreak\endgroup}% +\let\item = \internalBitem % +\let\itemx = \internalBitemx % +\let\kitem = \internalBkitem % +\let\kitemx = \internalBkitemx % +\let\xitem = \internalBxitem % +\let\xitemx = \internalBxitemx % +} + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\def\itemize{\parsearg\itemizezzz} + +\def\itemizezzz #1{% + \begingroup % ended by the @end itemsize + \itemizey {#1}{\Eitemize} +} + +\def\itemizey #1#2{% +\aboveenvbreak % +\itemmax=\itemindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \itemindent % +\exdentamount=\itemindent +\parindent = 0pt % +\parskip = \smallskipamount % +\ifdim \parskip=0pt \parskip=2pt \fi% +\def#2{\endgraf\afterenvbreak\endgroup}% +\def\itemcontents{#1}% +\let\item=\itemizeitem} + +% Set sfcode to normal for the chars that usually have another value. +% These are `.?!:;,' +\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 + \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } + +% \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'. +% +\def\enumerate{\parsearg\enumeratezzz} +\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + \begingroup % ended by the @end enumerate + % + % 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 . + % + \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 itemizey, 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 + \itemizey{#1.}\Eenumerate\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} + +% Definition of @item while inside @itemize. + +\def\itemizeitem{% +\advance\itemno by 1 +{\let\par=\endgraf \smallbreak}% +\ifhmode \errmessage{In hmode at itemizeitem}\fi +{\parskip=0in \hskip 0pt +\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% +\vadjust{\penalty 1200}}% +\flushcr} + +% @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. +% +% For those who want to use more than one line's worth of words in +% the preamble, break the line within one argument and it +% will parse correctly, i.e., +% +% @multitable {Column 1 template} {Column 2 template} {Column 3 +% template} +% Not: +% @multitable {Column 1 template} {Column 2 template} +% {Column 3 template} + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab, @multitable or @end multitable 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 + +% 2/1/96, to allow fractions to be given with more than one digit. +\def\pickupwholefraction#1 {\global\advance\colcount by1 % +\expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% +\setuptable} + +\newcount\colcount +\def\setuptable#1{\def\firstarg{#1}% +\ifx\firstarg\xendsetuptable\let\go\relax% +\else + \ifx\firstarg\xcolumnfractions\global\setpercenttrue% + \else + \ifsetpercent + \let\go\pickupwholefraction % In this case arg of setuptable + % is the decimal point before the + % number given in percent of hsize. + % We don't need this so we don't use it. + \else + \global\advance\colcount by1 + \setbox0=\hbox{#1 }% 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\else\let\go\setuptable\fi% +\fi\go} + +% multitable syntax +\def\tab{&\hskip1sp\relax} % 2/2/96 + % tiny skip here makes sure this column space is + % maintained, even if it is never used. + +% @multitable ... @end multitable definitions: + +\def\multitable{\parsearg\dotable} +\def\dotable#1{\bgroup + \vskip\parskip + \let\item\crcr + \tolerance=9500 + \hbadness=9500 + \setmultitablespacing + \parskip=\multitableparskip + \parindent=\multitableparindent + \overfullrule=0pt + \global\colcount=0 + \def\Emultitable{\global\setpercentfalse\cr\egroup\egroup}% + % + % To parse everything between @multitable and @item: + \setuptable#1 \endsetuptable + % + % \everycr will reset column counter, \colcount, at the end of + % each line. Every column entry will cause \colcount to advance by one. + % The table preamble + % looks at the current \colcount to find the correct column width. + \everycr{\noalign{% + % + % \filbreak%% keeps underfull box messages off when table breaks over pages. + % 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. + \global\colcount=0\relax}}% + % + % 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\relax + \multistrut\vtop{\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\setmultitablespacing{% test to see if user has set \multitablelinespace. +% If so, do nothing. If not, give it an appropriate dimension based on +% current baselineskip. +\ifdim\multitablelinespace=0pt +%% strut to put in table in case some entry doesn't have descenders, +%% to keep lines equally spaced +\let\multistrut = \strut +%% 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. +\else +\gdef\multistrut{\vrule height\multitablelinespace depth\dp0 +width0pt\relax} \fi +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi} + + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within \newindex. +{\catcode`\@=11 +\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}} + +% \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{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#1}} +} + +% @defindex foo == \newindex{foo} + +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. + +\def\newcodeindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#1}} +} + +\def\defcodeindex{\parsearg\newcodeindex} + +% @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. +\def\synindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#2}}% +} + +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +\def\syncodeindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#2}}% +} + +% 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}}} + +\def\indexdummies{% +% Take care of the plain tex accent commands. +\def\"{\realbackslash "}% +\def\`{\realbackslash `}% +\def\'{\realbackslash '}% +\def\^{\realbackslash ^}% +\def\~{\realbackslash ~}% +\def\={\realbackslash =}% +\def\b{\realbackslash b}% +\def\c{\realbackslash c}% +\def\d{\realbackslash d}% +\def\u{\realbackslash u}% +\def\v{\realbackslash v}% +\def\H{\realbackslash H}% +% Take care of the plain tex special European modified letters. +\def\oe{\realbackslash oe}% +\def\ae{\realbackslash ae}% +\def\aa{\realbackslash aa}% +\def\OE{\realbackslash OE}% +\def\AE{\realbackslash AE}% +\def\AA{\realbackslash AA}% +\def\o{\realbackslash o}% +\def\O{\realbackslash O}% +\def\l{\realbackslash l}% +\def\L{\realbackslash L}% +\def\ss{\realbackslash ss}% +% Take care of texinfo commands likely to appear in an index entry. +% (Must be a way to avoid doing expansion at all, and thus not have to +% laboriously list every single command here.) +\def\@{@}% will be @@ when we switch to @ as escape char. +%\let\{ = \lbracecmd +%\let\} = \rbracecmd +\def\_{{\realbackslash _}}% +\def\w{\realbackslash w }% +\def\bf{\realbackslash bf }% +%\def\rm{\realbackslash rm }% +\def\sl{\realbackslash sl }% +\def\sf{\realbackslash sf}% +\def\tt{\realbackslash tt}% +\def\gtr{\realbackslash gtr}% +\def\less{\realbackslash less}% +\def\hat{\realbackslash hat}% +%\def\char{\realbackslash char}% +\def\TeX{\realbackslash TeX}% +\def\dots{\realbackslash dots }% +\def\result{\realbackslash result}% +\def\equiv{\realbackslash equiv}% +\def\expansion{\realbackslash expansion}% +\def\print{\realbackslash print}% +\def\error{\realbackslash error}% +\def\point{\realbackslash point}% +\def\copyright{\realbackslash copyright}% +\def\tclose##1{\realbackslash tclose {##1}}% +\def\code##1{\realbackslash code {##1}}% +\def\dotless##1{\realbackslash dotless {##1}}% +\def\samp##1{\realbackslash samp {##1}}% +\def\,##1{\realbackslash ,{##1}}% +\def\t##1{\realbackslash t {##1}}% +\def\r##1{\realbackslash r {##1}}% +\def\i##1{\realbackslash i {##1}}% +\def\b##1{\realbackslash b {##1}}% +\def\sc##1{\realbackslash sc {##1}}% +\def\cite##1{\realbackslash cite {##1}}% +\def\key##1{\realbackslash key {##1}}% +\def\file##1{\realbackslash file {##1}}% +\def\var##1{\realbackslash var {##1}}% +\def\kbd##1{\realbackslash kbd {##1}}% +\def\dfn##1{\realbackslash dfn {##1}}% +\def\emph##1{\realbackslash emph {##1}}% +\def\value##1{\realbackslash value {##1}}% +\unsepspaces +} + +% 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 \ ). +{\obeyspaces + \gdef\unsepspaces{\obeyspaces\let =\space}} + +% \indexnofonts no-ops all font-change commands. +% This is used when outputting the strings to sort the index by. +\def\indexdummyfont#1{#1} +\def\indexdummytex{TeX} +\def\indexdummydots{...} + +\def\indexnofonts{% +% Just ignore accents. +\let\,=\indexdummyfont +\let\"=\indexdummyfont +\let\`=\indexdummyfont +\let\'=\indexdummyfont +\let\^=\indexdummyfont +\let\~=\indexdummyfont +\let\==\indexdummyfont +\let\b=\indexdummyfont +\let\c=\indexdummyfont +\let\d=\indexdummyfont +\let\u=\indexdummyfont +\let\v=\indexdummyfont +\let\H=\indexdummyfont +\let\dotless=\indexdummyfont +% Take care of the plain tex special European modified letters. +\def\oe{oe}% +\def\ae{ae}% +\def\aa{aa}% +\def\OE{OE}% +\def\AE{AE}% +\def\AA{AA}% +\def\o{o}% +\def\O{O}% +\def\l{l}% +\def\L{L}% +\def\ss{ss}% +\let\w=\indexdummyfont +\let\t=\indexdummyfont +\let\r=\indexdummyfont +\let\i=\indexdummyfont +\let\b=\indexdummyfont +\let\emph=\indexdummyfont +\let\strong=\indexdummyfont +\let\cite=\indexdummyfont +\let\sc=\indexdummyfont +%Don't no-op \tt, since it isn't a user-level command +% and is used in the definitions of the active chars like <, >, |... +%\let\tt=\indexdummyfont +\let\tclose=\indexdummyfont +\let\code=\indexdummyfont +\let\file=\indexdummyfont +\let\samp=\indexdummyfont +\let\kbd=\indexdummyfont +\let\key=\indexdummyfont +\let\var=\indexdummyfont +\let\TeX=\indexdummytex +\let\dots=\indexdummydots +\def\@{@}% +} + +% To define \realbackslash, we must make \ not be an escape. +% We must first make another character (@) an escape +% so we do not become unable to do a definition. + +{\catcode`\@=0 \catcode`\\=\other +@gdef@realbackslash{\}} + +\let\indexbackslash=0 %overridden during \printindex. + +\let\SETmarginindex=\relax %initialize! +% workhorse for all \fooindexes +% #1 is name of index, #2 is stuff to put there +\def\doind #1#2{% + % Put the index entry in the margin if desired. + \ifx\SETmarginindex\relax\else + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% + \fi + {% + \count255=\lastpenalty + {% + \indexdummies % Must do this here, since \bf, etc expand at this stage + \escapechar=`\\ + {% + \let\folio=0% We will expand all macros now EXCEPT \folio. + \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now + % so it will be output as is; and it will print as backslash. + % + % First process the index-string with all font commands turned off + % to get the string to sort by. + {\indexnofonts \xdef\indexsorttmp{#2}}% + % + % Now produce the complete index entry, with both the sort key and the + % original text, including any font commands. + \toks0 = {#2}% + \edef\temp{% + \write\csname#1indfile\endcsname{% + \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}% + }% + \temp + }% + }% + \penalty\count255 + }% +} + +\def\dosubind #1#2#3{% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% +\def\rawbackslashxx{\indexbackslash}% +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2 #3}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}{#3}}}% +\temp }% +}\penalty\count10}} + +% 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). +% +\def\printindex{\parsearg\doprintindex} +\def\doprintindex#1{\begingroup + \dobreak \chapheadingskip{10000}% + % + \indexfonts \rm + \tolerance = 9500 + \indexbreaks + % + % 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. + (Index is nonexistent) + \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 + (Index is empty) + \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{\rawbackslashxx}% + \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. + +% Same as \bigskipamount except no shrink. +% \balancecolumns gets confused if there is any shrink. +\newskip\initialskipamount \initialskipamount 12pt plus4pt + +\def\initial #1{% +{\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt +\ifdim\lastskip<\initialskipamount +\removelastskip \penalty-200 \vskip \initialskipamount\fi +\line{\secbf#1\hfill}\kern 2pt\penalty10000}} + +% This typesets a paragraph consisting of #1, dot leaders, and then #2 +% flush to the right margin. It is used for index and table of contents +% entries. The paragraph is indented by \leftskip. +% +\def\entry #1#2{\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 + % + % Start a ``paragraph'' for the index entry so the line breaking + % parameters we've set above will have an effect. + \noindent + % + % Insert the text of the index entry. TeX will do line-breaking on it. + #1% + % 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{#2}% + \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. + \ #2% The page number ends the paragraph. + \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 #2\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 = {\global\setbox\partialpage = \vbox{% + % + % 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 must prevent the second \partialpage from + % simply overwriting the first, causing us to lose the page. + % This will preserve it until a real output routine can ship it + % out. Generally, \partialpage will be empty when this runs and + % this will be a no-op. + \unvbox\partialpage + % + % Unvbox the main output page. + \unvbox255 + \kern-\topskip \kern\baselineskip + }}% + \eject + % + % 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 +} +\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@=\pageheight \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 +} +\def\pagesofar{% + % Re-output the contents of the output page -- any previous material, + % followed by the two boxes we just split. + \unvbox\partialpage + \hsize = \doublecolumnhsize + \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}% +} +\def\enddoublecolumns{% + \output = {\balancecolumns}\eject % split what we have + \endgroup % started in \begindoublecolumns + % + % Back to normal single-column typesetting, but take account of the + % fact that we just accumulated some stuff on the output page. + \pagegoal = \vsize +} +\def\balancecolumns{% + % Called at the end of the double column material. + \setbox0 = \vbox{\unvbox255}% + \dimen@ = \ht0 + \advance\dimen@ by \topskip + \advance\dimen@ by-\baselineskip + \divide\dimen@ by 2 + \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@ by1pt + \repeat}% + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + \pagesofar +} +\catcode`\@ = \other + + +\message{sectioning,} +% Define chapters, sections, etc. + +\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} + +\newwrite\contentsfile +% This is called from \setfilename. +\def\opencontents{\openout\contentsfile = \jobname.toc } + +% Each @chapter defines this as the name of the chapter. +% page headings and footings can use it. @section does likewise + +\def\thischapter{} \def\thissection{} +\def\seccheck#1{\ifnum \pageno<0 + \errmessage{@#1 not allowed after generating table of contents}% +\fi} + +\def\chapternofonts{% + \let\rawbackslash=\relax + \let\frenchspacing=\relax + \def\result{\realbackslash result}% + \def\equiv{\realbackslash equiv}% + \def\expansion{\realbackslash expansion}% + \def\print{\realbackslash print}% + \def\TeX{\realbackslash TeX}% + \def\dots{\realbackslash dots}% + \def\result{\realbackslash result}% + \def\equiv{\realbackslash equiv}% + \def\expansion{\realbackslash expansion}% + \def\print{\realbackslash print}% + \def\error{\realbackslash error}% + \def\point{\realbackslash point}% + \def\copyright{\realbackslash copyright}% + \def\tt{\realbackslash tt}% + \def\bf{\realbackslash bf}% + \def\w{\realbackslash w}% + \def\less{\realbackslash less}% + \def\gtr{\realbackslash gtr}% + \def\hat{\realbackslash hat}% + \def\char{\realbackslash char}% + \def\tclose##1{\realbackslash tclose{##1}}% + \def\code##1{\realbackslash code{##1}}% + \def\samp##1{\realbackslash samp{##1}}% + \def\r##1{\realbackslash r{##1}}% + \def\b##1{\realbackslash b{##1}}% + \def\key##1{\realbackslash key{##1}}% + \def\file##1{\realbackslash file{##1}}% + \def\kbd##1{\realbackslash kbd{##1}}% + % These are redefined because @smartitalic wouldn't work inside xdef. + \def\i##1{\realbackslash i{##1}}% + \def\cite##1{\realbackslash cite{##1}}% + \def\var##1{\realbackslash var{##1}}% + \def\emph##1{\realbackslash emph{##1}}% + \def\dfn##1{\realbackslash dfn{##1}}% +} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raise/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 + +% Choose a numbered-heading macro +% #1 is heading level if unmodified by @raisesections or @lowersections +% #2 is text for heading +\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \chapterzzz{#2} +\or + \seczzz{#2} +\or + \numberedsubseczzz{#2} +\or + \numberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \chapterzzz{#2} + \else + \numberedsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses appendix heading levels +\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \appendixzzz{#2} +\or + \appendixsectionzzz{#2} +\or + \appendixsubseczzz{#2} +\or + \appendixsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \appendixzzz{#2} + \else + \appendixsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses numberless heading levels +\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \unnumberedzzz{#2} +\or + \unnumberedseczzz{#2} +\or + \unnumberedsubseczzz{#2} +\or + \unnumberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \unnumberedzzz{#2} + \else + \unnumberedsubsubseczzz{#2} + \fi +\fi +} + + +\def\thischaptername{No Chapter Title} +\outer\def\chapter{\parsearg\chapteryyy} +\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz #1{\seccheck{chapter}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \chapno by 1 \message{\putwordChapter \the\chapno}% +\chapmacro {#1}{\the\chapno}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +% We don't substitute the actual chapter name into \thischapter +% because we don't want its macros evaluated now. +\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash chapentry{\the\toks0}{\the\chapno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec +}} + +\outer\def\appendix{\parsearg\appendixyyy} +\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz #1{\seccheck{appendix}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \appendixno by 1 \message{Appendix \appendixletter}% +\chapmacro {#1}{\putwordAppendix{} \appendixletter}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash chapentry{\the\toks0}% + {\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\global\let\section = \appendixsec +\global\let\subsection = \appendixsubsec +\global\let\subsubsection = \appendixsubsubsec +}} + +% @centerchap is like @unnumbered, but the heading is centered. +\outer\def\centerchap{\parsearg\centerchapyyy} +\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}} + +\outer\def\top{\parsearg\unnumberedyyy} +\outer\def\unnumbered{\parsearg\unnumberedyyy} +\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz #1{\seccheck{unnumbered}% +\secno=0 \subsecno=0 \subsubsecno=0 +% +% 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 to achieve this: TeX expands \the only once, +% simply yielding the contents of the . +\toks0 = {#1}\message{(\the\toks0)}% +% +\unnumbchapmacro {#1}% +\gdef\thischapter{#1}\gdef\thissection{#1}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbchapentry{\the\toks0}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\global\let\section = \unnumberedsec +\global\let\subsection = \unnumberedsubsec +\global\let\subsubsection = \unnumberedsubsubsec +}} + +\outer\def\numberedsec{\parsearg\secyyy} +\def\secyyy #1{\numhead1{#1}} % normally calls seczzz +\def\seczzz #1{\seccheck{section}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash secentry % +{\the\toks0}{\the\chapno}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsec{\parsearg\appendixsecyyy} +\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz #1{\seccheck{appendixsection}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash secentry % +{\the\toks0}{\appendixletter}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} +\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz #1{\seccheck{unnumberedsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbsecentry{\the\toks0}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} +\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz #1{\seccheck{subsection}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash subsecentry % +{\the\toks0}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} +\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz #1{\seccheck{appendixsubsec}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash subsecentry % +{\the\toks0}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} +\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% +\plainsubsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbsubsecentry{\the\toks0}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} +\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz #1{\seccheck{subsubsection}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash subsubsecentry{\the\toks0} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} + {\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} +\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz #1{\seccheck{appendixsubsubsec}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash subsubsecentry{\the\toks0}% + {\appendixletter} + {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} +\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% +\plainsubsubsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbsubsubsecentry{\the\toks0}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +% These are variants which are not "outer", so they can appear in @ifinfo. +% Actually, they should now be obsolete; ordinary section commands should work. +\def\infotop{\parsearg\unnumberedzzz} +\def\infounnumbered{\parsearg\unnumberedzzz} +\def\infounnumberedsec{\parsearg\unnumberedseczzz} +\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz} +\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz} + +\def\infoappendix{\parsearg\appendixzzz} +\def\infoappendixsec{\parsearg\appendixseczzz} +\def\infoappendixsubsec{\parsearg\appendixsubseczzz} +\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz} + +\def\infochapter{\parsearg\chapterzzz} +\def\infosection{\parsearg\sectionzzz} +\def\infosubsection{\parsearg\subsectionzzz} +\def\infosubsubsection{\parsearg\subsubsectionzzz} + +% 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. +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\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{\parsearg\majorheadingzzz} +\def\majorheadingzzz #1{% +{\advance\chapheadingskip by 10pt \chapbreak }% +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\chapheading{\parsearg\chapheadingzzz} +\def\chapheadingzzz #1{\chapbreak % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +% @heading, @subheading, @subsubheading. +\def\heading{\parsearg\plainsecheading} +\def\subheading{\parsearg\plainsubsecheading} +\def\subsubheading{\parsearg\plainsubsubsecheading} + +% 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} + +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} + +%%% 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 + +\def\CHAPFplain{ +\global\let\chapmacro=\chfplain +\global\let\unnumbchapmacro=\unnchfplain +\global\let\centerchapmacro=\centerchfplain} + +% Plain chapter opening. +% #1 is the text, #2 the chapter number or empty if unnumbered. +\def\chfplain#1#2{% + \pchapsepmacro + {% + \chapfonts \rm + \def\chapnum{#2}% + \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}% + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent = \wd0 \centerparametersmaybe + \unhbox0 #1\par}% + }% + \nobreak\bigskip % no page break after a chapter title + \nobreak +} + +% Plain opening for unnumbered. +\def\unnchfplain#1{\chfplain{#1}{}} + +% @centerchap -- centered and unnumbered. +\let\centerparametersmaybe = \relax +\def\centerchfplain#1{{% + \def\centerparametersmaybe{% + \advance\rightskip by 3\rightskip + \leftskip = \rightskip + \parfillskip = 0pt + }% + \chfplain{#1}{}% +}} + +\CHAPFplain % The default + +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} + +\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\penalty 10000 % +} + +\def\CHAPFopen{ +\global\let\chapmacro=\chfopen +\global\let\unnumbchapmacro=\unnchfopen +\global\let\centerchapmacro=\centerchfopen} + + +% Section titles. +\newskip\secheadingskip +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} +\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}} +\def\plainsecheading#1{\sectionheading{sec}{}{#1}} + +% Subsection titles. +\newskip \subsecheadingskip +\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} +\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}} +\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}} + +% Subsubsection titles. +\let\subsubsecheadingskip = \subsecheadingskip +\let\subsubsecheadingbreak = \subsecheadingbreak +\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}} +\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}} + + +% Print any size section title. +% +% #1 is the section type (sec/subsec/subsubsec), #2 is the section +% number (maybe empty), #3 the text. +\def\sectionheading#1#2#3{% + {% + \expandafter\advance\csname #1headingskip\endcsname by \parskip + \csname #1headingbreak\endcsname + }% + {% + % Switch to the right set of fonts. + \csname #1fonts\endcsname \rm + % + % Only insert the separating space if we have a section number. + \def\secnum{#2}% + \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}% + % + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent = \wd0 % zero if no section number + \unhbox0 #3}% + }% + \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak +} + + +\message{toc printing,} +% Finish up the main text and prepare to read what we've written +% to \contentsfile. + +\newskip\contentsrightmargin \contentsrightmargin=1in +\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 + \contentsalignmacro + \immediate\closeout \contentsfile + \ifnum \pageno>0 + \pageno = -1 % Request roman numbered pages. + \fi + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \unnumbchapmacro{#1}\def\thischapter{}% + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + % We can't do this, because then an actual ^ in a section + % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97. + %\catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. +} + + +% Normal (long) toc. +\outer\def\contents{% + \startcontents{\putwordTableofContents}% + \input \jobname.toc + \endgroup + \vfill \eject +} + +% And just the chapters. +\outer\def\summarycontents{% + \startcontents{\putwordShortContents}% + % + \let\chapentry = \shortchapentry + \let\unnumbchapentry = \shortunnumberedentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \rm + \hyphenpenalty = 10000 + \advance\baselineskip by 1pt % Open it up a little. + \def\secentry ##1##2##3##4{} + \def\unnumbsecentry ##1##2{} + \def\subsecentry ##1##2##3##4##5{} + \def\unnumbsubsecentry ##1##2{} + \def\subsubsecentry ##1##2##3##4##5##6{} + \def\unnumbsubsubsecentry ##1##2{} + \input \jobname.toc + \endgroup + \vfill \eject +} +\let\shortcontents = \summarycontents + +% 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, ... + +% Chapter-level things, for both the long and short contents. +\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} + +% See comments in \dochapentry re vbox and related settings +\def\shortchapentry#1#2#3{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno{#3}}% +} + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter. +% We could simplify the code here by writing out an \appendixentry +% command in the toc file for appendices, instead of using \chapentry +% for both, but it doesn't seem worth it. +\setbox0 = \hbox{\shortcontrm \putwordAppendix } +\newdimen\shortappendixwidth \shortappendixwidth = \wd0 + +\def\shortchaplabel#1{% + % We typeset #1 in a box of constant width, regardless of the text of + % #1, so the chapter titles will come out aligned. + \setbox0 = \hbox{#1}% + \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi + % + % This space should be plenty, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in by \shortchapentry above.) + \advance\dimen0 by 1.1em + \hbox to \dimen0{#1\hfil}% +} + +\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} +\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno{#2}}} + +% Sections. +\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} +\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} + +% Subsections. +\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} +\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} + +% And subsubsections. +\def\subsubsecentry#1#2#3#4#5#6{% + \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} +\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} + +% This parameter controls the indentation of the various levels. +\newdimen\tocindent \tocindent = 3pc + +% 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{#2}}% + \endgroup + \nobreak\vskip .25\baselineskip plus.1\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +% Final typesetting of a toc entry; we use the same \entry macro as for +% the index entries, but we want to suppress hyphenation here. (We +% can't do that in the \entry macro, since index entries might consist +% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) +\def\tocentry#1#2{\begingroup + \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks + % Do not use \turnoffactive in these arguments. Since the toc is + % typeset in cmr, so characters such as _ would come out wrong; we + % have to do the usual translation tricks. + \entry{#1}{#2}% +\endgroup} + +% 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} +\let\subsecentryfonts = \textfonts +\let\subsubsecentryfonts = \textfonts + + +\message{environments,} + +% 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. +% Furthermore, these definitions must come after we define our fonts. +\newbox\dblarrowbox \newbox\longdblarrowbox +\newbox\pushcharbox \newbox\bullbox +\newbox\equivbox \newbox\errorbox + +%{\tentt +%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} +%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} +%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} +%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} +% Adapted from the manmac format (p.420 of TeXbook) +%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex +% depth .1ex\hfil} +%} + +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +\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}} + +% Adapted from the TeXbook's \boxit. +{\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} + +\global\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} + +% The @error{} command. +\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. + +\def\tex{\begingroup + \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 + \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 + \catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie + \catcode `\%=14 + \catcode 43=12 % plus + \catcode`\"=12 + \catcode`\==12 + \catcode`\|=12 + \catcode`\<=12 + \catcode`\>=12 + \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\{=\ptexlbrace + \let\}=\ptexrbrace + \let\*=\ptexstar + \let\t=\ptext + % + \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% + \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% + \def\@{@}% +\let\Etex=\endgroup} + +% Define @lisp ... @endlisp. +% @lisp does a \begingroup so it can rebind things, +% including the definition of @endlisp (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} + +% 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. +% +{\obeyspaces % +\gdef\sepspaces{\obeyspaces\let =\tie}} + +% Define \obeyedspace to be our active space, whatever it is. This is +% for use in \parsearg. +{\sepspaces% +\global\let\obeyedspace= } + +% 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{{\advance\envskipamount by \parskip +\endgraf \ifdim\lastskip<\envskipamount +\removelastskip \penalty-50 \vskip\envskipamount \fi}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. +\let\nonarrowing=\relax + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \cartouche: draw rectangle w/rounded corners around argument +\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 + +\long\def\cartouche{% +\begingroup + \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 18pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char + \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 + \hsize=\cartinner + \kern3pt + \begingroup + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip +\def\Ecartouche{% + \endgroup + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup +\endgroup +}} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\def\nonfillstart{% + \aboveenvbreak + \inENV % This group ends at the end of the body + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \singlespace + \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 + \let\exdent=\nofillexdent + \let\nonarrowing=\relax + \fi +} + +% To ending an @example-like environment, we first end the paragraph +% (via \afterenvbreak's vertical glue), and then the group. That way we +% keep the zero \parskip that the environments set -- \parskip glue +% will be inserted at the beginning of the next paragraph in the +% document, after the environment. +% +\def\nonfillfinish{\afterenvbreak\endgroup}% + +\def\lisp{\begingroup + \nonfillstart + \let\Elisp = \nonfillfinish + \tt + % Make @kbd do something special, if requested. + \let\kbdfont\kbdexamplefont + \rawbackslash % have \ input char produce \ char from current font + \gobble +} + +% Define the \E... control sequence only if we are inside the +% environment, so the error checking in \end will work. +% +% We must call \lisp last in the definition, since it reads the +% return following the @example (or whatever) command. +% +\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} +\def\smallexample{\begingroup \def\Esmallexample{\nonfillfinish\endgroup}\lisp} +\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}\lisp} + +% @smallexample and @smalllisp. This is not used unless the @smallbook +% command is given. Originally contributed by Pavel@xerox. +% +\def\smalllispx{\begingroup + \nonfillstart + \let\Esmalllisp = \nonfillfinish + \let\Esmallexample = \nonfillfinish + % + % Smaller fonts for small examples. + \indexfonts \tt + \rawbackslash % make \ output the \ character from the current font (tt) + \gobble +} + +% This is @display; same as @lisp except use roman font. +% +\def\display{\begingroup + \nonfillstart + \let\Edisplay = \nonfillfinish + \gobble +} + +% This is @format; same as @display except don't narrow margins. +% +\def\format{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eformat = \nonfillfinish + \gobble +} + +% @flushleft (same as @format) and @flushright. +% +\def\flushleft{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushleft = \nonfillfinish + \gobble +} +\def\flushright{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushright = \nonfillfinish + \advance\leftskip by 0pt plus 1fill + \gobble} + +% @quotation does normal linebreaking (hence we can't use \nonfillstart) +% and narrows the margins. +% +\def\quotation{% + \begingroup\inENV %This group ends at the end of the @quotation body + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \singlespace + \parindent=0pt + % We have retained a nonzero parskip for the environment, since we're + % doing normal filling. So to avoid extra space below the environment... + \def\Equotation{\parskip = 0pt \nonfillfinish}% + % + % @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 +} + +\message{defuns,} +% Define formatter for defuns +% First, allow user to change definition object font (\df) internally +\def\setdeffont #1 {\csname DEF#1\endcsname} + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deftypemargin \deftypemargin=12pt +\newskip\deflastargmargin \deflastargmargin=18pt + +\newcount\parencount +% define \functionparens, which makes ( and ) and & do special things. +% \functionparens affects the group it is contained in. +\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 = ) + +{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) + +% 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. +\global\let(=\lparen \global\let)=\rparen +\global\let[=\lbrack \global\let]=\rbrack + +\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } +\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} +% This is used to turn on special parens +% but make & act ordinary (given that it's active). +\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr} + +% Definitions of (, ) and & used in args for functions. +% This is the definition of ( outside of all parentheses. +\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested + \global\advance\parencount by 1 +} +% +% This is the definition of ( when already inside a level of parens. +\gdef\opnested{\char`\(\global\advance\parencount by 1 } +% +\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. + % also in that case restore the outer-level definition of (. + \ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi + \global\advance \parencount by -1 } +% If we encounter &foo, then turn on ()-hacking afterwards +\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } +% +\gdef\normalparens{\boldbrax\let&=\ampnr} +} % End of definition inside \activeparens +%% These parens (in \boldbrax) actually are a little bolder than the +%% contained text. This is especially needed for [ and ] +\def\opnr{{\sf\char`\(}\global\advance\parencount by 1 } +\def\clnr{{\sf\char`\)}\global\advance\parencount by -1 } +\def\ampnr{\&} +\def\lbrb{{\bf\char`\[}} +\def\rbrb{{\bf\char`\]}} + +% First, defname, which formats the header line itself. +% #1 should be the function name. +% #2 should be the type of definition, such as "Function". + +\def\defname #1#2{% +% Get the values of \leftskip and \rightskip as they were +% outside the @def... +\dimen2=\leftskip +\advance\dimen2 by -\defbodyindent +\dimen3=\rightskip +\advance\dimen3 by -\defbodyindent +\noindent % +\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% +\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line +\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations +\parshape 2 0in \dimen0 \defargsindent \dimen1 % +% Now output arg 2 ("Function" or some such) +% ending at \deftypemargin from the right margin, +% but stuck inside a box of width 0 so it does not interfere with linebreaking +{% Adjust \hsize to exclude the ambient margins, +% so that \rightline will obey them. +\advance \hsize by -\dimen2 \advance \hsize by -\dimen3 +\rlap{\rightline{{\rm #2}\hskip \deftypemargin}}}% +% Make all lines underfull and no complaints: +\tolerance=10000 \hbadness=10000 +\advance\leftskip by -\defbodyindent +\exdentamount=\defbodyindent +{\df #1}\enskip % Generate function name +} + +% Actually process the body of a definition +% #1 should be the terminating control sequence, such as \Edefun. +% #2 should be the "another name" control sequence, such as \defunx. +% #3 should be the control sequence that actually processes the header, +% such as \defunheader. + +\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % 61 is `=' +\obeylines\activeparens\spacesplit#3} + +\def\defmethparsebody #1#2#3#4 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} + +\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} + +% These parsing functions are similar to the preceding ones +% except that they do not make parens into active characters. +% These are used for "variables" since they have no arguments. + +\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % +\obeylines\spacesplit#3} + +% This is used for \def{tp,vr}parsebody. It could probably be used for +% some of the others, too, with some judicious conditionals. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV % + \medbreak % + % Define the end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% + \parindent=0in + \advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent + \exdentamount=\defbodyindent + \begingroup\obeylines +} + +\def\defvrparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{#3{#4}}% +} + +% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the +% type is just `struct', because we lose the braces in `{struct +% termios}' when \spacesplit reads its undelimited argument. Sigh. +% \let\deftpparsebody=\defvrparsebody +% +% So, to get around this, we put \empty in with the type name. That +% way, TeX won't find exactly `{...}' as an undelimited argument, and +% won't strip off the braces. +% +\def\deftpparsebody #1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{\parsetpheaderline{#3{#4}}}\empty +} + +% Fine, but then we have to eventually remove the \empty *and* the +% braces (if any). That's what this does. +% +\def\removeemptybraces\empty#1\relax{#1} + +% After \spacesplit has done its work, this is called -- #1 is the final +% thing to call, #2 the type name (which starts with \empty), and #3 +% (which might be empty) the arguments. +% +\def\parsetpheaderline#1#2#3{% + #1{\removeemptybraces#2\relax}{#3}% +}% + +\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\spacesplit{#3{#5}}} + +% Split up #2 at the first space token. +% call #1 with two arguments: +% the first is all of #2 before the space token, +% the second is all of #2 after that space token. +% If #2 contains no space token, all of it is passed as the first arg +% and the second is passed as empty. + +{\obeylines +\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% +\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% +\ifx\relax #3% +#1{#2}{}\else #1{#2}{#3#4}\fi}} + +% So much for the things common to all kinds of definitions. + +% Define @defun. + +% First, define the processing that is wanted for arguments of \defun +% Use this to expand the args and terminate the paragraph they make up + +\def\defunargs #1{\functionparens \sl +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +\hyphenchar\tensl=0 +#1% +\hyphenchar\tensl=45 +\ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi% +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +\def\deftypefunargs #1{% +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +% Use \boldbraxnoamp, not \functionparens, so that & is not special. +\boldbraxnoamp +\tclose{#1}% avoid \code because of side effects on active chars +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +% Do complete processing of one @defun or @defunx line already parsed. + +% @deffn Command forward-char nchars + +\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} + +\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% +\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defun == @deffn Function + +\def\defun{\defparsebody\Edefun\defunx\defunheader} + +\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Function}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefun int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} + +% #1 is the data type. #2 is the name and args. +\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} +% #1 is the data type, #2 the name, #3 the args. +\def\deftypefunheaderx #1#2 #3\relax{% +\doind {fn}{\code{#2}}% Make entry in function index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Function}% +\deftypefunargs {#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} + +% \defheaderxcond#1\relax$$$ +% puts #1 in @code, followed by a space, but does nothing if #1 is null. +\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi} + +% #1 is the classification. #2 is the data type. #3 is the name and args. +\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} +% #1 is the classification, #2 the data type, #3 the name, #4 the args. +\def\deftypefnheaderx #1#2#3 #4\relax{% +\doind {fn}{\code{#3}}% Make entry in function index +\begingroup +\normalparens % notably, turn off `&' magic, which prevents +% at least some C++ text from working +\defname {\defheaderxcond#2\relax$$$#3}{#1}% +\deftypefunargs {#4}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defmac == @deffn Macro + +\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} + +\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Macro}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defspec == @deffn Special Form + +\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} + +\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Special Form}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% This definition is run if you use @defunx +% anywhere other than immediately after a @defun or @defunx. + +\def\deffnx #1 {\errmessage{@deffnx in invalid context}} +\def\defunx #1 {\errmessage{@defunx in invalid context}} +\def\defmacx #1 {\errmessage{@defmacx in invalid context}} +\def\defspecx #1 {\errmessage{@defspecx in invalid context}} +\def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypemethodx #1 {\errmessage{@deftypemethodx in invalid context}} +\def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} + +% @defmethod, and so on + +% @defop {Funny Method} foo-class frobnicate argument + +\def\defop #1 {\def\defoptype{#1}% +\defopparsebody\Edefop\defopx\defopheader\defoptype} + +\def\defopheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% Make entry in function index +\begingroup\defname {#2}{\defoptype{} on #1}% +\defunargs {#3}\endgroup % +} + +% @deftypemethod foo-class return-type foo-method args +% +\def\deftypemethod{% + \defmethparsebody\Edeftypemethod\deftypemethodx\deftypemethodheader} +% +% #1 is the class name, #2 the data type, #3 the method name, #4 the args. +\def\deftypemethodheader#1#2#3#4{% + \deftypefnheaderx{Method on #1}{#2}#3 #4\relax +} + +% @defmethod == @defop Method + +\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} + +\def\defmethodheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% entry in function index +\begingroup\defname {#2}{Method on #1}% +\defunargs {#3}\endgroup % +} + +% @defcv {Class Option} foo-class foo-flag + +\def\defcv #1 {\def\defcvtype{#1}% +\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} + +\def\defcvarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{\defcvtype{} of #1}% +\defvarargs {#3}\endgroup % +} + +% @defivar == @defcv {Instance Variable} + +\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} + +\def\defivarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{Instance Variable of #1}% +\defvarargs {#3}\endgroup % +} + +% These definitions are run if you use @defmethodx, etc., +% anywhere other than immediately after a @defmethod, etc. + +\def\defopx #1 {\errmessage{@defopx in invalid context}} +\def\defmethodx #1 {\errmessage{@defmethodx in invalid context}} +\def\defcvx #1 {\errmessage{@defcvx in invalid context}} +\def\defivarx #1 {\errmessage{@defivarx in invalid context}} + +% Now @defvar + +% First, define the processing that is wanted for arguments of @defvar. +% This is actually simple: just print them in roman. +% This must expand the args and terminate the paragraph they make up +\def\defvarargs #1{\normalparens #1% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000} + +% @defvr Counter foo-count + +\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} + +\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% +\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} + +% @defvar == @defvr Variable + +\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} + +\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{Variable}% +\defvarargs {#2}\endgroup % +} + +% @defopt == @defvr {User Option} + +\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} + +\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{User Option}% +\defvarargs {#2}\endgroup % +} + +% @deftypevar int foobar + +\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} + +% #1 is the data type. #2 is the name, perhaps followed by text that +% is actually part of the data type, which should not be put into the index. +\def\deftypevarheader #1#2{% +\dovarind#2 \relax% Make entry in variables index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} +\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}} + +% @deftypevr {Global Flag} int enable + +\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} + +\def\deftypevrheader #1#2#3{\dovarind#3 \relax% +\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% This definition is run if you use @defvarx +% anywhere other than immediately after a @defvar or @defvarx. + +\def\defvrx #1 {\errmessage{@defvrx in invalid context}} +\def\defvarx #1 {\errmessage{@defvarx in invalid context}} +\def\defoptx #1 {\errmessage{@defoptx in invalid context}} +\def\deftypevarx #1 {\errmessage{@deftypevarx in invalid context}} +\def\deftypevrx #1 {\errmessage{@deftypevrx in invalid context}} + +% Now define @deftp +% Args are printed in bold, a slight difference from @defvar. + +\def\deftpargs #1{\bf \defvarargs{#1}} + +% @deftp Class window height width ... + +\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} + +\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% +\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} + +% This definition is run if you use @deftpx, etc +% anywhere other than immediately after a @deftp, etc. + +\def\deftpx #1 {\errmessage{@deftpx in invalid context}} + + +\message{cross reference,} +% Define cross-reference macros +\newwrite \auxfile + +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% @inforef is simple. +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +% \setref{foo} defines a cross-reference point named foo. + +\def\setref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ysectionnumberandtype}} + +\def\unnumbsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ynothing}} + +\def\appendixsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Yappendixletterandtype}} + +% \xref, \pxref, and \ref generate cross-references to specified points. +% 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 + \def\printedmanual{\ignorespaces #5}% + \def\printednodename{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual}% + \setbox0=\hbox{\printednodename}% + \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\printednodename{\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\printednodename{\ignorespaces #1}% + \else + \ifhavexrefs + % We know the real title if we have the xref values. + \def\printednodename{\refx{#1-title}{}}% + \else + % Otherwise just copy the Info node name. + \def\printednodename{\ignorespaces #1}% + \fi% + \fi + \fi + \fi + % + % 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{} ``\printednodename'' in \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 \refx{#1-snt}{}}% + \space [\printednodename],\space + \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \fi +\endgroup} + +% \dosetq is the interface for calls from other macros + +% Use \turnoffactive so that punctuation chars such as underscore +% work in node names. +\def\dosetq #1#2{{\let\folio=0 \turnoffactive +\edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% +\next}} + +% \internalsetq {foo}{page} expands into +% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} +% When the aux file is read, ' is the escape character + +\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} + +% Things to be expanded by \internalsetq + +\def\Ypagenumber{\folio} + +\def\Ytitle{\thissection} + +\def\Ynothing{} + +\def\Ysectionnumberandtype{% +\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % +\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\def\Yappendixletterandtype{% +\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% +\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\gdef\xreftie{'tie} + +% 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 % Non-3.0. +\else + \def\linenumber{\the\inputlineno:\space} +\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{% + \expandafter\ifx\csname X#1\endcsname\relax + % If not defined, say something at least. + \angleleft un\-de\-fined\angleright + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \else + % It's defined, so just use it. + \csname X#1\endcsname + \fi + #2% Output the suffix in any case. +} + +% This is the macro invoked by entries in the aux file. +% +\def\xrdef#1{\begingroup + % Reenable \ as an escape while reading the second argument. + \catcode`\\ = 0 + \afterassignment\endgroup + \expandafter\gdef\csname X#1\endcsname +} + +% Read the last existing aux file, if any. No error if none exists. +\def\readauxfile{\begingroup + \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 + \catcode`\@=\other + \catcode`\^=\other + % It was suggested to define this as 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 + \catcode`\[=\other + \catcode`\]=\other + \catcode`\"=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\$=\other + \catcode`\#=\other + \catcode`\&=\other + % `\+ does not work, so use 43. + \catcode43=\other + % Make the characters 128-255 be printing characters + {% + \count 1=128 + \def\loop{% + \catcode\count 1=\other + \advance\count 1 by 1 + \ifnum \count 1<256 \loop \fi + }% + }% + % The aux file uses ' as the escape (for now). + % Turn off \ as an escape so we do not lose on + % entries which were dumped with control sequences in their names. + % For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ + % Reference to such entries still does not work the way one would wish, + % but at least they do not bomb out when the aux file is read in. + \catcode`\{=1 + \catcode`\}=2 + \catcode`\%=\other + \catcode`\'=0 + \catcode`\\=\other + % + \openin 1 \jobname.aux + \ifeof 1 \else + \closein 1 + \input \jobname.aux + \global\havexrefstrue + \global\warnedobstrue + \fi + % Open the new aux file. TeX will close it automatically at exit. + \openout\auxfile=\jobname.aux +\endgroup} + + +% 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 + +\let\ptexfootnote=\footnote + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \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}\/\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \footnotezzz +}% + +% 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 fail inside footnotes because the tokens are fixed when +% the footnote is read. --karl, 16nov96. +% +\long\gdef\footnotezzz{\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. + \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 + % + % Hang the footnote text off the number. + \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 +} +\def\fo@t{\ifcat\bgroup\noexpand\next \let\next\f@@t + \else\let\next\f@t\fi \next} +\def\f@@t{\bgroup\aftergroup\@foot\let\next} +\def\f@t#1{#1\@foot} +\def\@foot{\strut\egroup} + +}%end \catcode `\@=11 + +% 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 + }% +} + +% @| 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 + }% + }% +} + +% 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} + +% @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 + \closein 1 + \def\epsfannounce{\toks0 = }% do not bother showing banner + \input epsf.tex +\fi +% +\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://ftp.tug.org/tex/epsf.tex.} +% +% Only complain once about lack of 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 just the usual extra ignored arg for parsing this stuff. +\def\imagexxx#1,#2,#3,#4\finish{% + % \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}% +} + +% End of control word definitions. + + +\message{and turning on texinfo input format.} + +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% Set some numeric style parameters, for 8.5 x 11 format. + +\hsize = 6in +\hoffset = .25in +\newdimen\defaultparindent \defaultparindent = 15pt +\parindent = \defaultparindent +\parskip 3pt plus 2pt minus 1pt +\setleading{13.2pt} +\advance\topskip by 1.2cm + +\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 + +% 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. This makes it come to about 9pt for the 8.5x11 format. +% +\ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% +\else + \emergencystretch = \hsize + \divide\emergencystretch by 45 +\fi + +% Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) +\def\smallbook{ + \global\chapheadingskip = 15pt plus 4pt minus 2pt + \global\secheadingskip = 12pt plus 3pt minus 2pt + \global\subsecheadingskip = 9pt plus 2pt minus 2pt + % + \global\lispnarrowing = 0.3in + \setleading{12pt} + \advance\topskip by -1cm + \global\parskip 2pt plus 1pt + \global\hsize = 5in + \global\vsize=7.5in + \global\tolerance=700 + \global\hfuzz=1pt + \global\contentsrightmargin=0pt + \global\deftypemargin=0pt + \global\defbodyindent=.5cm + % + \global\pagewidth=\hsize + \global\pageheight=\vsize + % + \global\let\smalllisp=\smalllispx + \global\let\smallexample=\smalllispx + \global\def\Esmallexample{\Esmalllisp} +} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{ +\global\tolerance=700 +\global\hfuzz=1pt +\setleading{12pt} +\global\parskip 15pt plus 1pt + +\global\vsize= 53\baselineskip +\advance\vsize by \topskip +%\global\hsize= 5.85in % A4 wide 10pt +\global\hsize= 6.5in +\global\outerhsize=\hsize +\global\advance\outerhsize by 0.5in +\global\outervsize=\vsize +\global\advance\outervsize by 0.6in + +\global\pagewidth=\hsize +\global\pageheight=\vsize +} + +\bindingoffset=0pt +\normaloffset=\hoffset +\pagewidth=\hsize +\pageheight=\vsize + +% Allow control of the text dimensions. Parameters in order: textheight; +% textwidth; voffset; hoffset; binding offset; topskip. +% All require a dimension; +% header is additional; added length extends the bottom of the page. + +\def\changepagesizes#1#2#3#4#5#6{ + \global\vsize= #1 + \global\topskip= #6 + \advance\vsize by \topskip + \global\voffset= #3 + \global\hsize= #2 + \global\outerhsize=\hsize + \global\advance\outerhsize by 0.5in + \global\outervsize=\vsize + \global\advance\outervsize by 0.6in + \global\pagewidth=\hsize + \global\pageheight=\vsize + \global\normaloffset= #4 + \global\bindingoffset= #5} + +% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin +% 29mm, hence bottom margin 28mm, nominal side margin 3cm. +\def\afourlatex + {\global\tolerance=700 + \global\hfuzz=1pt + \setleading{12pt} + \global\parskip 15pt plus 1pt + \advance\baselineskip by 1.6pt + \changepagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm} + } + +% Use @afourwide to print on European A4 paper in wide format. +\def\afourwide{\afourpaper +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}} + +% 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 +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} + +% This macro is used to make a character print one way in ttfont +% where it can probably just be output, 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\the\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 \char '042}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt \char '176}} +\chardef\hat=`\^ +\catcode`\^=\active +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +% Subroutine for the previous macro. +\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}} + +\catcode`\|=\active +\def|{{\tt \char '174}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +%\catcode 27=\active +%\def^^[{$\diamondsuit$} + +% Set up an active definition for =, but don't enable it most of the time. +{\catcode`\==\active +\global\def={{\tt \char 61}}} + +\catcode`+=\active +\catcode`\_=\active + +% 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 + +% \rawbackslashxx output one backslash character in current font +\global\chardef\rawbackslashxx=`\\ +%{\catcode`\\=\other +%@gdef@rawbackslashxx{\}} + +% \rawbackslash redefines \ as input to do \rawbackslashxx. +{\catcode`\\=\active +@gdef@rawbackslash{@let\=@rawbackslashxx }} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\rawbackslashxx}} + +% Say @foo, not \foo, in error messages. +\escapechar=`\@ + +% \catcode 17=0 % Define control-q +\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} + +@def@normalturnoffactive{@let"=@normaldoublequote +@let\=@normalbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +% 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 back turn 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} + +%% These look ok in all fonts, so just make them not special. The @rm below +%% makes sure that the current font starts out as the newly loaded cmr10 +@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other + +@textfonts +@rm + +@c Local variables: +@c page-delimiter: "^\\\\message" +@c End: diff --git a/contrib/texinfo/doc/texinfo.txi b/contrib/texinfo/doc/texinfo.txi new file mode 100644 index 0000000..c0b7a20 --- /dev/null +++ b/contrib/texinfo/doc/texinfo.txi @@ -0,0 +1,17280 @@ +\input texinfo.tex @c -*-texinfo-*- +@c $Id: texinfo.txi,v 1.50 1998/02/27 21:21:34 karl Exp $ +@c %**start of header + +@c All text is ignored before the setfilename. +@setfilename texinfo +@settitle Texinfo @value{edition} + +@c Edition number is now the same as the Texinfo distribution version number. +@set edition 3.12 +@set update-month February 1998 +@set update-date 27 @value{update-month} + +@c Define a new index for options. +@defcodeindex op +@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 + +@footnotestyle separate +@paragraphindent 2 +@finalout +@comment %**end of header + +@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a +@c prefix arg). This updates the node pointers, which texinfmt.el needs. + +@dircategory Texinfo documentation system +@direntry +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. Updating info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. +* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. +* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. +@end direntry + +@c 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 Currently undocumented command, 5 December 1993: +@c nwnode (Same as node, but no warnings; for `makeinfo'.) + +@ifinfo +This file documents Texinfo, a documentation system that can produce +both on-line information and a printed manual from a single source file. + +Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 +Free Software Foundation, Inc. + +This edition is for Texinfo version @value{edition}. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end ifinfo + +@setchapternewpage odd + +@shorttitlepage Texinfo + +@titlepage +@c use the new format for titles +@title Texinfo +@subtitle The GNU Documentation Format +@subtitle for Texinfo version @value{edition} +@subtitle @value{update-month} + +@author Robert J.@: Chassell +@author Richard M.@: Stallman + +@c Include the Distribution inside the titlepage so +@c that headings are turned off. + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98 +Free Software Foundation, Inc. + +Published by the Free Software Foundation @* +59 Temple Place Suite 330 @* +Boston, MA 02111-1307 @* +USA @* +ISBN 1-882114-65-5 +@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 +@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@sp 2 +Cover art by Etienne Suvasa. +@end titlepage + +@ifinfo +@node Top, Copying, (dir), (dir) +@top Texinfo + +Texinfo is a documentation system that uses a single source file to +produce both on-line information and printed output.@refill + +The first part of this master menu lists the major nodes in this Info +document, including the @@-command and concept indices. The rest of +the menu lists all the lower level nodes in the document.@refill + +This is Edition @value{edition} of the Texinfo documentation, +@w{@value{update-date}}. +@end ifinfo + +@c Here is a spare copy of the chapter menu entry descriptions, +@c in case they are accidently deleted +@ignore +Your rights. +Texinfo in brief. +How to use Texinfo mode. +What is at the beginning of a Texinfo file? +What is at the end of a Texinfo file? +How to create chapters, sections, subsections, + appendices, and other parts. +How to provide structure for a document. +How to write nodes. +How to write menus. +How to write cross references. +How to mark words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +How to write quotations, examples, etc. +How to write lists and tables. +How to create indices. +How to insert @@-signs, braces, etc. +How to indicate results of evaluation, + expansion of macros, errors, etc. +How to force and prevent line and page breaks. +How to describe functions and the like in a uniform manner. +How to write footnotes. +How to specify text for either @TeX{} or Info. +How to print hardcopy. +How to create an Info file. +How to install an Info file +A list of all the Texinfo @@-commands. +Hints on how to write a Texinfo document. +A sample Texinfo file to look at. +Tell readers they have the right to copy + and distribute. +How to incorporate other Texinfo files. +How to write page headings and footings. +How to find formatting mistakes. +All about paragraph refilling. +A description of @@-Command syntax. +Texinfo second edition features. +A menu containing commands and variables. +A menu covering many topics. +@end ignore + +@menu +* Copying:: Your rights. +* Overview:: Texinfo in brief. +* Texinfo Mode:: How to use 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:: How to create chapters, sections, subsections, + appendices, and other parts. +* Nodes:: How to write nodes. +* Menus:: How to write menus. +* Cross References:: How to write cross references. +* Marking Text:: How to mark words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +* Quotations and Examples:: How to write quotations, examples, etc. +* Lists and Tables:: How to write lists and tables. +* Indices:: How to create indices. +* Insertions:: How to insert @@-signs, braces, etc. +* Breaks:: How to force and prevent line and page breaks. +* Definition Commands:: How to describe functions and the like + in a uniform manner. +* Footnotes:: How to write footnotes. +* Conditionals:: How to specify text for either @TeX{} or Info. +* Macros:: Defining new Texinfo commands. +* Format/Print Hardcopy:: How to convert a Texinfo file to a file + for printing and how to print that file. +* Create an Info File:: Convert a Texinfo file into an Info file. +* Install an Info File:: Make an Info file accessible to users. +* Command List:: All the Texinfo @@-commands. +* Tips:: Hints on how to write a Texinfo document. +* Sample Texinfo File:: A sample Texinfo file to look at. +* Sample Permissions:: Tell readers they have the right to copy + and distribute. +* Include Files:: How to incorporate other Texinfo files. +* Headings:: How to write page headings and footings. +* Catching Mistakes:: How to find formatting mistakes. +* Refilling Paragraphs:: All about paragraph refilling. +* Command Syntax:: A description of @@-Command syntax. +* Obtaining TeX:: How to Obtain @TeX{}. +* 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 + +* Using Texinfo:: Create a conventional printed book + or an Info file. +* Info Files:: What is an Info file? +* Printed Books:: Characteristics of a printed book or manual. +* Formatting Commands:: @@-commands are used for formatting. +* Conventions:: General rules for writing a Texinfo file. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. +* Minimum:: What a Texinfo file must have. +* Six Parts:: Usually, a Texinfo file has six parts. +* Short Sample:: A short sample Texinfo file. +* Acknowledgements:: + +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 + +* Four Parts:: Four parts begin a Texinfo file. +* Sample Beginning:: Here is a sample beginning for a Texinfo file. +* Header:: The very beginning of a Texinfo file. +* Info Summary and Permissions:: Summary and copying permissions for Info. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* The Top Node:: Creating the `Top' node and master menu. +* Software Copying Permissions:: Ensure that you and others continue to + have the right to use and share software. + +The 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. +* setchapternewpage:: Start chapters on right-hand pages. +* paragraphindent:: An option to specify paragraph indentation. +* End of Header:: Formatting a region requires this. + +The 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 & Permissions:: 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 + +* Title of Top Node:: Sketch what the file is about. +* Master Menu Parts:: A master menu has three or more parts. + +Ending a Texinfo File + +* Printing Indices & Menus:: How to print an index in hardcopy and + generate index menus in Info. +* Contents:: How to create a table of contents. +* 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:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. + +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. +* Top Node Summary:: Write a brief description for readers. + +Menus + +* Menu Location:: Put a menu in a short node. +* 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:: How to indicate code. +* kbd:: How to show keyboard input. +* key:: How to specify keys. +* samp:: How to show a literal sequence of characters. +* var:: How to indicate a metasyntactic variable. +* file:: How to indicate the name of a file. +* dfn:: How to specify a definition. +* cite:: How to refer to a book that is not in Info. +* url:: How to indicate a world wide web reference. +* email:: How to indicate an electronic mail address. + +Emphasizing Text + +* emph & strong:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. + +Quotations and Examples + +* Block Enclosing Commands:: Use different constructs for + different purposes. +* quotation:: How to write a quotation. +* example:: How to write an example in a fixed-width font. +* noindent:: How to prevent paragraph indentation. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. +* display:: How to write an example in the current font. +* format:: How to write an example that does not narrow + the margins. +* exdent:: How to undo the indentation of a line. +* flushleft & flushright:: How to push text flushleft or flushright. +* cartouche:: How to draw cartouches around examples. + +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. + +Multi-column Tables + +* Multitable Column Widths:: Defining multitable column widths. +* Multitable Rows:: Defining multitable rows, with examples. + +Creating Indices + +* Index Entries:: Choose different words for index entries. +* Predefined Indices:: Use different indices for different kinds + of entry. +* 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 + +* Braces Atsigns:: How to insert braces, @samp{@@}. +* 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. +* 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. +* Images:: How to include graphics. + +Inserting @@ and Braces + +* Inserting An Atsign:: How to insert @samp{@@}. +* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. + +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, Dots, and Bullets + +* dots:: How to insert dots @dots{} +* bullet:: How to insert a bullet. + +Inserting @TeX{} and the Copyright Symbol + +* tex:: How to insert the @TeX{} logo. +* copyright symbol:: How to use @code{@@copyright}@{@}. + +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:: + +Making and Preventing Breaks + +* Break Commands:: Cause and prevent splits. +* Line Breaks:: How to force a single line to use two lines. +* - and hyphenation:: How to tell TeX about hyphenation points. +* w:: How to prevent unwanted line breaks. +* sp:: How to insert blank lines. +* page:: How to force the start of a new page. +* group:: How to prevent unwanted page breaks. +* need:: Another way to prevent unwanted page breaks. + +Definition Commands + +* Def Cmd Template:: How to structure a description using a + definition command. +* Optional Arguments:: How to handle optional and repeated arguments. +* deffnx:: How to group two or more `first' lines. +* Def Cmds in Detail:: All the definition commands. +* Def Cmd Conventions:: Conventions for writing definitions. +* Sample Function Definition:: + +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. +* Abstract Objects:: Commands for object-oriented programming. +* Data Types:: The definition command for data types. + +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. + +Conditionally Visible Text + +* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. +* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. +* Raw Formatter Commands:: Using raw @TeX{} or HTML commands. +* set clear value:: Designating which text to format (for + all output formats); and how to set a + flag to a string that you can insert. + +@code{@@set}, @code{@@clear}, and @code{@@value} + +* ifset ifclear:: Format a region if a flag is set. +* value:: Replace a flag with a string. +* value Example:: An easy way to update edition information. + +Macros: Defining New Texinfo Commands + +* Defining Macros:: Both defining and undefining new commands. +* Invoking Macros:: Using a macro, once you've defined it. + +Format and Print Hardcopy + +* Use TeX:: Use @TeX{} to format for hardcopy. +* Format with tex/texindex:: How to format in a shell. +* Format with texi2dvi:: A simpler way to use the shell. +* Print with lpr:: How to print. +* Within Emacs:: How to format and print from an Emacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using Emacs's compile command. +* Requirements Summary:: @TeX{} formatting requirements summary. +* Preparing for TeX:: What you need to do to use @TeX{}. +* Overfull hboxes:: What are and what to do with overfull hboxes. +* smallbook:: How to print small format books and manuals. +* A4 Paper:: How to print on European A4 paper. +* Cropmarks and Magnification:: How to print marks to indicate the size + of pages and how to print scaled up output. + +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. + +Sample Permissions + +* Inserting Permissions:: How to put permissions in your document. +* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. +* Titlepage Permissions:: Sample Titlepage copying permissions. + +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 File Requirements:: What @code{texinfo-multiple-files-update} expects. +* 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. + +How to Obtain @TeX{} + +* New Texinfo Mode Commands:: The updating commands are especially useful. +* New Commands:: Many newly described @@-commands. +@end detailmenu +@end menu + +@node Copying, Overview, Top, Top +@comment node-name, next, previous, up +@unnumbered Texinfo Copying Conditions +@cindex Copying conditions +@cindex Conditions for copying Texinfo + +The programs currently being distributed that relate to Texinfo include +portions of GNU Emacs, plus other separate programs (including +@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.@refill + + 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.@refill + + 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.@refill + + 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.@refill + + 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.@refill + +@node Overview, Texinfo Mode, Copying, Top +@comment node-name, next, previous, up +@chapter Overview of Texinfo +@cindex Overview of Texinfo +@cindex Texinfo overview + +@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is +pronounced like ``speck'', not ``hex''. This odd pronunciation is +derived from, but is not the same as, the pronunciation of @TeX{}. In +the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' +rather than the English letter ``ex''. Pronounce @TeX{} as if the +@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo +as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' +and write the other letters in lower case.} +is a documentation system that uses a single source file to produce both +on-line information and printed output. This means that instead of +writing two different documents, one for the on-line help or other on-line +information and the other for a typeset manual or other printed work, you +need write only one document. When the work is revised, you need revise +only one document. (You can read the on-line information, known as an +@dfn{Info file}, with an Info documentation-reading program.)@refill + +@menu +* Using Texinfo:: Create a conventional printed book + or an Info file. +* Info Files:: What is an Info file? +* Printed Books:: Characteristics of a printed book or manual. +* Formatting Commands:: @@-commands are used for formatting. +* Conventions:: General rules for writing a Texinfo file. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. +* Minimum:: What a Texinfo file must have. +* Six Parts:: Usually, a Texinfo file has six parts. +* Short Sample:: A short sample Texinfo file. +* Acknowledgements:: +@end menu + +@node Using Texinfo, Info Files, Overview, Overview +@ifinfo +@heading Using Texinfo +@end ifinfo + +Using Texinfo, you can create a printed document with the normal +features of a book, including chapters, sections, cross references, +and indices. From the same Texinfo source file, you can create a +menu-driven, on-line Info file with nodes, menus, cross references, +and indices. You can, if you wish, make the chapters and sections of +the printed document correspond to the nodes of the on-line +information; and you use the same cross references and indices for +both the Info file and the printed work. @cite{The GNU +Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill + +To make a printed document, you process a Texinfo source file with the +@TeX{} typesetting program. This creates a DVI file that you can +typeset and print as a book or report. (Note that the Texinfo language +is completely different from @TeX{}'s usual language, plain @TeX{}.) If +you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you +can use the @code{texi2roff} program instead.@refill + +To make an Info file, you process a Texinfo source file with the +@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; +this creates an Info file that you can install on-line.@refill + +@TeX{} and @code{texi2roff} work with many types of printers; similarly, +Info works with almost every type of computer terminal. This power +makes Texinfo a general purpose system, but brings with it a constraint, +which is that a Texinfo file may contain only the customary +``typewriter'' characters (letters, numbers, spaces, and punctuation +marks) but no special graphics.@refill + +A Texinfo file is a plain @sc{ascii} file containing text and +@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the +typesetting and formatting programs what to do. You may edit a +Texinfo file with any text editor; but it is especially convenient to +use GNU Emacs since that editor has a special mode, called Texinfo +mode, that provides various Texinfo-related features. (@xref{Texinfo +Mode}.)@refill + +Before writing a Texinfo source file, you should become familiar with +the Info documentation reading program and learn about nodes, +menus, cross references, and the rest. (@inforef{Top, info, info}, +for more information.)@refill + +You can use Texinfo to create both on-line help and printed manuals; +moreover, Texinfo is freely redistributable. For these reasons, Texinfo +is the format in which documentation for GNU utilities and libraries is +written.@refill + +@node Info Files, Printed Books, Using Texinfo, Overview +@comment node-name, next, previous, up +@section Info files +@cindex Info files + +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.)@refill + +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.@refill + +@ifinfo +@inforef{Top, info, info}, for more information about using Info.@refill +@end ifinfo + +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.@refill + +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.}@refill + +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{Expert, +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 + +@node Printed Books, Formatting Commands, Info Files, Overview +@comment node-name, next, previous, up +@section Printed Books +@cindex Printed book and manual characteristics +@cindex Manual characteristics, printed +@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 +@code{texi2roff} program if you do not have @TeX{}; since Texinfo is +designed for use with @TeX{}, @code{texi2roff} is not described here. +@code{texi2roff} is not part of the standard GNU distribution.} + +A Texinfo-based book is similar to any other typeset, printed work: it +can have a title page, copyright page, table of contents, and preface, +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 on-line information. You can use Texinfo for +writing a printed novel, and even to write a printed memo, although +this latter application is not recommended since electronic mail is so +much easier.@refill + +@TeX{} is a general purpose typesetting program. Texinfo provides a +file called @file{texinfo.tex} that contains information (definitions or +@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. +(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands +to @TeX{} commands, which @TeX{} can then process to create the typeset +document.) @file{texinfo.tex} contains the specifications for printing +a document.@refill + +Most often, documents are printed on 8.5 inch by 11 inch +pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you +can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by +235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper +(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}. +Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill + +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.@refill + +@TeX{} is freely distributable. It is written in a superset of Pascal +called WEB and can be compiled either in Pascal or (by using a +conversion program that comes with the @TeX{} distribution) in C. +(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information +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.@refill + +@xref{Obtaining TeX, , How to Obtain @TeX{}}. + + +@node Formatting Commands, Conventions, Printed Books, Overview +@comment node-name, next, previous, up +@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 +@strong{Please note:} All the @@-commands, with the exception of the +@code{@@TeX@{@}} command, must be written entirely in lower +case.@refill +@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 disputation between two people; it refers to the +information presented to the command. According to the @cite{Oxford +English Dictionary}, the word derives from the Latin for @dfn{to make +clear, prove}; thus it came to mean `the evidence offered as proof', +which is to say, `the information offered', which led to its +mathematical meaning. In its other thread of derivation, the word +came to mean `to assert in a manner against which others may make +counter assertions', which led to the meaning of `argument' as a +disputation.} they take, you need to write @@-commands on lines of +their own or as part of sentences:@refill + +@itemize @bullet +@item +Write a command such as @code{@@noindent} at the beginning of a line as +the only text on the line. (@code{@@noindent} prevents the beginning of +the next line from being indented as the beginning of a +paragraph.)@refill + +@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} at the beginning of a line of +its own; write the body-text on following lines; and write the matching +@code{@@end} command, @code{@@end example} in this case, at the +beginning of a line of its own after the body-text. (@code{@@example} +@dots{} @code{@@end example} indents and typesets body-text as an +example.)@refill +@end itemize + +@noindent +@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 +make it easier to write and read Texinfo files than if all commands +followed exactly the same syntax. (For details about @@-command +syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill + +@node Conventions, Comments, Formatting Commands, Overview +@comment node-name, next, previous, up +@section General Syntactic Conventions +@cindex General syntactic conventions +@cindex Syntactic conventions +@cindex Conventions, syntactic + +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. +@samp{@{} and @samp{@}} should be used only 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{@@@}}.@refill + +@ifinfo +It is customary in @TeX{} to use doubled single-quote characters to +begin and end quotations: ` ` and ' ' (but without a space between the +two single-quote characters). This convention should be followed in +Texinfo files. @TeX{} converts doubled single-quote characters to +left- and right-hand doubled quotation marks and Info converts doubled +single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill +@end ifinfo +@iftex +It is customary in @TeX{} to use doubled single-quote characters to +begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This +convention should be followed in Texinfo files. @TeX{} converts +doubled single-quote characters to left- and right-hand doubled +quotation marks, ``like this'', and Info converts doubled single-quote +characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and +@w{@tt{ '' }} to @w{@tt{ " }}.@refill +@end iftex + +Use three hyphens in a row, @samp{---}, for a dash---like this. In +@TeX{}, a single or double hyphen produces a printed dash that is +shorter than the usual typeset dash. Info reduces three hyphens to two +for display on the screen. + +To prevent a paragraph from being indented in the printed manual, put +the command @code{@@noindent} on a line by itself before the +paragraph.@refill + +If you mark off a region of the Texinfo file with the @code{@@iftex} +and @w{@code{@@end iftex}} commands, that region will appear only in +the printed copy; in that region, you can use certain commands +borrowed from plain @TeX{} that you cannot use in Info. Likewise, if +you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo} +commands, that region will appear only in the Info file; in that +region, you can use Info commands that you cannot use in @TeX{}. +Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, +@code{@@ifnothtml @dots{} @@end ifnothtml}, +@code{@@ifnotinfo @dots{} @@end ifnotinfo}, +@code{@@ifnottex @dots{} @@end ifnottex}, +@xref{Conditionals}. + +@cindex Tabs; don't use! +@quotation +@strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses +variable-width fonts, which means that it cannot predefine a tab to work +in all circumstances. Consequently, @TeX{} treats tabs like single +spaces, and that is not what they look like. Furthermore, +@code{makeinfo} does nothing special with tabs, and thus a tab character +in your input file may 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.@refill + +@noindent +Also, you can run @code{untabify} in Emacs to convert tabs in a region +to multiple spaces.@refill + +@noindent +Don't use tabs. +@end quotation + +@node Comments, Minimum, Conventions, Overview +@comment node-name, next, previous, up +@section Comments + +You can write comments in a Texinfo file that will not appear in +either the Info file or the printed manual by using the +@code{@@comment} command (which may be abbreviated to @code{@@c}). +Such comments are for the person who reads the Texinfo file. All the +text on a line that follows either @code{@@comment} or @code{@@c} is a +comment; the rest of the line does not appear in either the Info file +or the printed manual. (Often, you can write the @code{@@comment} or +@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.)@refill +@cindex Comments +@findex comment +@findex c @r{(comment)} + +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. Often, @code{@@ignore} and @code{@@end ignore} is used +to enclose a part of the copying permissions that applies to the +Texinfo source file of a document, but not to the Info or printed +version of the document.@refill +@cindex Ignored text +@cindex Unprocessed text +@findex ignore +@c !!! Perhaps include this comment about ignore and ifset: +@ignore +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 +will still get error messages if you have invalid Texinfo markup +within ignored text. +@end ignore + +@node Minimum, Six Parts, Comments, Overview +@comment node-name, next, previous, up +@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 names of Texinfo files end with one of the +extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer +extension is preferred since it describes more clearly to a human +reader the nature of the file. The shorter extensions are for +operating systems that cannot handle long file names.@refill + +In order to be made into a printed manual and an Info file, a Texinfo +file @strong{must} begin with lines like this:@refill + +@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:@refill + +@example +@@bye +@end example + +@findex input @r{(@TeX{} command)} +@noindent +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{}.) The +@samp{@@setfilename} line provides a name for the Info file and tells +@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a +title for the page headers (or footers) of the printed manual.@refill + +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.@refill + +Usually, you will not use quite such a spare format, but will include +mode setting and start-of-header and end-of-header lines at the +beginning of a Texinfo file, like this:@refill + +@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 @samp{@@setfilename} and +@samp{@@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}, +for more information.)@refill + +Furthermore, you will usually provide a Texinfo file with a title +page, indices, and the like. But the minimum, which can be useful +for short documents, is just the three lines at the beginning and the +one line at the end.@refill + +@node Six Parts, Short Sample, Minimum, Overview +@comment node-name, next, previous, up +@section Six Parts of a Texinfo File + +Generally, a Texinfo file contains more than the minimal +beginning and end---it usually contains six parts:@refill + +@table @r +@item 1. Header +The @dfn{Header} names the file, tells @TeX{} which definitions' file to +use, and performs other ``housekeeping'' tasks.@refill + +@item 2. Summary Description and Copyright +The @dfn{Summary Description and Copyright} segment describes the document +and contains the copyright notice and copying permissions for the Info +file. The segment must be enclosed between @code{@@ifinfo} and +@code{@@end ifinfo} commands so that the formatters place it only in the Info +file.@refill + +@item 3. Title and Copyright +The @dfn{Title and Copyright} segment contains the title and copyright pages +and copying permissions 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 @w{manual}.@refill + +@item 4. `Top' Node and Master Menu +The @dfn{Master Menu} contains a complete menu of all the nodes in the whole +Info file. It appears only in the Info file, in the `Top' node.@refill + +@item 5. Body +The @dfn{Body} of the document may be structured like a traditional book or +encyclopedia or it may be free form.@refill + +@item 6. End +The @dfn{End} contains commands for printing indices and generating +the table of contents, and the @code{@@bye} command on a line of its +own.@refill +@end table + +@node Short Sample, Acknowledgements, Six Parts, Overview +@comment node-name, next, previous, up +@section A Short Sample Texinfo File +@cindex Sample Texinfo file + +Here is a complete but very short Texinfo file, in six parts. 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 you write a manual, simply +insert the names for your own manual in this segment. (@xref{Beginning a +File}.)@refill + +@noindent +In the following, the sample text is @emph{indented}; comments on it are +not. The complete file, without any comments, is shown in +@ref{Sample Texinfo File}. + +@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 Document +@@c %**end of header + +@@setchapternewpage odd +@end group +@end example + +@subheading Part 2: Summary Description and Copyright + +@noindent +The summary description and copyright segment does not +appear in the printed document. + +@example +@group +@@ifinfo +This is a short example of a complete Texinfo file. + +Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +@@end ifinfo +@end group +@end example + +@subheading Part 3: Titlepage and Copyright + +@noindent +The titlepage segment does not appear in the Info file. + +@example +@group +@@titlepage +@@sp 10 +@@comment The title is printed in a large font. +@@center @@titlefont@{Sample Title@} +@end group + +@group +@@c The following two commands start the copyright page. +@@page +@@vskip 0pt plus 1filll +Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +@@end titlepage +@end group +@end example + +@subheading Part 4: `Top' Node and Master Menu + +@noindent +The `Top' node contains the master menu for the Info file. +Since a printed manual uses a table of contents rather than +a menu, the master menu appears only in the Info file. + +@example +@group +@@node Top, First Chapter, , (dir) +@@comment node-name, next, previous, up +@end group +@end example + +@example +@group +@@menu +* First Chapter:: The first chapter is the + only chapter in this sample. +* Concept Index:: This index has two entries. +@@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.@refill + +@example +@group +@@node First Chapter, Concept Index, Top, Top +@@comment node-name, next, previous, up +@@chapter First Chapter +@@cindex Sample index entry +@end group + +@group +This is the contents of the first chapter. +@@cindex Another sample index entry +@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 + +@group +The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} +commands transform a Texinfo file such as this into +an Info file; and @@TeX@{@} typesets it for a printed +manual. +@end group +@end example + +@subheading Part 6: The End of the Document + +@noindent +The end segment contains commands both for generating an index in a node +and unnumbered chapter of its own and for generating the table of +contents; and it contains the @code{@@bye} command that marks the end of +the document.@refill + +@example +@group +@@node Concept Index, , First Chapter, Top +@@comment node-name, next, previous, up +@@unnumbered Concept Index +@end group + +@group +@@printindex cp + +@@contents +@@bye +@end group +@end example + +@subheading The Results + +Here is what the contents of the first chapter of the sample look like: + +@sp 1 +@need 700 +@quotation +This is the contents of the first chapter. + +Here is a numbered list. + +@enumerate +@item +This is the first item. + +@item +This is the second item. +@end enumerate + +The @code{makeinfo} and @code{texinfo-format-buffer} +commands transform a Texinfo file such as this into +an Info file; and @TeX{} typesets it for a printed +manual. +@end quotation + +@node Acknowledgements, , Short Sample, Overview +@comment node-name, next, previous, up +@section Acknowledgements + +@cindex Stallman, Richard M. +@cindex Chassell, Robert J. +@cindex Berry, Karl +Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@: +Chassell} revised and extended it, starting with Edition 1.1. Karl +Berry made updates for the Texinfo 3.8 and subsequent releases, starting +with Edition 2.22. + +@cindex Pinard, Fran@,{c}ois +@cindex Zuhn, David D. +@cindex Weisshaus, Melissa +Our thanks go out to all who helped improve this work, particularly to +Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and +reported mistakes and obscurities; our special thanks go to Melissa +Weisshaus for her frequent and often tedious reviews of nearly similar +editions. Our mistakes are our own. + +Please send suggestions and corrections to: + +@example +@group +@r{Internet address:} + bug-texinfo@@gnu.org +@end group +@end example + +@noindent +Please include the manual's edition number and update date in your messages. + +@node Texinfo Mode, Beginning a File, Overview, Top +@comment node-name, next, previous, up +@chapter Using Texinfo Mode +@cindex Texinfo mode +@cindex Mode, using Texinfo +@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.@refill + +This chapter describes features of GNU Emacs' Texinfo mode but not any +features of the Texinfo formatting language. 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.@refill + +@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, Emacs Editing, Texinfo Mode, Texinfo Mode +@ifinfo +@heading Texinfo Mode Overview +@end ifinfo + +Texinfo mode provides special features for working with Texinfo +files:@refill + +@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, Inserting, Texinfo Mode Overview, Texinfo Mode +@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 three extensions +@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is +preferred, since it is explicit, but a shorter extension may be +necessary for operating systems that limit the length of file names. +GNU Emacs automatically enters Texinfo mode when you visit a file with +a @file{.texinfo} or @file{.texi} +extension. Also, Emacs switches to Texinfo mode +when you visit a +file that has @samp{-*-texinfo-*-} in its first line. If ever you are +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, Showing the Structure, Emacs Editing, Texinfo Mode +@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, Updating Nodes and Menus, Inserting, Texinfo Mode +@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. (This is how the +@code{texinfo-show-structure} command worked without an argument in +the first version of Texinfo. It was changed because @code{@@node} +lines clutter up the @samp{*Occur*} buffer and are usually not +needed.) You can use @code{texinfo-show-structure} with a prefix +argument to check whether the `Next', `Previous', and `Up' pointers of +an @code{@@node} line are correct.@refill + +Often, when you are working on a manual, you will be interested only +in the structure of the current chapter. In this case, you can mark +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, Info Formatting, Showing the Structure, Texinfo Mode +@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.@refill + +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, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus +@ifinfo +@subheading The Updating Commands +@end ifinfo + +You can use the updating commands@refill + +@itemize @bullet +@item +to insert or update the `Next', `Previous', and `Up' pointers of a +node,@refill + +@item +to insert or update the menu for a section, and@refill + +@item +to create a master menu for a Texinfo source file.@refill +@end itemize + +You can also use the commands to update all the nodes and menus in a +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. +Note that the menu updating commands will not create a main or master +menu for a Texinfo file that has only @code{@@chapter}-level nodes! The +menu updating commands only create menus @emph{within} nodes for lower level +nodes. To create a menu of chapters, you must provide a `Top' +node.@refill + +The menu updating commands remove menu entries that refer to other Info +files since they do not refer to nodes within the current buffer. This +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 with the @kbd{M-x edit-options} command +(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs +Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, +, Examining and Setting Variables, emacs, The GNU Emacs +Manual}).@refill + +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, Other Updating Commands, Updating Commands, Updating Nodes and Menus +@comment node-name, next, previous, up +@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:@refill + +@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 + +@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 can write an @code{@@ifinfo} line.)@refill + +If a file has a `Top' node, it must be called @samp{top} or @samp{Top} +and be the first node in the file.@refill + +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{Create an Info File, , Creating an +Info File}, for more information about @code{makeinfo}.) However, +both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands +require that you insert menus in the file.@refill + +@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus +@comment node-name, next, previous, up +@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 + +(Note that this command inserts titles as node names in @code{@@node} +lines; the @code{texinfo-start-menu-description} command +(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles +as descriptions in menu entries, a different action. However, in both +cases, you need to edit the inserted text.)@refill + +@item M-x texinfo-multiple-files-update +@findex texinfo-multiple-files-update @r{(in brief)} +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. +@ifinfo +@xref{texinfo-multiple-files-update}.@refill +@end ifinfo +@iftex +@xref{texinfo-multiple-files-update, , +@code{texinfo-multiple-files-update}}.@refill +@end iftex + +@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, Printing, Updating Nodes and Menus, Texinfo Mode +@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.@refill + +@xref{Create an Info File}, for details about Info formatting.@refill + +@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode +@comment node-name, next, previous, up +@section Formatting and 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{Format/Print Hardcopy}, for a description of the other @TeX{} related +commands, such as @code{tex-show-print-queue}.@refill + +@node Texinfo Mode Summary, , Printing, Texinfo Mode +@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 + +@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 `other 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, Ending a File, Texinfo Mode, Top +@comment node-name, next, previous, up +@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 of the file and the title of the +document.@refill + +@menu +* Four Parts:: Four parts begin a Texinfo file. +* Sample Beginning:: Here is a sample beginning for a Texinfo file. +* Header:: The very beginning of a Texinfo file. +* Info Summary and Permissions:: Summary and copying permissions for Info. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* The Top Node:: Creating the `Top' node and master menu. +* Software Copying Permissions:: Ensure that you and others continue to + have the right to use and share software. +@end menu + +@node Four Parts, Sample Beginning, Beginning a File, Beginning a File +@ifinfo +@heading Four Parts Begin a File +@end ifinfo + +Generally, the beginning of a Texinfo file has four parts:@refill + +@enumerate +@item +The header, delimited by special comment lines, that includes the +commands for naming the Texinfo file and telling @TeX{} what +definitions file to use when processing the Texinfo file.@refill + +@item +A short statement of what the file is about, with a copyright notice +and copying permissions. This is enclosed in @code{@@ifinfo} and +@code{@@end ifinfo} commands so that the formatters place it only +in the Info file.@refill + +@item +A title page and copyright page, with a copyright notice and copying +permissions. This is enclosed between @code{@@titlepage} and +@code{@@end titlepage} commands. The title and copyright page appear +only in the printed @w{manual}.@refill + +@item +The `Top' node that contains a menu for the whole Info file. The +contents of this node appear only in the Info file.@refill +@end enumerate + +Also, optionally, you may include the copying conditions for a program +and a warranty disclaimer. The copying section will be followed by an +introduction or else by the first chapter of the manual.@refill + +Since the copyright notice and copying permissions for the Texinfo +document (in contrast to the copying permissions for a program) are in +parts that appear only in the Info file or only in the printed manual, +this information must be given twice.@refill + +@node Sample Beginning, Header, Four Parts, Beginning a File +@comment node-name, next, previous, up +@section Sample Texinfo File Beginning + +The following sample shows what is needed.@refill + +@example +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename @var{name-of-info-file} +@@settitle @var{name-of-manual} +@@setchapternewpage odd +@@c %**end of header + +@@ifinfo +This file documents @dots{} + +Copyright @var{year} @var{copyright-owner} + +@group +Permission is granted to @dots{} +@@end ifinfo +@end group + +@group +@@c This title page illustrates only one of the +@@c two methods of forming a title page. +@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 +Copyright @@copyright@{@} @var{year} @var{copyright-owner} +@end group + +Published by @dots{} + +Permission is granted to @dots{} +@@end titlepage + +@@node Top, Overview, , (dir) + +@@ifinfo +This document describes @dots{} + +This document applies to version @dots{} +of the program named @dots{} +@@end ifinfo + +@group +@@menu +* Copying:: Your rights and freedoms. +* First Chapter:: Getting started @dots{} +* Second Chapter:: @dots{} + @dots{} + @dots{} +@@end menu +@end group + +@group +@@node First Chapter, Second Chapter, top, top +@@comment node-name, next, previous, up +@@chapter First Chapter +@@cindex Index entry for First Chapter +@end group +@end example + +@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File +@comment node-name, next, previous, up +@section The 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. If you want to run @TeX{} on just a part +of the Texinfo File, you must write the @code{@@settitle} +and @code{@@setfilename} lines between start-of-header and end-of-header +lines.@refill + +Thus, the beginning of a Texinfo file looks like this: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@setfilename sample.info +@@settitle Sample Document +@end group +@end example + +@noindent +or else like this: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename sample.info +@@settitle Sample Document +@@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. +* setchapternewpage:: Start chapters on right-hand pages. +* paragraphindent:: An option to specify paragraph indentation. +* End of Header:: Formatting a region requires this. +@end menu + +@node First Line, Start of Header, Header, Header +@comment node-name, next, previous, up +@subsection The First Line of a Texinfo File +@cindex First line of a Texinfo file +@cindex Beginning line of a Texinfo file +@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:@refill + +@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 is usually located +in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash, +@samp{\}, to mark the beginning of a command, just 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.@refill + +@item +When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode +specification tells Emacs to use Texinfo mode.@refill +@end enumerate + +@node Start of Header, setfilename, First Line, Header +@comment node-name, next, previous, up +@subsection Start of Header +@cindex Start of header line + +Write a 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 command lines, such +as @code{@@smallbook} or @code{@@footnotestyle}; and then by an +end-of-header line (@pxref{End of Header}).@refill + +With these lines, you can format part of a Texinfo file for Info or +typeset part for printing.@refill + +A start-of-header line looks like this:@refill + +@example +@@c %**start of header +@end example + +The odd string of characters, @samp{%**}, is to ensure that no other +comment is accidentally taken for a start-of-header line.@refill + +@node setfilename, settitle, Start of Header, Header +@comment node-name, next, previous, up +@subsection @code{@@setfilename} +@cindex Info file requires @code{@@setfilename} +@findex 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. + +The @code{@@setfilename} line specifies the name of the Info file to be +generated. This name should be different from the name of the Texinfo +file. There are two conventions for choosing the name: you can either +remove the @samp{.texi} extension from the input file name, or replace +it with the @samp{.info} extension. + +Some operating systems cannot handle long file names. You can run into +a problem even when the file name you specify is itself short enough. +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, , Tag Files and Split Files}.) +The subfile name @file{texinfo.info-10}, for example, is too long for +some systems; so the Info file name for this document is @file{texinfo} +rather than @file{texinfo.info}. + +@cindex Ignored before @code{@@setfilename} +The Info formatting commands ignore everything written before the +@code{@@setfilename} line, which is why the very first line of +the file (the @code{\input} line) does not show up in the output. + +@pindex texinfo.cnf +The @code{@@setfilename} line produces no output when you typeset a +manual with @TeX{}, but it nevertheless is essential: it opens the +index, cross-reference, and other auxiliary files used by Texinfo, and +also reads @file{texinfo.cnf} if that file is present on your system +(@pxref{Preparing for TeX,, Preparing to Use @TeX{}}). + + +@node settitle, setchapternewpage, setfilename, Header +@comment node-name, next, previous, up +@subsection @code{@@settitle} +@findex settitle + +In order to be made into a printed manual, a Texinfo file must contain +a line that looks like this:@refill + +@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 a comment.@refill + +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.) Page footers are not +printed.@refill + +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. @refill + +The @code{@@settitle} command should precede everything that generates +actual output in @TeX{}.@refill + +Although the title in the @code{@@settitle} command is usually the +same as the title on the title page, it does not affect the title as +it appears on the title page. Thus, the two do not need not match +exactly; and the title in the @code{@@settitle} command can be a +shortened or expanded version of the title as it appears on the title +page. (@xref{titlepage, , @code{@@titlepage}}.)@refill + +@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.)@refill + +You may, if you wish, create your own, customized headings and +footings. @xref{Headings, , Page Headings}, for a detailed discussion +of this process.@refill + +@node setchapternewpage, paragraphindent, settitle, Header +@comment node-name, next, previous, up +@subsection @code{@@setchapternewpage} +@cindex Starting chapters +@cindex Pages, starting odd +@findex setchapternewpage + +In a book or a manual, text is usually printed on both sides of the +paper, chapters start on right-hand pages, and right-hand pages have +odd numbers. But in short reports, text often is printed only on one +side of the paper. Also in short reports, chapters sometimes do not +start on new pages, but are printed on the same page as the end of the +preceding chapter, after a small amount of vertical whitespace.@refill + +You can use the @code{@@setchapternewpage} command with various +arguments to specify how @TeX{} should start chapters and whether it +should typeset pages for printing on one or both sides of the paper +(single-sided or double-sided printing).@refill + +Write the @code{@@setchapternewpage} command at the beginning of a +line followed by its argument.@refill + +For example, you would write the following to cause each chapter to +start on a fresh odd-numbered page:@refill + +@example +@@setchapternewpage odd +@end example + +You can specify one of three alternatives with the +@code{@@setchapternewpage} command:@refill + +@table @asis +@ignore +@item No @code{@@setchapternewpage} command +If the Texinfo file does not contain an @code{@@setchapternewpage} +command before the @code{@@titlepage} command, @TeX{} automatically +begins chapters on new pages and prints headings in the standard +format for single-sided printing. This is the conventional format for +single-sided printing.@refill + +The result is exactly the same as when you write +@code{@@setchapternewpage on}.@refill +@end ignore +@item @code{@@setchapternewpage off} +Cause @TeX{} to typeset a new chapter on the same page as the last +chapter, after skipping some vertical whitespace. Also, cause @TeX{} to +format page headers 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 on} +Cause @TeX{} to start new chapters on new pages and to typeset page +headers for single-sided printing. This is the form most often +used for short reports.@refill + +This alternative is the default.@refill + +@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.@refill +@end table + +@noindent +Texinfo does not have an @code{@@setchapternewpage even} command.@refill + +@noindent +(You can countermand or modify an @code{@@setchapternewpage} command +with an @code{@@headings} command. @xref{headings on off, , The +@code{@@headings} Command}.)@refill + +At the beginning of a manual or book, pages are not numbered---for +example, the title and copyright pages of a book are not numbered. +By convention, table of contents pages are numbered with roman +numerals and not in sequence with the rest of the document.@refill + +Since an Info file does not have pages, the @code{@@setchapternewpage} +command has no effect on it.@refill + +Usually, you do not write an @code{@@setchapternewpage} command for +single-sided printing, but accept the default which is to typeset for +single-sided printing and to start new chapters on new pages. Usually, +you write an @code{@@setchapternewpage odd} command for double-sided +printing.@refill + +@node paragraphindent, End of Header, setchapternewpage, Header +@comment node-name, next, previous, up +@subsection Paragraph Indenting +@cindex Indenting paragraphs +@cindex Paragraph indentation +@findex paragraphindent + +The Info formatting commands may insert spaces at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You +can use the @code{@@paragraphindent} command to specify the +indentation. Write an @code{@@paragraphindent} command at the +beginning of a line followed by either @samp{asis} or a number. The +template is:@refill + +@example +@@paragraphindent @var{indent} +@end example + +The Info formatting commands indent according to the value of +@var{indent}:@refill + +@itemize @bullet +@item +If the value of @var{indent} is @samp{asis}, the Info formatting +commands do not change the existing indentation.@refill + +@item +If the value of @var{indent} is zero, the Info formatting commands delete +existing indentation.@refill + +@item +If the value of @var{indent} is greater than zero, the Info formatting +commands indent the paragraph by that number of spaces.@refill +@end itemize + +The default value of @var{indent} is @samp{asis}.@refill + +Write the @code{@@paragraphindent} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you write +the command between the start-of-header and end-of-header lines, the +region formatting commands indent paragraphs as specified.)@refill + +A peculiarity of the @code{texinfo-format-buffer} and +@code{texinfo-format-region} commands is that they do not indent (nor +fill) paragraphs that contain @code{@@w} or @code{@@*} commands. +@xref{Refilling Paragraphs}, for a detailed description of what goes +on.@refill + +@node End of Header, , paragraphindent, Header +@comment node-name, next, previous, up +@subsection End of Header +@cindex End of header line + +Follow the header lines with an @w{end-of-header} line. +An end-of-header line looks like this:@refill + +@example +@@c %**end of header +@end example + +If you include the @code{@@setchapternewpage} command between the +start-of-header and end-of-header lines, @TeX{} will typeset a region as +that command specifies. Similarly, if you include an @code{@@smallbook} +command between the start-of-header and end-of-header lines, @TeX{} will +typeset a region in the ``small'' book format.@refill + +@ifinfo +The reason for the odd string of characters (@samp{%**}) is so that the +@code{texinfo-tex-region} command does not accidentally find +something that it should not when it is looking for the header.@refill + +The start-of-header line and the end-of-header line are Texinfo mode +variables that you can change.@refill +@end ifinfo + +@iftex +@xref{Start of Header}. +@end iftex + +@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File +@comment node-name, next, previous, up +@section Summary and Copying Permissions for Info + +The title page and the copyright page appear only in the printed copy of +the manual; therefore, the same information must be inserted in a +section that appears only in the Info file. This section usually +contains a brief description of the contents of the Info file, a +copyright notice, and copying permissions.@refill + +The copyright notice should read:@refill + +@example +Copyright @var{year} @var{copyright-owner} +@end example + +@noindent +and be put on a line by itself.@refill + +Standard text for the copyright permissions is contained in an appendix +to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying +Permissions}, for the complete text.@refill + +The permissions text appears in an Info file @emph{before} the first +node. This mean that a reader does @emph{not} see this text when +reading the file using Info, except when using the advanced Info command +@kbd{g *}. + +@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File +@comment node-name, next, previous, up +@section The Title and Copyright Pages + +A manual's name and author are usually printed on a title page. +Sometimes copyright information is printed on the title page as well; +more often, copyright information is 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 will appear in the printed manual.@refill + +@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the +standard text for the copyright permissions.@refill + +@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 & Permissions:: 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, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page +@comment node-name, next, previous, up +@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.@refill + +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. By using the +@code{@@page} command you can force a page break within the region +delineated by the @code{@@titlepage} and @code{@@end titlepage} +commands and thereby create more than one unnumbered page. This is +how the copyright page is produced. (The @code{@@titlepage} command +might perhaps have been better named the +@code{@@titleandadditionalpages} command, but that would have been +rather long!)@refill + +@c !!! append refill to footnote when makeinfo can handle it. +When you write a manual about a computer program, you should write the +version of the program to which the manual applies on the title +page. If the manual changes more frequently than the program or is +independent of it, you should also include an edition +number@footnote{We have found that it is helpful to refer to versions +of manuals as `editions' and versions of programs as `versions'; +otherwise, we find we are liable to confuse each other in conversation +by referring to both the documentation and the software with the same +words.} for the manual. This helps readers keep track of which manual +is for which version of the program. (The `Top' node +should also contain this information; see @ref{makeinfo top, , +@code{@@top}}.)@refill + +Texinfo provides two main methods for creating a title page. One method +uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands +to generate a title page in which the words on the page are +centered.@refill + +The second method uses the @code{@@title}, @code{@@subtitle}, and +@code{@@author} commands to create a title page with black rules under +the title and author lines and the subtitle text set flush to the +right hand side of the page. With this method, you do not specify any +of the actual formatting of the title page. You specify the text +you want, and Texinfo does the formatting. You may use either +method.@refill + +@findex shorttitlepage +For extremely simple applications, Texinfo also provides a command +@code{@@shorttitlepage} which takes a single argument as the title. +The argument is typeset on a page by itself and followed by a blank +page. + + +@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page +@comment node-name, next, previous, up +@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} +@findex titlefont +@findex center +@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.)@refill + +Use the @code{@@titlefont} command to select a large font suitable for +the title itself.@refill + +@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,@refill + +@example +@@center @@titlefont@{Texinfo@} +@end example + +@noindent +centers the title, which in this example is ``Texinfo'' printed +in the title font.@refill + +Use the @code{@@sp} command to insert vertical space. For example:@refill + +@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.)@refill + +A template for this method looks like this:@refill + +@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 1/2 by 11 inch manual.@refill + +@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page +@comment node-name, next, previous, up +@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} +@findex title +@findex subtitle +@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.@refill + +Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} +commands at the beginning of a line followed by the title, subtitle, +or author.@refill + +The @code{@@title} command produces a line in which the title is set +flush to the left-hand side of the page in a larger than normal font. +The title is underlined with a black rule.@refill + +The @code{@@subtitle} command sets subtitles in a normal-sized font +flush to the right-hand side of the page.@refill + +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.)@refill + +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:@refill + +@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:@refill + +@example +@group +@@author Jane Smith +@@author John Doe +@end group +@end example + +@noindent +(Only the bottom name is underlined with a black rule.)@refill + +@need 950 +A template for this method looks like this:@refill + +@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 + +@ifinfo +@noindent +Contrast this form with the form of a title page written using the +@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill + +@example +@@titlepage +@@sp 10 +@@center @@titlefont@{Name of Manual When Printed@} +@@sp 2 +@@center Subtitle, If Any +@@sp 1 +@@center Second subtitle +@@sp 2 +@@center Author +@@page +@dots{} +@@end titlepage +@end example +@end ifinfo + +@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page +@comment node-name, next, previous, up +@subsection Copyright Page and Permissions +@cindex Copyright page +@cindex Printed permissions +@cindex Permissions, printed + +By international treaty, the copyright notice for a book should be +either on the title page or on the back of the title page. The +copyright notice should include the year followed by the name of the +organization or person who owns the copyright.@refill + +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.@refill + +@findex vskip +@findex filll +@cindex Vertical whitespace (@samp{vskip}) +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, you can write a somewhat mysterious line after the +@code{@@page} command that reads like this:@refill + +@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 the correct usage in +@TeX{}.@refill + +@findex copyright +In a printed manual, the @code{@@copyright@{@}} command generates a +@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The +copyright notice itself has the following legally defined sequence:@refill + +@example +Copyright @copyright{} @var{year} @var{copyright-owner} +@end example + +It is customary to put information on how to get a manual after the +copyright notice, followed by the copying permissions for the +manual.@refill + +Note that permissions must be given here as well as in the summary +segment within @code{@@ifinfo} and @code{@@end ifinfo} that +immediately follows the header since this text appears only in the +printed manual and the @samp{ifinfo} text appears only in the Info +file.@refill + +@xref{Sample Permissions}, for the standard text.@refill + +@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page +@comment node-name, next, previous, up +@subsection Heading Generation +@findex end titlepage +@cindex Headings, page, begin to appear +@cindex Titlepage end starts headings +@cindex End titlepage starts headings + +An @code{@@end titlepage} command on a line by itself 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). +(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.) +You can specify these formats in different ways:@refill + +@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, , @code{@@setchapternewpage}}.)@refill + +@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.@refill +@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.@refill + +@node headings on off, , end titlepage, Titlepage & Copyright Page +@comment node-name, next, previous, up +@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 +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 The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File +@comment node-name, next, previous, up +@section The `Top' Node and Master Menu +@cindex @samp{@r{Top}} node +@cindex Master menu +@cindex Node, `Top' + +The `Top' node is the node from which you enter an Info file.@refill + +A `Top' node should contain a brief description of the Info file and an +extensive, master menu for the whole Info file. +This helps the reader understand what the Info file is +about. Also, you should write the version number of the program to +which the Info file applies; or, at least, the edition number.@refill + +The contents of the `Top' node should appear only in the Info file; none +of it should appear in printed output, so enclose it between +@code{@@ifinfo} and @code{@@end ifinfo} 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{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so. +@xref{Conditionals, , Conditionally Visible Text}.)@refill + +@menu +* Title of Top Node:: Sketch what the file is about. +* Master Menu Parts:: A master menu has three or more parts. +@end menu + +@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node +@ifinfo +@subheading `Top' Node Title +@end ifinfo + +Sometimes, you will want to place an @code{@@top} sectioning command +line containing the title of the document immediately after the +@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top} +Sectioning Command}, for more information).@refill + +For example, the beginning of the Top node of this manual contains an +@code{@@top} sectioning command, a short description, and edition and +version information. It looks like this:@refill + +@example +@group +@dots{} +@@end titlepage + +@@ifinfo +@@node Top, Copying, , (dir) +@@top Texinfo + +Texinfo is a documentation system@dots{} +@end group + +@group +This is edition@dots{} +@dots{} +@@end ifinfo +@end group + +@group +@@menu +* Copying:: Texinfo is freely + redistributable. +* Overview:: What is Texinfo? +@dots{} +@end group +@@end menu +@end example + +In a `Top' node, the `Previous', and `Up' nodes usually refer to the top +level directory of the whole Info system, which is called @samp{(dir)}. +The `Next' node refers to the first node that follows the main or master +menu, which is usually the copying permissions, introduction, or first +chapter.@refill + +@node Master Menu Parts, , Title of Top Node, The Top Node +@subsection Parts of a Master Menu +@cindex Master menu parts +@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.@refill + +Generally, a master menu is divided into parts.@refill + +@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.@refill + +@item +The second part contains nodes for the indices.@refill + +@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.)@refill + +For example, the master menu for this manual looks like the following +(but has many more entries):@refill + +@example +@group +@@menu +* Copying:: Texinfo is freely + redistributable. +* Overview:: What is Texinfo? +* Texinfo Mode:: Special features in GNU Emacs. +@dots{} +@dots{} +@end group +@group +* Command and Variable Index:: + An entry for each @@-command. +* Concept Index:: An entry for each concept. +@end group + +@group +@@detailmenu + --- The Detailed Node Listing --- + +Overview of Texinfo + +* Info Files:: What is an Info file? +* Printed Manuals:: Characteristics of + a printed manual. +@dots{} +@dots{} +@end group + +@group +Using Texinfo Mode + +* Info on a Region:: Formatting part of a file + for Info. +@dots{} +@dots{} +@@end detailmenu +@@end menu +@end group +@end example + +@node Software Copying Permissions, , The Top Node, Beginning a File +@comment node-name, next, previous, up +@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, this section usually follows 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.@refill + +The copying and distribution information and the disclaimer are +followed by an introduction or else by the first chapter of the +manual.@refill + +@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. +Usually, an introduction is put in an @code{@@unnumbered} section. +(@xref{unnumbered & appendix, , The @code{@@unnumbered} and +@code{@@appendix} Commands}.)@refill + +@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 +@findex bye + +The end of a Texinfo file should include the commands that create +indices and generate detailed and summary tables of contents. +And it must include the @code{@@bye} command that marks the last line +processed by @TeX{}.@refill + +@need 700 +For example: + +@example +@@node Concept Index, , Variables Index, Top +@@c node-name, next, previous, up +@@unnumbered Concept Index + +@@printindex cp + +@@contents +@@bye +@end example + +@menu +* Printing Indices & Menus:: How to print an index in hardcopy and + generate index menus in Info. +* Contents:: How to create a table of contents. +* File End:: How to mark the end of a file. +@end menu + +@node Printing Indices & Menus, Contents, Ending a File, Ending a File +@comment node-name, next, previous, up +@section Index Menus and Printing an Index +@findex printindex +@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{Format/Print Hardcopy}) to sort the raw data to produce a sorted +index file. The sorted index file is what is actually used to +print the index.@refill + +Texinfo offers six different types of predefined index: the concept +index, the function index, the variables index, the keystroke index, the +program index, and the data type index (@pxref{Predefined Indices}). Each +index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr}, +@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them +into separate sections (@pxref{Combining Indices}); or you may define +your own indices (@pxref{New Indices, , Defining New Indices}).@refill + +The @code{@@printindex} command takes a two-letter index name, reads +the corresponding sorted index file and formats it appropriately into +an index.@refill + +@ignore +The two-letter index names are: + +@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 +@end ignore +The @code{@@printindex} command does not generate a chapter heading +for the index. Consequently, you should precede the +@code{@@printindex} command with a suitable section or chapter command +(usually @code{@@unnumbered}) to supply the chapter heading and put +the index into the table of contents. Precede the @code{@@unnumbered} +command with an @code{@@node} line.@refill + +@need 1200 +For example: + +@smallexample +@group +@@node Variable Index, Concept Index, Function Index, Top +@@comment node-name, next, previous, up +@@unnumbered Variable Index + +@@printindex vr +@end group + +@group +@@node Concept Index, , Variable Index, Top +@@comment node-name, next, previous, up +@@unnumbered Concept Index + +@@printindex cp +@end group + +@group +@@summarycontents +@@contents +@@bye +@end group +@end smallexample + +@noindent +(Readers often prefer that the concept index come last in a book, +since that makes it easiest to find.)@refill + +@ignore +@c TeX can do sorting, just not conveniently enough to handle sorting +@c Texinfo indexes. --karl, 5may97. +In @TeX{}, the @code{@@printindex} command needs a sorted index file +to work from. @TeX{} does not know how to do sorting; this is a +deficiency. @TeX{} writes output files of raw index data; use the +@code{texindex} program to convert these files to sorted index files. +(@xref{Format/Print Hardcopy}, for more information.)@refill +@end ignore + + +@node Contents, File End, Printing Indices & Menus, Ending a File +@comment node-name, next, previous, up +@section Generating a Table of Contents +@cindex Table of contents +@cindex Contents, Table of +@findex contents +@findex summarycontents +@findex shortcontents + +The @code{@@chapter}, @code{@@section}, and other structuring commands +supply the information to make up a table of contents, but they do not +cause an actual table to appear in the manual. To do this, you must +use the @code{@@contents} and @code{@@summarycontents} +commands:@refill + +@table @code +@item @@contents +Generate a table of contents in a printed manual, including all +chapters, sections, subsections, etc., as well as appendices and +unnumbered chapters. (Headings generated by the @code{@@heading} +series of commands do not appear in the table of contents.) The +@code{@@contents} command should be written on a line by +itself.@refill + +@item @@shortcontents +@itemx @@summarycontents +(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the +two commands are exactly the same.)@refill + +Generate a short or summary table of contents that lists only the +chapters (and appendices and unnumbered chapters). Omit sections, subsections +and subsubsections. Only a long manual needs a short table +of contents in addition to the full table of contents.@refill + +Write the @code{@@shortcontents} command on a line by itself right +@emph{before} the @code{@@contents} command.@refill +@end table + +The table of contents commands automatically generate a chapter-like +heading at the top of the first table of contents page. Write the table +of contents commands at the very end of a Texinfo file, just before the +@code{@@bye} command, following any index sections---anything in the +Texinfo file after the table of contents commands will be omitted from +the table of contents.@refill + +When you print a manual with a table of contents, the table of +contents are printed last and numbered with roman numerals. You need +to place those pages in their proper place, after the title page, +yourself. (This is the only collating you need to do for a printed +manual. The table of contents is printed last because it is generated +after the rest of the manual is typeset.)@refill + +@need 700 +Here is an example of where to write table of contents commands:@refill + +@example +@group +@var{indices}@dots{} +@@shortcontents +@@contents +@@bye +@end group +@end example + +Since an Info file uses menus instead of tables of contents, the Info +formatting commands ignore the @code{@@contents} and +@code{@@shortcontents} commands.@refill + +@node File End, , Contents, Ending a File +@comment node-name, next, previous, up +@section @code{@@bye} File Ending +@findex bye + +An @code{@@bye} command terminates @TeX{} or Info formatting. None of +the formatting commands see any of the file following @code{@@bye}. +The @code{@@bye} command should be on a line by itself.@refill + +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. @xref{Compile-Command, , Using Local +Variables and the Compile Command}, for more information.@refill + +@node Structuring, Nodes, Ending a File, Top +@comment node-name, next, previous, up +@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, Structuring Command Types, Structuring, Structuring +@comment node-name, next, previous, up +@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, makeinfo top, Tree Structuring, Structuring +@comment node-name, next, previous, up +@section Types of Structuring Commands + +The chapter structuring commands fall into four groups or series, each +of which contains structuring commands corresponding to the +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}}).@refill + +@item +The @code{@@heading} series of commands produce unnumbered headings +that do not appear in a table of contents. The heading commands never +start a new page.@refill + +@item +The @code{@@majorheading} command produces results similar to using +the @code{@@chapheading} command but generates a larger vertical +whitespace before the heading.@refill + +@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 + +@need 1000 +Here are the four groups of chapter structuring commands:@refill + +@c Slightly different formatting for regular sized books and smallbooks. +@ifset smallbook +@sp 1 +@tex +{\let\rm=\indrm \let\tt=\indtt +\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& +\hskip.5em#\hfil\cr + +& & & \rm No new pages\cr +\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr +\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr + +& & & \cr + & \tt @@top& & \tt @@majorheading\cr +\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr +\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr +\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& +\tt @@subheading\cr +\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& +\tt @@subsubheading\cr}} +@end tex +@end ifset +@ifclear smallbook +@sp 1 +@tex +\vbox{ +\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& +\hskip.5em#\hfil& \hskip.5em #\hfil\cr + +& & & \cr +& & & \rm No new pages\cr +\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr +\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr + +& & & \cr + & \tt @@top& & \tt @@majorheading\cr +\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr +\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr +\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& +\tt @@subheading\cr +\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& +\tt @@subsubheading\cr}} +@end tex +@end ifclear +@ifinfo +@example +@group + @r{No new pages} +@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} +@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} + + @@top @@majorheading +@@chapter @@unnumbered @@appendix @@chapheading +@@section @@unnumberedsec @@appendixsec @@heading +@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading +@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading +@end group +@end example +@end ifinfo + +@c Cannot line up columns properly inside of an example because of roman +@c proportional fonts. +@ignore +@ifset smallbook +@iftex +@smallexample +@group + @r{No new pages} +@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} +@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} + + @@top @@majorheading +@@chapter @@unnumbered @@appendix @@chapheading +@@section @@unnumberedsec @@appendixsec @@heading +@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading +@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading +@end group +@end smallexample +@end iftex +@end ifset +@ifclear smallbook +@iftex +@smallexample +@group + @r{No new pages} +@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} +@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} + + @@top @@majorheading +@@chapter @@unnumbered @@appendix @@chapheading +@@section @@unnumberedsec @@appendixsec @@heading +@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading +@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading +@end group +@end smallexample +@end iftex +@end ignore + +@node makeinfo top, chapter, Structuring Command Types, Structuring +@comment node-name, next, previous, up +@section @code{@@top} + +The @code{@@top} command is a special sectioning command that you use +only after an @samp{@@node Top} line at the beginning of a Texinfo file. +The @code{@@top} command tells the @code{makeinfo} formatter +which node is the `Top' +node. It has the same typesetting effect as @code{@@unnumbered} +(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). +For detailed information, see +@ref{makeinfo top command, , The @code{@@top} Command}.@refill + +@node chapter, unnumbered & appendix, makeinfo top, Structuring +@comment node-name, next, previous, up +@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, majorheading & chapheading, chapter, Structuring +@comment node-name, next, previous, up +@section @code{@@unnumbered}, @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, unnumbered & appendix, Structuring +@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.@refill + +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, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring +@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, subsection, section, Structuring +@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, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring +@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, subsubsection, subsection, Structuring +@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, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring +@comment node-name, next, previous, up +@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, , subsubsection, Structuring +@comment node-name, next, previous, up +@section @code{@@raisesections} and @code{@@lowersections} +@findex raisesections +@findex lowersections +@cindex Raising and lowering sections +@cindex Sections, raising and lowering + +The @code{@@raisesections} and @code{@@lowersections} commands raise and +lower the hierarchical level of chapters, sections, subsections and the +like. The @code{@@raisesections} command changes sections to chapters, +subsections to sections, and so on. The @code{@@lowersections} command +changes chapters to sections, sections to subsections, and so on. + +@cindex Include files, and section levels +An @code{@@lowersections} command is useful if you wish to include text +that is written as an outer or standalone Texinfo file in another +Texinfo file as an inner, included file. If you write the command at +the beginning of the file, all your @code{@@chapter} commands are +formatted as if they were @code{@@section} commands, all your +@code{@@section} command are formatted as if they were +@code{@@subsection} commands, and so on. + +@need 1000 +@code{@@raisesections} raises a command one level in the chapter +structuring hierarchy:@refill + +@example +@group + @r{Change} @r{To} + +@@subsection @@section, +@@section @@chapter, +@@heading @@chapheading, + @r{etc.} +@end group +@end example + +@need 1000 +@code{@@lowersections} lowers a command one level in the chapter +structuring hierarchy:@refill + +@example +@group + @r{Change} @r{To} + +@@chapter @@section, +@@subsection @@subsubsection, +@@heading @@subheading, + @r{etc.} +@end group +@end example + +An @code{@@raisesections} or @code{@@lowersections} command changes only +those structuring commands that follow the command in the Texinfo file. +Write an @code{@@raisesections} or @code{@@lowersections} command on a +line of its own. + +An @code{@@lowersections} command cancels an @code{@@raisesections} +command, and vice versa. Typically, the commands are used like this: + +@example +@@lowersections +@@include somefile.texi +@@raisesections +@end example + +Without the @code{@@raisesections}, all the subsequent sections in your +document will be lowered. + +Repeated use of the commands continue to raise or lower the hierarchical +level a step at a time. + +An attempt to raise above `chapters' reproduces chapter commands; an +attempt to lower below `subsubsections' reproduces subsubsection +commands. + +@node Nodes, Menus, Structuring, Top +@comment node-name, next, previous, up +@chapter Nodes + +@dfn{Nodes} are the primary segments of a Texinfo file. They do not +themselves impose a hierarchic or any other kind of structure on a file. +Nodes contain @dfn{node pointers} that name other nodes, and can contain +@dfn{menus} which are lists of nodes. In Info, the movement commands +can carry you to a pointed-to node or to a node listed in a menu. Node +pointers and menus provide structure for Info files just as chapters, +sections, subsections, and the like, provide structure for printed +books.@refill + +@menu +* Two Paths:: Different commands to structure + Info output and printed output. +* Node Menu Illustration:: A diagram, and sample nodes and menus. +* node:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. +@end menu + +@node Two Paths, Node Menu Illustration, Nodes, Nodes +@ifinfo +@heading Two Paths +@end ifinfo + +The node and menu commands and the chapter structuring commands are +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, most Texinfo +files are written such that the structure for the Info output +corresponds to the structure for the printed output. It is not +convenient to do otherwise.@refill + +Generally, printed output is structured in a tree-like hierarchy in +which the chapters are the major limbs from which the sections branch +out. Similarly, node pointers and menus are organized to create a +matching structure in the Info output.@refill + +@node Node Menu Illustration, node, Two Paths, Nodes +@comment node-name, next, previous, up +@section Node and Menu Illustration + +Here is a copy of the diagram shown earlier that illustrates a Texinfo +file with three chapters, each of which contains two sections.@refill + +Note that the ``root'' is at the top of the diagram and the ``leaves'' +are at the bottom. This is how such a diagram is drawn conventionally; +it illustrates an upside-down tree. For this reason, the root node is +called the `Top' node, and `Up' node pointers carry you closer to the +root.@refill + +@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 + +Write the beginning of the node for Chapter 2 like this:@refill + +@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''. + +@quotation +@strong{Please Note:} `Next' refers to the next node at the same +hierarchical level in the manual, not necessarily to the next node +within the Texinfo file. In the Texinfo file, the subsequent node may +be at a lower level---a section-level node may follow a chapter-level +node, and a subsection-level node may follow a section-level node. +`Next' and `Previous' refer to nodes at the @emph{same} hierarchical +level. (The `Top' node contains the exception to this rule. Since the +`Top' node is the only node at that level, `Next' refers to the first +following node, which is almost always a chapter or chapter-level +node.)@refill +@end quotation + +To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter +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, makeinfo Pointer Creation, Node Menu Illustration, Nodes +@comment node-name, next, previous, up +@section The @code{@@node} Command + +@cindex Node, defined +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.@refill + +To create a node, write an @code{@@node} command at the beginning of a +line, and follow it with four arguments, separated by commas, on the +rest of the same line. These arguments are the name of the node, and +the names of the `Next', `Previous', and `Up' pointers, in that order. +You may insert spaces before each pointer if you wish; the spaces are +ignored. You must write the name of the node, and the names of the +`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, +the formatters fail. (@inforef{Top, info, info}, for more information +about nodes in Info.)@refill + +Usually, you write one of the chapter-structuring command lines +immediately after an @code{@@node} line---for example, an +@code{@@section} or @code{@@subsection} line. (@xref{Structuring +Command Types, , Types of Structuring Commands}.)@refill + +@quotation +@strong{Please 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}.@refill +@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 its related +commands; see @ref{Cross References}.)@refill + +@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. +* Top Node Summary:: Write a brief description for readers. +@end menu + +@node Node Names, Writing a Node, node, node +@ifinfo +@subheading Choosing Node and Pointer Names +@end ifinfo + +The name of a node identifies the node. The pointers enable +you to reach other nodes and consist of the names of those nodes.@refill + +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.@refill + +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.@refill + +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.@refill + +@node Writing a Node, Node Line Tips, Node Names, node +@comment node-name, next, previous, up +@subsection How to Write an @code{@@node} Line +@cindex Writing an @code{@@node} line +@cindex @code{@@node} line writing +@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 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.@refill + +After you have inserted an @code{@@node} line, you should immediately +write an @@-command for the chapter or section and insert its name. +Next (and this is important!), put in several index entries. Usually, +you will find at least two and often as many as four or five ways of +referring to the node in the index. Use them all. This will make it +much easier for people to find the node.@refill + +@node Node Line Tips, Node Line Requirements, Writing a Node, node +@comment node-name, next, previous, up +@subsection @code{@@node} Line Tips + +Here are three suggestions: + +@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, First Node, Node Line Tips, node +@comment node-name, next, previous, up +@subsection @code{@@node} Line Requirements + +@cindex Node line requirements +Here are several requirements for @code{@@node} lines: + +@itemize @bullet +@cindex Unique nodename requirement +@cindex Nodename must be unique +@item +All the node names for a single Info file must be unique.@refill + +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.@refill + +@item +A pointer name must be the name of a node.@refill + +The node to which a pointer points may come before or after the +node containing the pointer.@refill + +@cindex @@-command in nodename +@cindex Nodename, cannot contain +@item +You cannot use any of the Texinfo @@-commands in a node name; +@w{@@-commands} confuse Info.@refill + +@need 750 +Thus, the beginning of the section called @code{@@chapter} looks like +this:@refill + +@smallexample +@group +@@node chapter, unnumbered & appendix, makeinfo top, Structuring +@@comment node-name, next, previous, up +@@section @@code@{@@@@chapter@} +@@findex chapter +@end group +@end smallexample + +@cindex Comma in nodename +@cindex Apostrophe in nodename +@item +You cannot use commas or apostrophes within a node name; these +confuse @TeX{} or the Info formatters.@refill + +@need 700 +For example, the following is a section title: + +@smallexample +@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} +@end smallexample + +@noindent +The corresponding node name is: + +@smallexample +unnumberedsec appendixsec heading +@end smallexample + +@cindex Case in nodename +@item +Case is significant. +@end itemize + + +@node First Node, makeinfo top command, Node Line Requirements, node +@comment node-name, next, previous, up +@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 contains the main +or master menu for the document, and a short summary of the document +(@pxref{Top Node Summary}). + +@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. If +the file is to be installed directly in the Info directory file, 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. For +example, the @code{@@node Top} line of this manual looks like this: + +@example +@@node Top, Copying, , (dir) +@end example + +@noindent +(You can use the Texinfo updating commands or the @code{makeinfo} +utility to insert these pointers automatically.) + +@cindex Previous node of Top node +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. + +@xref{Install an Info File}, for more information about installing +an Info file in the @file{info} directory. + + +@node makeinfo top command, Top Node Summary, First Node, node +@comment node-name, next, previous, up +@subsection The @code{@@top} Sectioning Command +@findex top @r{(@@-command)} + +A special sectioning command, @code{@@top}, has been created for use +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.@refill + +In Info, the @code{@@top} sectioning command causes the title to appear on a +line by itself, with a line of asterisks inserted underneath.@refill + +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.@refill + + +@node Top Node Summary, , makeinfo top command, node +@subsection The `Top' Node Summary +@cindex @samp{@r{Top}} node summary + +You can help readers by writing a summary in the `Top' node, after the +@code{@@top} line, before the main or master menu. The summary should +briefly describe the document. In Info, this summary will appear just +before the master menu. In a printed manual, this summary will appear +on a page of its own.@refill + +If you do not want the summary to appear on a page of its own in a +printed manual, you can enclose the whole of the `Top' node, including +the @code{@@node Top} line and the @code{@@top} sectioning command line +or other sectioning command line between @code{@@ifinfo} and @code{@@end +ifinfo}. This prevents any of the text from appearing in the printed +output. (@pxref{Conditionals, , Conditionally Visible Text}). You can +repeat the brief description from the `Top' node within @code{@@iftex} +@dots{} @code{@@end iftex} at the beginning of the first chapter, for +those who read the printed manual. This saves paper and may look +neater.@refill + +You should write the version number of the program to which the manual +applies in the summary. This helps the reader keep track of which +manual is for which version of the program. If the manual changes more +frequently than the program or is independent of it, you should also +include an edition number for the manual. (The title page should also +contain this information: see @ref{titlepage, , +@code{@@titlepage}}.)@refill + +@node makeinfo Pointer Creation, , node, Nodes +@section Creating Pointers with @code{makeinfo} +@cindex Creating pointers with @code{makeinfo} +@cindex Pointer creation with @code{makeinfo} +@cindex Automatic pointer creation with @code{makeinfo} + +The @code{makeinfo} program has a feature for automatically creating +node pointers for a hierarchically organized file that lacks +them.@refill + +When you take advantage of this feature, you do not need to write the +`Next', `Previous', and `Up' pointers after the name of a node. +However, you must write a sectioning command, such as @code{@@chapter} +or @code{@@section}, on the line immediately following each truncated +@code{@@node} line. You cannot write a comment line after a node +line; the section line must follow it immediately.@refill + +In addition, you must follow the `Top' @code{@@node} line with a line beginning +with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo +top, , @code{@@top}}. + +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.@refill + +This node pointer insertion feature in @code{makeinfo} is an +alternative to the menu and pointer creation and update commands in +Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially +helpful to people who do not use GNU Emacs for writing Texinfo +documents.@refill + +@node Menus, Cross References, Nodes, Top +@comment node-name, next, previous, up +@chapter Menus +@cindex Menus +@findex menu + +@dfn{Menus} contain pointers to subordinate +nodes.@footnote{Menus can carry you to any node, regardless +of the hierarchical structure; even to nodes in a different +Info file. However, the GNU Emacs Texinfo mode updating +commands work only to create menus of subordinate nodes. +Conventionally, cross references are used to refer to other +nodes.} In Info, you use menus to go to such nodes. Menus +have no effect in printed manuals and do not appear in +them.@refill + +By convention, a menu is put at the end of a node since a reader who +uses the menu may not see text that follows it.@refill + +@ifinfo +A node that has a menu should @emph{not} contain much text. If you +have a lot of text and a menu, move most of the text into a new +subnode---all but a few lines.@refill +@end ifinfo +@iftex +@emph{A node that has a menu should not contain much text.} If you +have a lot of text and a menu, move most of the text into a new +subnode---all but a few lines. Otherwise, a reader with a terminal +that displays only a few lines may miss the menu and its associated +text. As a practical matter, you should locate a menu within 20 lines +of the beginning of the node.@refill +@end iftex + +@menu +* Menu Location:: Put a menu in a short node. +* 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, Writing a Menu, Menus, Menus +@ifinfo +@heading Menus Need Short Nodes +@end ifinfo +@cindex Menu location +@cindex Location of menus +@cindex Nodes for menus are short +@cindex Short nodes for menus + +@ifinfo +A reader can easily see a menu that is close to the beginning of the +node. The node should be short. As a practical matter, you should +locate a menu within 20 lines of the beginning of the node. +Otherwise, a reader with a terminal that displays only a few lines may +miss the menu and its associated text.@refill +@end ifinfo + +The short text before a menu may look awkward in a printed manual. To +avoid this, you can write a menu near the beginning of its node and +follow the menu by an @code{@@node} line, and then an @code{@@heading} +line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, +the menu, @code{@@node} line, and title appear only in the Info file, +not the printed document.@refill + +For example, the preceding two paragraphs follow an Info-only menu, +@code{@@node} line, and heading, and look like this:@refill + +@example +@group +@@menu +* Menu Location:: Put a menu in a short node. +* 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 entries. +* Other Info Files:: How to refer to a different + Info file. +@@end menu + +@@node Menu Location, Writing a Menu, , Menus +@@ifinfo +@@heading Menus Need Short Nodes +@@end ifinfo +@end group +@end example + +The Texinfo file for this document contains more than a dozen +examples of this procedure. One is at the beginning of this chapter; +another is at the beginning of the ``Cross References'' chapter.@refill + +@node Writing a Menu, Menu Parts, Menu Location, Menus +@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.@refill + +A menu looks like this:@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 + +In a menu, every line that begins with an @w{@samp{* }} is a +@dfn{menu entry}. (Note the space after the asterisk.) A +line that does not start with an @w{@samp{* }} may also +appear in a menu. Such a line is not a menu entry but is a +menu comment line that appears in the Info file. In +the example above, the line @samp{Larger Units of Text} is a +menu comment line; the two lines starting with @w{@samp{* }} +are menu entries. + +@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus +@section The Parts of a Menu +@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, Menu Example, Menu Parts, Menus +@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, Other Info Files, Less Cluttered Menu Entry, Menus +@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, , Menu Example, Menus +@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{Install an Info File}.)@refill + +@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 + +Note that the GNU Emacs Texinfo mode menu updating commands only work +with nodes within the current buffer, so you cannot use them to create +menus that refer to other files. You must write such menus by hand.@refill + +@node Cross References, Marking Text, Menus, Top +@comment node-name, next, previous, up +@chapter Cross References +@cindex Making cross references +@cindex Cross references +@cindex References + +@dfn{Cross references} are used to refer the reader to other parts of the +same or different Texinfo files. In Texinfo, nodes are the +places to which cross references can refer.@refill + +@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, Cross Reference Commands, Cross References, Cross References +@ifinfo +@heading What References Are For +@end ifinfo + +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 on-line help system or a +reference manual is not like a novel; few read such documents in +sequence from beginning to end. Instead, people look up what they +need. For this reason, such creations should contain many cross +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-Adv, Some advanced Info +commands, info}.)@refill + +The various cross reference commands use nodes to define cross +reference locations. This is evident in Info, in which a cross +reference takes you to the specified node. @TeX{} also uses nodes to +define cross reference locations, but the action is less obvious. When +@TeX{} generates a DVI file, it records nodes' page numbers and +uses the page numbers in making references. Thus, if you are writing +a manual that will only be printed, and will not be used on-line, you +must nonetheless write @code{@@node} lines to name the places to which +you make cross references.@refill + +@need 800 +@node Cross Reference Commands, Cross Reference Parts, References, Cross References +@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, xref, Cross Reference Commands, Cross References +@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 name (required). This is the node to which the +cross reference takes you. In a printed document, the location of the +node provides the page reference only for references within the same +document.@refill + +@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, Top Node Naming, Cross Reference Parts, Cross References +@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, One Argument, xref, xref +@ifinfo +@subheading What a Reference Looks Like and Requires +@end ifinfo + +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: + +@example +See Section @var{section-number} [@var{node-name}], page @var{page}. +@end example + +@noindent +or like this + +@example +See Section @var{section-number} [@var{title-or-topic}], page @var{page}. +@end example + +The @code{@@xref} command does not generate a period or comma to end +the cross reference in either the Info file or the printed output. +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 +@strong{Please note:} 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 +@strong{Please 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, Two Arguments, Reference Syntax, xref +@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 + +@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, Three Arguments, One Argument, xref +@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.)@refill + +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, Four and Five Arguments, Two Arguments, xref +@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 a +@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, , Three Arguments, xref +@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, ref, xref, Cross References +@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.@refill +@node ref, pxref, Top Node Naming, Cross References +@comment node-name, next, previous, up +@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.@refill + +@need 700 +@noindent +For example, + +@example +For more information, see @@ref@{Hurricanes@}. +@end example + +@noindent +produces + +@example +For more information, see *Note Hurricanes. +@end example + +@noindent +and + +@quotation +For more information, see Section 8.2 [Hurricanes], page 123. +@end quotation + +The @code{@@ref} command sometimes leads 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.@refill + +@need 800 +@noindent +For example, + +@example +@group +Sea surges are described in @@ref@{Hurricanes@}. +@end group +@end example + +@need 800 +@noindent +produces + +@quotation +Sea surges are described in Section 6.7 [Hurricanes], page 72. +@end quotation + +@need 800 +@noindent +in a printed document, and the following in Info: + +@example +Sea surges are described in *Note Hurricanes::. +@end example + +@quotation +@strong{Caution:} You @emph{must} write a period or comma immediately +after an @code{@@ref} command with two or more arguments. Otherwise, +Info will not find the end of the cross reference entry and its +attempt to follow the cross reference will fail. As a general rule, +you should write a period or comma after every @code{@@ref} command. +This looks best in both the printed and the Info output.@refill +@end quotation + +@node pxref, inforef, ref, Cross References +@comment node-name, next, previous, up +@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 after the command's +closing brace. The command differs from @code{@@xref} in two +ways:@refill + +@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, as you do +with @code{@@xref}.@refill + +@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 + +@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 +@strong{Please note:} 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 + +Also, parenthetical cross references look best at the ends of sentences. +Although you may write them in the middle of a sentence, that location +breaks up the flow of text.@refill +@end quotation + +@node inforef, uref, pxref, Cross References +@section @code{@@inforef} +@cindex Cross references using @code{@@inforef} +@cindex References using @code{@@inforef} +@findex inforef + +@code{@@inforef} is used for cross references to Info files for which +there are no printed manuals. Even in a printed manual, +@code{@@inforef} generates a reference directing the user to look in +an Info file.@refill + +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 +Thus, + +@example +@group +@@inforef@{Expert, Advanced Info commands, info@}, +for more information. +@end group +@end example + +@need 800 +@noindent +produces + +@example +@group +*Note Advanced Info commands: (info)Expert, +for more information. +@end group +@end example + +@need 800 +@noindent +and + +@quotation +See Info file @file{info}, node @samp{Expert}, for more information. +@end quotation + +@need 800 +@noindent +Similarly, + +@example +@group +@@inforef@{Expert, , info@}, for more information. +@end group +@end example + +@need 800 +@noindent +produces + +@example +*Note (info)Expert::, for more information. +@end example + +@need 800 +@noindent +and + +@quotation +See Info file @file{info}, node @samp{Expert}, for more information. +@end quotation + +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}}.@refill + + +@node uref, , inforef, Cross References +@section @code{@@uref@{@var{url}[, @var{displayed-text}]@}} +@findex uref +@cindex Uniform resource locator, referring to +@cindex URL, referring to + +@code{@@uref} produces a reference to a uniform resource locator (URL). +It takes one mandatory argument, the URL, and one optional argument, the +text to display (the default is the URL itself). In HTML output, +@code{@@uref} produces a link you can follow. For example: + +@example +The official GNU ftp site is +@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@} +@end example + +@noindent produces (in text): +@display +The official GNU ftp site is +@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu} +@end display + +@noindent whereas +@example +The official +@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu, + GNU ftp site@} holds programs and texts. +@end example + +@noindent produces (in text): +@display +The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds +programs and texts. +@end display + +@noindent and (in HTML): +@example +The official GNU ftp +site holds programs and texts. +@end example + +To merely indicate a URL, use @code{@@url} (@pxref{url, @code{@@url}}). + + +@node Marking Text, Quotations and Examples, Cross References, Top +@comment node-name, next, previous, up +@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 + +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.@refill + +@menu +* Indicating:: How to indicate definitions, files, etc. +* Emphasis:: How to emphasize text. +@end menu + +@node Indicating, Emphasis, Marking Text, Marking Text +@comment node-name, next, previous, up +@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 effect 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:: How to indicate code. +* kbd:: How to show keyboard input. +* key:: How to specify keys. +* samp:: How to show a literal sequence of characters. +* var:: How to indicate a metasyntactic variable. +* file:: How to indicate the name of a file. +* dfn:: How to specify a definition. +* cite:: How to refer to a book that is not in Info. +* url:: How to indicate a world wide web reference. +* email:: How to indicate an electronic mail address. +@end menu + +@node Useful Highlighting, code, Indicating, Indicating +@ifinfo +@subheading Highlighting Commands are Useful +@end ifinfo + +The highlighting commands can be used to generate 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.@refill + +@item @@kbd@{@var{keyboard-characters}@} +Indicate keyboard input.@refill + +@item @@key@{@var{key-name}@} +Indicate the conventional name for a key on a keyboard.@refill + +@item @@samp@{@var{text}@} +Indicate text that is a literal example of a sequence of characters.@refill + +@item @@var@{@var{metasyntactic-variable}@} +Indicate a metasyntactic variable.@refill + +@item @@url@{@var{uniform-resource-locator}@} +Indicate a uniform resource locator for the World Wide Web. + +@item @@file@{@var{file-name}@} +Indicate the name of a file.@refill + +@item @@email@{@var{email-address}[, @var{displayed-text}]@} +Indicate an electronic mail address. + +@item @@dfn@{@var{term}@} +Indicate the introductory or defining use of a term.@refill + +@item @@cite@{@var{reference}@} +Indicate the name of a book.@refill + +@ignore +@item @@ctrl@{@var{ctrl-char}@} +Use for an @sc{ascii} control character.@refill +@end ignore +@end table + +@node code, kbd, Useful Highlighting, Indicating +@comment node-name, next, previous, up +@subsection @code{@@code}@{@var{sample-code}@} +@findex code + +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.@refill + +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. Also, you should use @code{@@code} for the name of a +program, such as @code{diff}, that is a name used in the machine. (You +should write the name of a program in the ordinary text font if you +regard it as a new English word, such as `Emacs' or `Bison'.)@refill + +Use @code{@@code} for environment variables such as @code{TEXINPUTS}, +and other variables.@refill + +Use @code{@@code} for command names in command languages that +resemble programming languages, such as Texinfo or the shell. +For example, @code{@@code} and @code{@@samp} are produced by writing +@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo +source, respectively.@refill + +Note, however, that you should not use @code{@@code} for shell options +such as @samp{-c} when such options stand alone. (Use @code{@@samp}.) +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.@refill + +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 written all in lower case, you should +rearrange the sentence.@refill + +Do not use the @code{@@code} command for a string of characters shorter +than a syntactic token. If you are writing about @samp{TEXINPU}, which +is just a part of the name for the @code{TEXINPUTS} environment +variable, you should use @code{@@samp}.@refill + +In particular, you should not use the @code{@@code} command when writing +about the characters used in a token; do not, for example, 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.@refill + +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 +Use @@code@{diff@} to compare two files. +@end example + +@noindent +produces this in the printed manual:@refill + +@quotation +Use @code{diff} to compare two files. +@end quotation +@iftex + +@noindent +and this in the Info file:@refill + +@example +Use `diff' to compare two files. +@end example +@end iftex + + +@node kbd, key, code, Indicating +@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@refill + +@example +@@kbd@{M-a@} +@end example + +@noindent +and to refer to the characters @kbd{M-x shell}, write@refill + +@example +@@kbd@{M-x shell@} +@end example + +@cindex user input +@cindex slanted typewriter font, for @code{@@kbd} +The @code{@@kbd} command has the same effect as @code{@@code} in Info, +but by default produces a different font (slanted typewriter instead of +normal typewriter) in the printed manual, so users can distinguish the +characters they are supposed to type from those the computer outputs. + +@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{, arg to @@kbdinputstyle} +@vindex example@r{, arg to @@kbdinputstyle} +@vindex code@r{, arg to @@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 example +(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 an @samp{r} and then +press the @key{RET} key'':@refill + +@example +@@kbd@{r @@key@{RET@}@} +@end example + +@noindent +This produces: @kbd{r @key{RET}} + +You also use the @code{@@kbd} command if you are spelling out the letters +you type; for example:@refill + +@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 +really want to mention a space character as one of the characters of +input, write @kbd{@@key@{SPC@}} for it.)@refill + + +@node key, samp, kbd, Indicating +@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, var, key, Indicating +@comment node-name, next, previous, up +@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. +Use @code{@@samp} for the names of command-line options (except in an +@code{@@table}, where @code{@@code} seems to read more easily). 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 var, file, samp, Indicating +@comment node-name, next, previous, up +@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. For example, the Emacs Lisp variable +@code{texinfo-tex-command} is not a metasyntactic variable; it is +properly formatted using @code{@@code}.@refill + +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, to italicize it. + +@need 700 +For example, + +@example +To delete file @@var@{filename@}, +type @@code@{rm @@var@{filename@}@}. +@end example + +@noindent +produces + +@quotation +To delete file @var{filename}, type @code{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 +@end example + +@noindent +However, that is not the style that Texinfo uses. (You can, of +course, modify the sources to @TeX{} and the Info formatting commands +to output the @code{<@dots{}>} format if you wish.)@refill + +@node file, dfn, var, Indicating +@comment node-name, next, previous, up +@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 dfn, cite, file, Indicating +@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, url, dfn, Indicating +@comment node-name, next, previous, up +@subsection @code{@@cite}@{@var{reference}@} +@findex cite + +Use the @code{@@cite} command for the name of a book that lacks a +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file.@refill + +(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}}.)@refill + +@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 url, email, cite, Indicating +@subsection @code{@@url}@{@var{uniform-resource-locator}@} +@findex url +@cindex Uniform resource locator, indicating +@cindex URL, indicating + +Use the @code{@@url} to indicate a uniform resource locator on the World +Wide Web. This is analogous to @code{@@file}, @code{@@var}, etc., and +is purely for markup purposes. It does not produce a link you can +follow in HTML output (the @code{@@uref} command does, @pxref{uref,, +@code{@@uref}}). It is useful for example URL's which do not actually +exist. For example: + +@c Two lines because one is too long for smallbook format. +@example +For example, the url might be +@@url@{http://host.domain.org/path@}. +@end example + + +@node email, , url, Indicating +@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 and @TeX{}, the address is shown in angle brackets, preceded by +the text to display if any. 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@}. +Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. +@end example +@noindent produces +@example +Send bug reports to @email{bug-texinfo@@gnu.org}. +Send suggestions to the @email{bug-texinfo@@gnu.org, same place}. +@end example + + +@node Emphasis, , Indicating, Marking Text +@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 affect on Info and only one of them, +the @code{@@r} command, has any regular use.@refill + +@menu +* emph & strong:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. +@end menu + +@node emph & strong, Smallcaps, Emphasis, Emphasis +@comment node-name, next, previous, up +@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} +@cindex Emphasizing text, font for +@findex emph +@findex strong + +The @code{@@emph} and @code{@@strong} commands are for emphasis; +@code{@@strong} is stronger. In printed output, @code{@@emph} +produces @emph{italics} and @code{@@strong} produces +@strong{bold}.@refill + +@need 800 +For example, + +@example +@group +@@quotation +@@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@} +files in the directory. +@@end quotation +@end group +@end example + +@iftex +@noindent +produces the following in printed output: + +@quotation +@strong{Caution}: @code{rm * .[^.]*} removes @emph{all} +files in the directory. +@end quotation + +@noindent +and the following in Info: +@end iftex +@ifinfo +@noindent +produces: +@end ifinfo + +@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 file, both @code{@@emph} and @code{@@strong} put asterisks +around the text.@refill + +@quotation +@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the +word @samp{Note}; Info will mistake the combination for a cross +reference. Use a phrase such as @strong{Please note} or +@strong{Caution} instead.@refill +@end quotation + +@node Smallcaps, Fonts, emph & strong, Emphasis +@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font +@cindex Small caps font +@findex sc @r{(small caps font)} + +@iftex +Use the @samp{@@sc} command to set text in the printed output in @sc{a +small caps font} and set text in the Info file in upper case letters.@refill +@end iftex +@ifinfo +Use the @samp{@@sc} command to set text in the printed output in a +small caps font and set text in the Info file in upper case letters.@refill +@end ifinfo + +Write the text between braces in lower case, like this:@refill + +@example +The @@sc@{acm@} and @@sc@{ieee@} are technical societies. +@end example + +@noindent +This produces: + +@display +The @sc{acm} and @sc{ieee} are technical societies. +@end display + +@TeX{} typesets the small caps font in a manner that prevents the +letters from `jumping out at you on the page'. This makes small caps +text easier to read than text in all upper case. The Info formatting +commands set all small caps text in upper case.@refill + +@ifinfo +If the text between the braces of an @code{@@sc} command is upper case, +@TeX{} typesets in full-size capitals. Use full-size capitals +sparingly.@refill +@end ifinfo +@iftex +If the text between the braces of an @code{@@sc} command is upper case, +@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals +sparingly.@refill +@end iftex + +You may also use the small caps font for a jargon word such as +@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill + +There are subtleties to using the small caps font with a jargon word +such as @sc{cdr}, a word used in Lisp programming. In this case, you +should use the small caps font when the word refers to the second and +subsequent elements of a list (the @sc{cdr} of the list), but you +should use @samp{@@code} when the word refers to the Lisp function of +the same spelling.@refill + +@node Fonts, Customized Highlighting, Smallcaps, Emphasis +@comment node-name, next, previous, up +@subsection Fonts for Printing, Not Info +@cindex Fonts for printing, not for Info +@findex i @r{(italic font)} +@findex b @r{(bold font)} +@findex t @r{(typewriter font)} +@findex r @r{(Roman font)} + +Texinfo provides four font commands that specify font changes in the +printed manual but have no effect in the Info file. @code{@@i} +requests @i{italic} font (in some versions of @TeX{}, a slanted font +is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the +@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a +@r{roman} font, which is the usual font in which text is printed. All +four commands apply to an argument that follows, surrounded by +braces.@refill + +Only the @code{@@r} command has much use: in example programs, you +can use the @code{@@r} command to convert code comments from the +fixed-width font to a roman font. This looks better in printed +output.@refill + +@need 700 +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 + +If possible, you should avoid using the other three font commands. If +you need to use one, it probably indicates a gap in the Texinfo +language.@refill + +@node Customized Highlighting, , Fonts, Emphasis +@comment node-name, next, previous, up +@subsection Customized Highlighting +@cindex Highlighting, customized +@cindex Customized highlighting + +@c I think this whole section is obsolete with the advent of macros +@c --karl, 15sep96. +You can use regular @TeX{} commands inside of @code{@@iftex} @dots{} +@code{@@end iftex} to create your own customized highlighting commands +for Texinfo. The easiest way to do this is to equate your customized +commands with pre-existing commands, such as those for italics. Such +new commands work only with @TeX{}.@refill + +@findex definfoenclose +@cindex Enclosure command for Info +You can use the @code{@@definfoenclose} command inside of +@code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info +with the same names as new commands for @TeX{}. +@code{@@definfoenclose} creates new commands for Info that mark text by +enclosing it in strings that precede and follow the text. +@footnote{Currently, @code{@@definfoenclose} works only with +@code{texinfo-format-buffer} and @code{texinfo-format-region}, not with +@code{makeinfo}.}@refill + +Here is how to create a new @@-command called @code{@@phoo} that causes +@TeX{} to typeset its argument in italics and causes Info to display the +argument between @samp{//} and @samp{\\}.@refill + +@need 1300 +For @TeX{}, write the following to equate the @code{@@phoo} command with +the existing @code{@@i} italics command:@refill + +@example +@group +@@iftex +@@global@@let@@phoo=@@i +@@end iftex +@end group +@end example + +@noindent +This defines @code{@@phoo} as a command that causes @TeX{} to typeset +the argument to @code{@@phoo} in italics. @code{@@global@@let} tells +@TeX{} to equate the next argument with the argument that follows the +equals sign. + +@need 1300 +For Info, write the following to tell the Info formatters to enclose the +argument between @samp{//} and @samp{\\}: + +@example +@group +@@ifinfo +@@definfoenclose phoo, //, \\ +@@end ifinfo +@end group +@end example + +@noindent +Write the @code{@@definfoenclose} command on a line and follow it with +three arguments separated by commas (commas are used as separators in an +@code{@@node} line in the same way).@refill + +@itemize @bullet +@item +The first argument to @code{@@definfoenclose} is the @@-command name +@strong{without} the @samp{@@}; + +@item +the second argument is the Info start delimiter string; and, + +@item +the third argument is the Info end delimiter string. +@end itemize + +@noindent +The latter two arguments enclose the highlighted text in the Info file. +A delimiter string may contain spaces. Neither the start nor end +delimiter is required. However, if you do not provide a start +delimiter, you must follow the command name with two commas in a row; +otherwise, the Info formatting commands will misinterpret the end +delimiter string as a start delimiter string.@refill + +After you have defined @code{@@phoo} both for @TeX{} and for Info, you +can then write @code{@@phoo@{bar@}} to see @samp{//bar\\} +in Info and see +@ifinfo +@samp{bar} in italics in printed output. +@end ifinfo +@iftex +@i{bar} in italics in printed output. +@end iftex + +Note that each definition applies to its own formatter: one for @TeX{}, +the other for Info. + +@need 1200 +Here is another example: + +@example +@group +@@ifinfo +@@definfoenclose headword, , : +@@end ifinfo +@@iftex +@@global@@let@@headword=@@b +@@end iftex +@end group +@end example + +@noindent +This defines @code{@@headword} as an Info formatting command that +inserts nothing before and a colon after the argument and as a @TeX{} +formatting command to typeset its argument in bold. + +@node Quotations and Examples, Lists and Tables, Marking Text, Top +@comment node-name, next, previous, up +@chapter Quotations and Examples + +Quotations and examples are blocks of text consisting of one or more +whole paragraphs that are set off from the bulk of the text and +treated differently. They are usually indented.@refill + +In Texinfo, you always begin a quotation or example by writing an +@@-command at the beginning of a line by itself, and end it by writing +an @code{@@end} command that is also at the beginning of a line by +itself. For instance, you begin an example by writing @code{@@example} +by itself at the beginning of a line and end the example by writing +@code{@@end example} on a line by itself, at the beginning of that +line.@refill +@findex end + +@menu +* Block Enclosing Commands:: Use different constructs for + different purposes. +* quotation:: How to write a quotation. +* example:: How to write an example in a fixed-width font. +* noindent:: How to prevent paragraph indentation. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. +* display:: How to write an example in the current font. +* format:: How to write an example that does not narrow + the margins. +* exdent:: How to undo the indentation of a line. +* flushleft & flushright:: How to push text flushleft or flushright. +* cartouche:: How to draw cartouches around examples. +@end menu + +@node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples +@section The Block Enclosing Commands + +Here are commands for quotations and examples:@refill + +@table @code +@item @@quotation +Indicate text that is quoted. The text is filled, indented, and +printed in a roman font by default.@refill + +@item @@example +Illustrate code, commands, and the like. The text is printed +in a fixed-width font, and indented but not filled.@refill + +@item @@lisp +Illustrate Lisp code. The text is printed in a fixed-width font, +and indented but not filled.@refill + +@item @@smallexample +Illustrate code, commands, and the like. Similar to +@code{@@example}, except that in @TeX{} this command typesets text in +a smaller font for the smaller @code{@@smallbook} format than for the +8.5 by 11 inch format.@refill + +@item @@smalllisp +Illustrate Lisp code. Similar to @code{@@lisp}, except that +in @TeX{} this command typesets text in a smaller font for the smaller +@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill + +@item @@display +Display illustrative text. The text is indented but not filled, and +no font is specified (so, by default, the font is roman).@refill + +@item @@format +Print illustrative text. The text is not indented and not filled +and no font is specified (so, by default, the font is roman).@refill +@end table + +The @code{@@exdent} command is used within the above constructs to +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.@refill + +You can use the @code{@@cartouche} command within one of the above +constructs to highlight the example or quotation by drawing a box with +rounded corners around it. (The @code{@@cartouche} command affects +only the printed manual; it has no effect in the Info file; see +@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill + +@node quotation, example, Block Enclosing Commands, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@quotation} +@cindex Quotations +@findex quotation + +The text of a quotation is +processed normally except that:@refill + +@itemize @bullet +@item +the margins are closer to the center of the page, so the whole of the +quotation is indented;@refill + +@item +the first lines of paragraphs are indented no more than other +lines;@refill + +@item +in the printed output, interparagraph spacing is reduced.@refill +@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.@refill +@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. Thus, the following,@refill + +@example +@@quotation +This is +a foo. +@@end quotation +@end example + +@noindent +produces + +@quotation +This is a foo. +@end quotation + +@node example, noindent, quotation, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@example} +@cindex Examples, formatting them +@cindex Formatting examples +@findex example + +The @code{@@example} command is used to indicate an example that is +not part of the running text, such as computer input or output.@refill + +@example +@group +This is an example of text written between an +@code{@@example} command +and an @code{@@end example} command. +The text is indented but not filled. +@end group + +@group +In the printed manual, the text is typeset in a +fixed-width font, and extra spaces and blank lines are +significant. In the Info file, an analogous result is +obtained by indenting each line with five spaces. +@end group +@end example + +Write an @code{@@example} command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the example +with an @code{@@end example} command, also written at the beginning of a +line by itself. The @code{@@end example} will disappear from the +output.@refill + +@need 700 +For example, + +@example +@@example +mv foo bar +@@end example +@end example + +@noindent +produces + +@example +mv foo bar +@end example + +Since the lines containing @code{@@example} and @code{@@end example} +will disappear, you should put a blank line before the +@code{@@example} and another blank line after the @code{@@end +example}. (Remember that blank lines between the beginning +@code{@@example} and the ending @code{@@end example} will appear in +the output.)@refill + +@quotation +@strong{Caution:} Do not use tabs in the lines of an example (or anywhere +else in Texinfo, for that matter)! @TeX{} treats tabs as single +spaces, and that is not what they look like. This is a problem with +@TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to +convert tabs in a region to multiple spaces.)@refill +@end quotation + +Examples are often, logically speaking, ``in the middle'' of a +paragraph, and the text continues after an example should not be +indented. The @code{@@noindent} command prevents a piece of text from +being indented as if it were a new paragraph. +@ifinfo +(@xref{noindent}.) +@end ifinfo + +(The @code{@@code} command is used for examples of code that are +embedded within sentences, not set off from preceding and following +text. @xref{code, , @code{@@code}}.) + +@node noindent, Lisp Example, example, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@noindent} +@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. However, you can prevent this by writing @code{@@noindent} +at the beginning of a line by itself preceding the continuation +text.@refill + +@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 +@tex +% Remove extra vskip; this is a kludge to counter the effect of display +\vskip-3.5\baselineskip +@end tex + +@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.@refill + +In the Texinfo source file for this manual, each line that says +`produces' is preceded by a line containing @code{@@noindent}.@refill + +Do not put braces after an @code{@@noindent} command; they are not +necessary, since @code{@@noindent} is a command used outside of +paragraphs (@pxref{Command Syntax}).@refill + +@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@lisp} +@cindex Lisp example +@findex lisp + +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.}@refill + +Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by +itself.@refill + +@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@smallexample} and @code{@@smalllisp} +@cindex Small book example +@cindex Example for a small book +@cindex Lisp example for a small book +@findex smallexample +@findex smalllisp + +In addition to the regular @code{@@example} and @code{@@lisp} commands, +Texinfo has two other ``example-style'' commands. These are the +@code{@@smallexample} and @code{@@smalllisp} commands. Both these +commands are designed for use with the @code{@@smallbook} command that +causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format +rather than the regular 8.5 by 11 inch format.@refill + +In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands +typeset text in a smaller font for the smaller @code{@@smallbook} +format than for the 8.5 by 11 inch format. Consequently, many examples +containing long lines fit in a narrower, @code{@@smallbook} page +without needing to be shortened. Both commands typeset in the normal +font size when you format for the 8.5 by 11 inch size; indeed, +in this situation, the @code{@@smallexample} and @code{@@smalllisp} +commands are defined to be the @code{@@example} and @code{@@lisp} +commands.@refill + +In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are +equivalent to the @code{@@example} and @code{@@lisp} commands, and work +exactly the same.@refill + +Mark the end of @code{@@smallexample} or @code{@@smalllisp} with +@code{@@end smallexample} or @code{@@end smalllisp}, +respectively.@refill + +@iftex +Here is an example written in the small font used by the +@code{@@smallexample} and @code{@@smalllisp} commands: + +@ifclear smallbook +@display +@tex +% Remove extra vskip; this is a kludge to counter the effect of display +\vskip-3\baselineskip +{\ninett +\dots{} to make sure that you have the freedom to +distribute copies of free software (and charge for +this service if you wish), that you receive source +code or can get it if you want it, that you can +change the software or use pieces of it in new free +programs; and that you know you can do these things.} +@end tex +@end display +@end ifclear +@end iftex +@ifset smallbook +@iftex +@smallexample +This is an example of text written between @code{@@smallexample} and +@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, +this text appears in its normal size; but in a 7 by 9.25 inch manual, +this text appears in a smaller font. +@end smallexample +@end iftex +@end ifset +@ifinfo +@smallexample +This is an example of text written between @code{@@smallexample} and +@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, +this text appears in its normal size; but in a 7 by 9.25 inch manual, +this text appears in a smaller font. +@end smallexample +@end ifinfo + +The @code{@@smallexample} and @code{@@smalllisp} commands make it +easier to prepare smaller format manuals without forcing you to edit +examples by hand to fit them onto narrower pages.@refill + +As a general rule, a printed document looks better if you write all the +examples in a chapter consistently in @code{@@example} or in +@code{@@smallexample}. Only occasionally should you mix the two +formats.@refill + +@xref{smallbook, , Printing ``Small'' Books}, for more information +about the @code{@@smallbook} command.@refill + +@node display, format, smallexample & smalllisp, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@display} +@cindex Display formatting +@findex display + +The @code{@@display} command begins a kind of example. It is 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.@refill + +@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 + +@node format, exdent, display, Quotations and Examples +@comment node-name, next, previous, up +@section @code{@@format} +@findex format + +The @code{@@format} command is similar to @code{@@example} except +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 + +@node exdent, flushleft & flushright, format, Quotations and Examples +@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, cartouche, exdent, Quotations and Examples +@section @code{@@flushleft} and @code{@@flushright} +@findex flushleft +@findex flushright + +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 cartouche, , flushleft & flushright, Quotations and Examples +@section Drawing Cartouches Around Examples +@findex cartouche +@cindex Box with rounded corners + +In a printed manual, the @code{@@cartouche} command draws a box with +rounded corners around its contents. 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.@refill + +The @code{@@cartouche} command affects only the printed manual; it has +no effect in the Info file.@refill + +@need 1500 +For example, + +@example +@group +@@example +@@cartouche +% pwd +/usr/local/share/emacs +@@end cartouche +@@end example +@end group +@end example + +@noindent +surrounds the two-line example with a box with rounded corners, in the +printed manual. + +@iftex +In a printed manual, the example looks like this:@refill + +@example +@group +@cartouche +% pwd +/usr/local/lib/emacs/info +@end cartouche +@end group +@end example +@end iftex + + +@node Lists and Tables, Indices, Quotations and Examples, Top +@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 + +@ifinfo +@node Introducing Lists, itemize, Lists and Tables, Lists and Tables +@heading Introducing Lists +@end ifinfo + +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 with indexing. +@end table + +@node itemize, enumerate, Introducing Lists, Lists and Tables +@comment node-name, next, previous, up +@section 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 + +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 character or any special symbol that results in +a single character in the Info file. (When you write @code{@@bullet} +or @code{@@minus} after an @code{@@itemize} command, you may omit the +@samp{@{@}}.)@refill + +Write the text of the indented paragraphs themselves after the +@code{@@itemize}, up to another line that says @code{@@end +itemize}.@refill + +Before each paragraph for which a mark in the margin is desired, write +a line that says just @code{@@item}. Do not write any other text on this +line.@refill +@findex item + +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. Note that @code{@@bullet} produces an @samp{*} in +Info and a round dot in @TeX{}.@refill + +@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, Two-column Tables, itemize, Lists and Tables +@comment node-name, next, previous, up +@section 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.@refill + +Write the text of the enumerated list in the same way you write an +itemized list: put @code{@@item} on a line of its own before the start +of each paragraph that you want enumerated. Do not write any other text +on the line beginning with @code{@@item}.@refill + +You should put a blank line between entries in the list. +This generally makes it easier to read the Info file.@refill + +@need 1500 +Here is an example of @code{@@enumerate} without an argument:@refill + +@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, Multi-column Tables, enumerate, Lists and 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 + +@ifinfo +@node table, ftable vtable, Two-column Tables, Two-column Tables +@subheading Using the @code{@@table} Command + +Use the @code{@@table} command to produce two-column tables.@refill +@end ifinfo + +Write the @code{@@table} command at the beginning of a 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}, or +@code{@@kbd} (@pxref{Indicating}). Although these commands are usually +followed by arguments in braces, in this case you use the command name +without an argument because @code{@@item} will supply the argument. +This command will be applied to the text that goes into the first column +of each item and determines how it will be highlighted. For example, +@code{@@code} will cause the text in the first column to be highlighted +with an @code{@@code} command. (We recommend @code{@@code} for +@code{@@table}'s of command-line options.) + +@findex asis +You may also choose to 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}, @TeX{} and the Info formatting +commands output the first column entries without added highlighting +(``as is'').@refill + +(The @code{@@table} command may work with other commands besides those +listed here. However, you can only use commands that normally take +arguments in braces.)@refill + +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 text on the same line as the @code{@@item} will +be placed in the first column.@refill +@findex item + +Normally, you should put a blank line before an @code{@@item} line. +This puts a blank like in the Info file. Except when the entries are +very brief, a blank line looks better.@refill + +@need 1500 +The following table, for example, highlights the text in the first +column with an @code{@@samp} command:@refill + +@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}}.)@refill + +@node ftable vtable, itemx, table, Two-column Tables +@comment node-name, next, previous, up +@subsection @code{@@ftable} and @code{@@vtable} +@cindex Tables with indexes +@cindex Indexing table entries automatically +@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, , +Creating Indices}, for more information about indices.@refill + +Begin a two-column table using @code{@@ftable} or @code{@@vtable} by +writing the @@-command at the beginning of a line, followed on the same +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, , ftable vtable, Two-column Tables +@comment node-name, next, previous, up +@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{@@itemx} for all but the first entry; +@code{@@itemx} should always follow an @code{@@item} command. The +@code{@@itemx} command works exactly like @code{@@item} except that it +does not generate extra vertical space above the first column text. + +@need 1000 +For example, + +@example +@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, , Two-column Tables, Lists and Tables +@section 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, Multitable Rows, Multi-column Tables, Multi-column Tables +@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) after the @code{@@multitable} command, as in: + +@example +@@multitable @@columnfractions .33 .33 .33 +@end example + +@noindent The fractions need not add up exactly to 1.0, as these do +not. This allows you to produce tables that do not need the full line +length. + +@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, , Multitable Column Widths, Multi-column Tables +@subsection Multitable Rows +@cindex Multitable rows +@cindex Rows, of a multitable + +@findex item +@cindex tab +After the @code{@@multitable} command defining the column widths (see +the previous section), you begin each row in the body of a multitable +with @code{@@item}, and separate the column entries with @code{@@tab}. +Line breaks are not special within the table body, and you may break +input lines in your source file as necessary. + +Here is a complete example of a multi-column table (the text is from +@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, +emacs, The GNU Emacs Manual}): + +@example +@@multitable @@columnfractions .15 .45 .4 +@@item 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 +@item 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 Indices, Insertions, Lists and Tables, Top +@comment node-name, next, previous, up +@chapter Creating Indices +@cindex Indices +@cindex Creating indices + +Using Texinfo, you can generate indices without having to sort and +collate entries manually. In an index, the entries are listed in +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.@refill + +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. If you wish, you can define your own indices.@refill + +@menu +* Index Entries:: Choose different words for index entries. +* Predefined Indices:: Use different indices for different kinds + of entry. +* 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, Predefined Indices, Indices, Indices +@comment node-name, next, previous, up +@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, Indexing Commands, Index Entries, Indices +@comment node-name, next, previous, up +@section Predefined Indices + +Texinfo provides six predefined indices:@refill + +@itemize @bullet +@item +A @dfn{concept index} listing concepts that are discussed.@refill + +@item +A @dfn{function index} listing functions (such as entry points of +libraries).@refill + +@item +A @dfn{variables index} listing variables (such as global variables +of libraries).@refill + +@item +A @dfn{keystroke index} listing keyboard commands.@refill + +@item +A @dfn{program index} listing names of programs.@refill + +@item +A @dfn{data type index} listing data types (such as structures defined in +header files).@refill +@end itemize + +@noindent +Not every manual needs all of these, and most manuals use two or three +of them. This manual 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). Two or +more indices can be combined into one using the @code{@@synindex} or +@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill + +@node Indexing Commands, Combining Indices, Predefined Indices, Indices +@comment node-name, next, previous, up +@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 +@@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.@refill + +@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! + +@ignore +Concept index entries consist of English text. The usual convention +is to capitalize the first word of each such index entry, unless that +word is the name of a function, variable, or other such entity that +should not be capitalized. However, if your concept index entries are +consistently short (one or two words each) it may look better for each +regular entry to start with a lower case letter, aside from proper +names and acronyms that always call for upper case letters. Whichever +convention you adapt, please be consistent! +@end ignore + +Entries in indices other than the concept index are symbol names in +programming languages, or program names; these names are usually +case-sensitive, so use upper and lower case as required for them. + +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 and @code{@@emph} for emphasis (@pxref{Marking +Text}).@refill +@cindex Index font types + +@cindex Predefined indexing commands +@cindex Indexing commands, predefined +The six indexing commands for predefined indices are: + +@table @code +@item @@cindex @var{concept} +@findex cindex +Make an entry in the concept index for @var{concept}.@refill + +@item @@findex @var{function} +@findex findex +Make an entry in the function index for @var{function}.@refill + +@item @@vindex @var{variable} +@findex vindex +Make an entry in the variable index for @var{variable}.@refill + +@item @@kindex @var{keystroke} +@findex kindex +Make an entry in the key index for @var{keystroke}.@refill + +@item @@pindex @var{program} +@findex pindex +Make an entry in the program index for @var{program}.@refill + +@item @@tindex @var{data type} +@findex tindex +Make an entry in the data type index for @var{data type}.@refill +@end table + +@quotation +@strong{Caution:} Do not use a colon in an index entry. In Info, a +colon separates the menu entry name from the node name. An extra +colon confuses Info. +@xref{Menu Parts, , The Parts of a Menu}, +for more information about the structure of a menu entry.@refill +@end quotation + +If you write several identical index entries in different places in a +Texinfo file, the index in the printed manual will list all the pages to +which those entries refer. However, the index in the Info file will +list @strong{only} the node that references the @strong{first} of those +index entries. Therefore, it is best to write indices in which each +entry refers to only one place in the Texinfo file. Fortunately, this +constraint is a feature rather than a loss since it means that the index +will be easy to use. Otherwise, you could create an index that lists +several pages for one entry and your reader would not know to which page +to turn. If you have two identical entries for one topic, change the +topics slightly, or qualify them to indicate the difference.@refill + +You are not actually required to use the predefined indices for their +canonical purposes. For example, suppose you wish to index some C +preprocessor macros. You could put them in the function index along +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. Or you could put the macros in +with the data types by writing @code{@@tindex} commands for them, and +give that index a suitable title so the reader will understand. +(@xref{Printing Indices & Menus}.)@refill + +@node Combining Indices, New Indices, Indexing Commands, Indices +@comment node-name, next, previous, up +@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 of one of them that +a separate index for them would look silly.@refill + +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}.@refill + +@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, synindex, Combining Indices, Combining Indices +@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 +@findex syncodeindex + +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, , syncodeindex, Combining Indices +@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, , Combining Indices, 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:@refill + +@example +@@defindex @var{name} +@end example + +The name of an index should be a two letter word, such as @samp{au}. +For example:@refill + +@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 the new indexing command just as +you would use a predefined indexing command.@refill + +For example, here is a section heading followed by a concept index +entry and two @samp{au} index entries.@refill + +@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''.) +Texinfo constructs the new indexing command by concatenating the name +of the index with @samp{index}; thus, defining an @samp{au} index +leads to the automatic creation of an @code{@@auindex} command.@refill + +Use the @code{@@printindex} command to print the index, as you do with +the predefined indices. For example:@refill + +@example +@group +@@node Author Index, Subject Index, , Top +@@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 +instead of a roman font. Thus, it parallels the @code{@@findex} command +rather than the @code{@@cindex} command.@refill + +You should define new indices within or right after the end-of-header +line of a Texinfo file, before any @code{@@synindex} or +@code{@@syncodeindex} commands (@pxref{Header}).@refill + +@node Insertions, Breaks, Indices, Top +@comment node-name, next, previous, up +@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 Braces, @samp{@@} and periods. +@item Whitespace within and around a sentence. +@item Accents. +@item Dots and bullets. +@item The @TeX{} logo and the copyright symbol. +@item Mathematical expressions. +@end itemize +@end iftex + +@menu +* Braces Atsigns:: How to insert braces, @samp{@@}. +* 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. +* 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. +* Images:: How to include graphics. +@end menu + + +@node Braces Atsigns, Inserting Space, Insertions, Insertions +@section Inserting @@ and Braces +@cindex Inserting @@, braces +@cindex Braces, inserting +@cindex Special characters, commands to insert +@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. + +Do not put braces after any of these commands; they are not +necessary. + +@menu +* Inserting An Atsign:: How to insert @samp{@@}. +* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. +@end menu + +@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns +@subsection Inserting @samp{@@} with @@@@ +@findex @@ @r{(single @samp{@@})} + +@code{@@@@} stands for a single @samp{@@} in either printed or Info +output. + +Do not put braces after an @code{@@@@} command. + +@node Inserting Braces, , Inserting An Atsign, Braces Atsigns +@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} +@findex @{ @r{(single @samp{@{})} +@findex @} @r{(single @samp{@}})} + +@code{@@@{} stands for a single @samp{@{} in either printed or Info +output. + +@code{@@@}} stands for a single @samp{@}} in either printed or Info +output. + +Do not put braces after either an @code{@@@{} or an @code{@@@}} +command. + + +@node Inserting Space, Inserting Accents, Braces Atsigns, Insertions +@section Inserting Space + +@cindex Inserting space +@cindex Spacing, inserting +@cindex Whitespace, inserting +The following sections describe commands that control spacing of various +kinds within and after sentences. + +@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, Ending a Sentence, Inserting Space, Inserting Space +@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 for +Texinfo to determine when a period ends a sentence and when it is used +in an abbreviation, special commands are needed in some circumstances. +(Usually, Texinfo can guess how to handle periods, so you do not need to +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 : @r{(suppress widening)} +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. + +@need 700 +For example, + +@example +The s.o.p.@@: has three parts @dots{} +The s.o.p. has three parts @dots{} +@end example + +@noindent +@ifinfo +produces +@end ifinfo +@iftex +produces the following. If you look carefully at this printed output, +you will see a little more whitespace after @samp{s.o.p.} in the second +line.@refill +@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 output. Do not put braces after +@code{@@:}. + + +@node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space +@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 single 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 +@ifinfo +produces +@end ifinfo +@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}). This made it necessary for them to be +incompatible with some other formatting systems that use @@-commands. + +Do not put braces after any of these commands. + + +@node Multiple Spaces, dmn, Ending a Sentence, Inserting Space +@subsection Multiple Spaces + +@cindex Multiple spaces +@cindex Whitespace, inserting +@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. + + +@node dmn, , Multiple Spaces, Inserting Space +@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.@refill + +To use the @code{@@dmn} command, write the number and then follow it +immediately, with no intervening space, by @code{@@dmn}, and then by +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{Inserting Space}. + + +@node Inserting Accents, Dots Bullets, Inserting Space, Insertions +@section Inserting Accents + +@cindex Inserting accents +@cindex Accents, inserting +@cindex Floating accents, inserting + +Here is a table with the commands Texinfo provides for inserting +floating accents. The commands with non-alphabetic names do not take +braces around their argument (which is taken to be the next character). +(Exception: @code{@@,} @emph{does} take braces around its argument.) +This is so as to make the source as convenient to type and read as +possible, since accented characters are very common in some languages. + +@findex " +@cindex Umlaut accent +@findex ' +@cindex Acute accent +@findex = +@cindex Macron accent +@findex ^ +@cindex Circumflex accent +@findex ` +@cindex Grave accent +@findex ~ +@cindex Tilde accent +@findex , +@cindex Cedilla accent +@findex dotaccent +@cindex Dot accent +@findex H +@cindex Hungariam umlaut accent +@findex ringaccent +@cindex Ring accent +@findex tieaccent +@cindex Tie-after accent +@findex u +@cindex Breve accent +@findex ubaraccent +@cindex Underbar accent +@findex udotaccent +@cindex Underdot accent +@findex v +@cindex Check accent +@multitable {@@questiondown@{@}} {Output} {macron/overbar 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 or check 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} +@cindex @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{} +@findex ss +@cindex @ss{} +@cindex Es-zet +@cindex Sharp S +@cindex German S +@multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S} +@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! +@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? +@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle +@item @t{@@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{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S +@end multitable + + +@node Dots Bullets, TeX and copyright, Inserting Accents, Insertions +@section Inserting Ellipsis, Dots, 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, bullet, Dots Bullets, Dots Bullets +@subsection @code{@@dots}@{@} (@dots{}) +@findex dots +@cindex Inserting dots +@cindex Dots, inserting + +Use the @code{@@dots@{@}} command to generate an ellipsis, which is +three dots in a row, appropriately spaced, like this: `@dots{}'. 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 (four dots) @enddots{} + +@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, , dots, Dots Bullets +@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, pounds, Dots Bullets, Insertions +@section Inserting @TeX{} and the Copyright Symbol + +The logo `@TeX{}' is typeset in a special fashion and it needs an +@@-command. The copyright symbol, `@copyright{}', 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.@refill + +@menu +* tex:: How to insert the @TeX{} logo. +* copyright symbol:: How to use @code{@@copyright}@{@}. +@end menu + + +@node tex, copyright symbol, TeX and copyright, TeX and copyright +@subsection @code{@@TeX}@{@} (@TeX{}) +@findex tex (command) + +Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed +manual, this is a special logo that is different from three ordinary +letters. In Info, it just looks like @samp{TeX}. The +@code{@@TeX@{@}} command is unique among Texinfo commands in that the +@kbd{T} and the @kbd{X} are in upper case.@refill + + +@node copyright symbol, , tex, TeX and copyright +@subsection @code{@@copyright}@{@} (@copyright{}) +@findex copyright + +Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In +a printed manual, this is a @samp{c} inside a circle, and in Info, +this is @samp{(C)}.@refill + + +@node pounds, minus, TeX and copyright, Insertions +@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling +@findex pounds + +Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a +printed manual, this is the symbol for the currency pounds sterling. +In Info, it is a @samp{#}. Other currency symbols are unfortunately not +available. + + +@node minus, math, pounds, Insertions +@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign +@findex 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, Glyphs, minus, Insertions +@section @code{@@math}: Inserting Mathematical Expressions +@findex math +@cindex Mathematical expressions + +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 +@need 1000 +@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 Info: +@end iftex +@ifinfo +@noindent +This produces the following in Info: +@end ifinfo + +@example +(a + b)(a + b) = a^2 + 2ab + b^2 +@end example + +Thus, the @code{@@math} command has no effect on the Info output. + +For complex mathematical expressions, you can also use @TeX{} directly +(@pxref{Raw Formatter Commands}). When you use @TeX{} directly, +remember to write the mathematical expression between one or two +@samp{$} (dollar-signs) as appropriate. + + +@node Glyphs, Images, math, Insertions +@section Glyphs for Examples +@cindex Glyphs + +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, result, Glyphs, Glyphs +@ifinfo +@subheading Glyphs Summary + +Here are the different glyph commands:@refill +@end ifinfo + +@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, expansion, Glyphs Summary, Glyphs +@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation +@cindex Result of an expression +@cindex Indicating evaluation +@cindex Evaluation glyph +@cindex Value of an expression, indicating + +Use the @code{@@result@{@}} command to indicate the result of +evaluating an expression.@refill + +@iftex +The @code{@@result@{@}} command is displayed as @samp{=>} in Info and +as @samp{@result{}} in the printed output. +@end iftex +@ifinfo +The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info +and as a double stemmed arrow in the printed output.@refill +@end ifinfo + +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, Print Glyph, result, Glyphs +@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion +@cindex Expansion, indicating it + +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{==>} in Info and +as @samp{@expansion{}} in the printed output. +@end iftex +@ifinfo +The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} +in Info and as a long arrow with a flat base in the printed output.@refill +@end ifinfo + +@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 +five spaces.@refill + + +@node Print Glyph, Error Glyph, expansion, Glyphs +@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output +@cindex Printed output, indicating it + +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 +as @samp{@print{}} in the printed output. +@end iftex +@ifinfo +The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info +and similarly, as a horizontal dash butting against a vertical bar, in +the printed output.@refill +@end ifinfo + +In the following example, the printed text is indicated with +@samp{@print{}}, and the value of the expression follows on the +last line.@refill + +@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, Equivalence, Print Glyph, Glyphs +@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message +@cindex Error message, indicating it + +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 as @samp{@error{}} in the printed output. +@end iftex +@ifinfo +The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info +and as the word `error' in a box in the printed output.@refill +@end ifinfo + +@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, Point Glyph, Error Glyph, Glyphs +@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence +@cindex Equivalence, indicating it + +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 +as @samp{@equiv{}} in the printed output. +@end iftex +@ifinfo +The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info +and as a three parallel horizontal lines in the printed output.@refill +@end ifinfo + +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, , Equivalence, Glyphs +@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer +@cindex Point, indicating it in a buffer + +Sometimes you need to show an example of text in an Emacs buffer. In +such examples, the convention is to include the entire contents of the +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 +as @samp{@point{}} in the printed output. +@end iftex +@ifinfo +The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info +and as a small five pointed star in the printed output.@refill +@end ifinfo + +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 + + +@c this should be described with figures when we have them +@c perhaps in the quotation/example chapter. +@node Images, , Glyphs, Insertions +@section Inserting Images + +@cindex Images, inserting +@cindex Pictures, inserting +@findex image + +You can insert an image in an external file with the @code{@@image} +command: + +@example +@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} +@end example + +@cindex Formats for images +@cindex Image formats +The @var{filename} argument is mandatory, and must not have an +extension, because the different processors support different formats: +@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript +format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for +Info output (more or less as if it was an @code{@@example}). HTML +output requires @file{@var{filename}.jpg}. + +@cindex Width of images +@cindex Height of images +@cindex Aspect ratio of images +@cindex Distorting images +The optional @var{width} and @var{height} arguments specify the size to +scale the image to (they are ignored for Info output). If they are both +specified, the image is presented in its natural size (given in the +file); if only one is specified, the other is scaled proportionately; +and if both are specified, both are respected, thus possibly distorting +the original image by changing its aspect ratio. + +@cindex Dimensions and image sizes +The @var{width} and @var{height} may be specified using any valid @TeX{} +dimension, namely: + +@table @asis +@item pt +@cindex Points (dimension) +point (72.27pt = 1in) +@item pc +@cindex Picas +pica (1pc = 12pt) +@item bp +@cindex Big points +big point (72bp = 1in) +@item in +@cindex Inches +inch +@item cm +@cindex Centimeters +centimeter (2.54cm = 1in) +@item mm +@cindex Millimeters +millimeter (10mm = 1cm) +@item dd +@cindex Did@^ot points +did@^ot point (1157dd = 1238pt) +@item cc +@cindex Ciceros +cicero (1cc = 12dd) +@item sp +@cindex Scaled points +scaled point (65536sp = 1pt) +@end table + +@pindex ridt.eps +For example, the following will scale a file @file{ridt.eps} to one +inch vertically, with the width scaled proportionately: + +@example +@@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. This file is included in +the Texinfo distribution and is available from +@uref{ftp://ftp.tug.org/tex/epsf.tex}. + + +@node Breaks, Definition Commands, Insertions, Top +@chapter Making and Preventing Breaks +@cindex Making line and page breaks +@cindex Preventing line and page breaks + +Usually, a Texinfo file is processed both by @TeX{} and by one of the +Info formatting commands. Line, paragraph, or page breaks sometimes +occur in the `wrong' place in one or other form of output. You must +ensure that text looks right both in the printed manual and in the +Info file.@refill + +For example, in a printed manual, page breaks may occur awkwardly in +the middle of an example; to prevent this, you can hold text together +using a grouping command that keeps the text from being split across +two pages. Conversely, you may want to force a page break where none +would occur normally. Fortunately, problems like these do not often +arise. When they do, use the break, break prevention, or pagination +commands.@refill + +@menu +* Break Commands:: Cause and prevent splits. +* Line Breaks:: How to force a single line to use two lines. +* - and hyphenation:: How to tell TeX about hyphenation points. +* w:: How to prevent unwanted line breaks. +* sp:: How to insert blank lines. +* page:: How to force the start of a new page. +* group:: How to prevent unwanted page breaks. +* need:: Another way to prevent unwanted page breaks. +@end menu + +@ifinfo +@node Break Commands, Line Breaks, Breaks, Breaks +@heading The Break Commands +@end ifinfo +@iftex +@sp 1 +@end iftex + +The break commands create or allow line and paragraph breaks:@refill + +@table @code +@item @@* +Force a line break. + +@item @@sp @var{n} +Skip @var{n} blank lines.@refill + +@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 + +The line-break-prevention command holds text together all on one +line:@refill + +@table @code +@item @@w@{@var{text}@} +Prevent @var{text} from being split and hyphenated across two lines.@refill +@end table +@iftex +@sp 1 +@end iftex + +The pagination commands apply only to printed output, since Info +files do not have pages.@refill + +@table @code +@item @@page +Start a new page in the printed manual.@refill + +@item @@group +Hold text together that must appear on one printed page.@refill + +@item @@need @var{mils} +Start a new printed page if not enough space on this one.@refill +@end table + +@node Line Breaks, - and hyphenation, Break Commands, Breaks +@comment node-name, next, previous, up +@section @code{@@*}: Generate Line Breaks +@findex * @r{(force line break)} +@cindex Line breaks +@cindex Breaks in a line + +The @code{@@*} command forces a line break in both the printed manual and +in Info.@refill + +@need 700 +For example, + +@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 + +@noindent +(Note that the space after the first @code{@@*} command is faithfully +carried down to the next line.)@refill + +@need 800 +The @code{@@*} command is often used in a file's copyright page:@refill + +@example +@group +This is edition 2.0 of the Texinfo documentation,@@* +and is for @dots{} +@end group +@end example + +@noindent +In this case, the @code{@@*} command keeps @TeX{} from stretching the +line across the whole page in an ugly manner.@refill + +@quotation +@strong{Please note:} Do not write braces after an @code{@@*} command; +they are not needed.@refill + +Do not write an @code{@@refill} command at the end of a paragraph +containing an @code{@@*} command; it will cause the paragraph to be +refilled after the line break occurs, negating the effect of the line +break.@refill +@end quotation + +@node - and hyphenation, w, Line Breaks, Breaks +@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate + +@findex - +@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 in 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, sp, - and hyphenation, Breaks +@comment node-name, next, previous, up +@section @code{@@w}@{@var{text}@}: Prevent Line Breaks +@findex w @r{(prevent line break)} +@cindex Line breaks, preventing +@cindex Hyphenation, preventing + +@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks +within @var{text}.@refill + +You can use the @code{@@w} command to prevent @TeX{} from automatically +hyphenating a long name or phrase that happens to fall near the end of a +line.@refill + +@example +You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}. +@end example + +@noindent +produces + +@quotation +You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}. +@end quotation + +@quotation +@strong{Caution:} Do not write an @code{@@refill} command at the end +of a paragraph containing an @code{@@w} command; it will cause the +paragraph to be refilled and may thereby negate the effect of the +@code{@@w} command.@refill +@end quotation + +@node sp, page, w, Breaks +@comment node-name, next, previous, up +@section @code{@@sp} @var{n}: Insert Blank Lines +@findex sp @r{(line spacing)} +@cindex Spaces (blank lines) +@cindex Blank lines +@cindex Line spacing + +A line beginning with and containing only @code{@@sp @var{n}} +generates @var{n} blank lines of space in both the printed manual and +the Info file. @code{@@sp} also forces a paragraph break. For +example,@refill + +@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, group, sp, Breaks +@comment node-name, next, previous, up +@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.@refill + +@node group, need, page, Breaks +@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, , group, Breaks +@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, Footnotes, Breaks, Top +@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.@refill + +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:: How to structure a description using a + definition command. +* Optional Arguments:: How to handle optional and repeated arguments. +* deffnx:: How to group two or more `first' lines. +* Def Cmds in Detail:: All the definition commands. +* Def Cmd Conventions:: Conventions for writing definitions. +* Sample Function Definition:: +@end menu + +@node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands +@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.)@refill + +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', +write braces around it. For example:@refill + +@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.@refill + +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. The @code{@@deffn} command possesses three predefined, +specialized variations, @code{@@defun}, @code{@@defmac}, and +@code{@@defspec}, that specify the category for you: ``Function'', +``Macro'', and ``Special Form'' respectively. (In Lisp, a special form +is an entity much like a function.) The @code{@@defvr} command also is +accompanied by several predefined, specialized variations for describing +particular kinds of variables.@refill + +The template for a specialized definition, such as @code{@@defun}, is +similar to the template for a generalized definition, except that you +do not need to specify the category:@refill + +@example +@group +@@defun @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defun +@end group +@end example + +@noindent +Thus, + +@example +@group +@@defun buffer-end flag +This function returns @@code@{(point-min)@} if @@var@{flag@} +is less than 1, @@code@{(point-max)@} otherwise. +@dots{} +@@end defun +@end group +@end example + +@noindent +produces + +@quotation +@defun buffer-end flag +This function returns @code{(point-min)} if @var{flag} is less than 1, +@code{(point-max)} otherwise. @dots{} +@end defun +@end quotation + +@noindent +@xref{Sample Function Definition, Sample Function Definition, A Sample +Function Definition}, for a more detailed example of a function +definition, including the use of @code{@@example} inside the +definition.@refill + +The other specialized commands work like @code{@@defun}.@refill + +@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands +@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.@refill + +@iftex +An argument enclosed within square brackets is optional. +Thus, the phrase +@samp{@code{@r{[}@var{optional-arg}@r{]}}} 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, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments. +Parentheses are used when several arguments are grouped +into additional levels of list structure in Lisp. +@end iftex +@c The following looks better in Info (no `r', `samp' and `code'): +@ifinfo +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}@dots{} stands for zero or more arguments. +Parentheses are used when several arguments are grouped +into additional levels of list structure in Lisp. +@end ifinfo + +Here is the @code{@@defspec} line of an example of an imaginary +special form:@refill + +@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, Def Cmds in Detail, Optional Arguments, Definition Commands +@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 of the other definition commands has an `x' form: @code{@@defunx}, +@code{@@defvrx}, @code{@@deftypefunx}, etc. + +The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. + +@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands +@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. +* Abstract Objects:: Commands for object-oriented programming. +* Data Types:: The definition command for data types. +@end menu + +@node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail +@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} prints argument names such as @var{nchars} in italics or +upper case, as if @code{@@var} had been used, because we think of these +names as metasyntactic variables---they stand for the actual argument +values. Within the text of the description, 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. + +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{}}.@refill + +@need 800 +@noindent +For example, + +@example +@group +@@defun set symbol new-value +Change the value of the symbol @@var@{symbol@} +to @@var@{new-value@}. +@@end defun +@end group +@end example + +@noindent +shows a rather terse definition for a function @code{set} whose +arguments are @var{symbol} and @var{new-value}. The argument names on +the @code{@@defun} line automatically appear in italics or upper case as +if they were enclosed in @code{@@var}. Terminate the definition with +@code{@@end defun} on a line of its own.@refill + +The template is: + +@example +@group +@@defun @var{function-name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defun +@end group +@end example + +@code{@@defun} creates an entry in the index of functions. + +@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}.@refill + +@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}.@refill +@end table + +@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail +@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 +followed it on the same line by the category of the entity and the +name of the entity.@refill + +Capitalize the category name like a title. If the name of the category +contains spaces, as in the name ``User Option'', enclose it in braces. +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}.@refill +@end table + + +@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail +@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 + +The argument names that you write in @code{@@deftypefn} are not subject +to an implicit @code{@@var}---since the actual names of the arguments in +@code{@@deftypefn} are typically scattered among data type names and +keywords, Texinfo cannot find them without help. Instead, you must write +@code{@@var} explicitly around the argument names. In the example +above, the argument names are @samp{foo} and @samp{bar}.@refill + +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.@refill + +@need 800 +@noindent +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 split into three lines, but +would be 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}.@refill + +@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{}}.@refill + +@need 800 +@noindent +Thus, + +@smallexample +@group +@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@}) +@dots{} +@@end deftypefun +@end group +@end smallexample + +@noindent +produces the following in Info: + +@example +@group +-- Function: int foobar (int FOO, float BAR) +@dots{} +@end group +@end example +@iftex + +@need 800 +@noindent +and the following in a printed manual: + +@quotation +@deftypefun int foobar (int @var{foo}, float @var{bar}) +@dots{} +@end deftypefun +@end quotation +@end iftex + +@need 800 +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}.@refill + +@end table + + +@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail +@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 + +@code{@@deftypevr} creates an entry in the index of variables for +@var{name}.@refill + +@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{}}.@refill + +@need 800 +@noindent +For example: + +@example +@group +@@deftypevar int fubar +@dots{} +@@end deftypevar +@end group +@end example + +@noindent +produces the following in Info: + +@example +@group +-- Variable: int fubar +@dots{} +@end group +@end example +@iftex + +@need 800 +@noindent +and the following in a printed manual: + +@quotation +@deftypevar int fubar +@dots{} +@end deftypevar +@end quotation +@end iftex + +@need 800 +@noindent +The template is: + +@example +@group +@@deftypevar @var{data-type} @var{name} +@var{body-of-description} +@@end deftypevar +@end group +@end example + +@code{@@deftypevar} creates an entry in the index of variables for +@var{name}.@refill +@end table + +@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail +@subsection 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.@refill + +In a definition, if the name of a class is truly a name defined in the +programming system for a class, then you should write an @code{@@code} +around it. Otherwise, it is printed in the usual text font.@refill + +@table @code +@findex defcv +@item @@defcv @var{category} @var{class} @var{name} +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. Thus,@refill + +@example +@group +@@defcv @{Class Option@} Window border-pattern +@dots{} +@@end defcv +@end group +@end example + +@noindent +illustrates how you would write the first line of a definition of the +@code{border-pattern} class option of the class @code{Window}.@refill + +The template is + +@example +@group +@@defcv @var{category} @var{class} @var{name} +@dots{} +@@end defcv +@end group +@end example + +@code{@@defcv} creates an entry in the index of variables. + +@findex defivar +@item @@defivar @var{class} @var{name} +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{}}@refill + +The template is: + +@example +@group +@@defivar @var{class} @var{instance-variable-name} +@var{body-of-definition} +@@end defivar +@end group +@end example + +@code{@@defivar} creates an entry in the index of variables. + +@findex defop +@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +The @code{@@defop} command is the general definition command for +entities that may resemble methods in object-oriented programming. +These entities take arguments, as functions do, but are associated +with particular classes of objects.@refill + +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 + +@need 800 +@noindent +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 + +@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. In the Lisp Machine, methods actually were functions, but +they were usually defined with @code{defmethod}. + +@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. +The command is written at the beginning of a line and is followed by +the name of the class of the method, the name of the method, and its +arguments, if any.@refill + +@need 800 +@noindent +For example, + +@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.@refill + +The template is: + +@example +@group +@@defmethod @var{class} @var{method-name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defmethod +@end group +@end example + +@code{@@defmethod} creates an entry, such as `@code{bar-method} on +@code{bar-class}', in the index of functions.@refill + +@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +@findex defmethod +The @code{@@deftypemethod} command is the definition command for methods +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. + +@end table + + +@node Data Types, , Abstract Objects, Def Cmds in Detail +@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 Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands +@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, , Def Cmd Conventions, Definition Commands +@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@}.@@refill +@@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 Footnotes, Conditionals, Definition Commands, Top +@chapter Footnotes +@cindex Footnotes +@findex footnote + +A @dfn{footnote} is for a reference that documents or elucidates the +primary text.@footnote{A footnote should complement or expand upon +the primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see @cite{The Chicago Manual of Style}, which is published by the +University of Chicago Press.}@refill + +@menu +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. +@end menu + +@node Footnote Commands, Footnote Styles, Footnotes, Footnotes +@section Footnote Commands + +In Texinfo, footnotes are created with the @code{@@footnote} command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +@example +ordinary text@@footnote@{@var{text of footnote}@} +@end example + +As shown here, the @code{@@footnote} command should come right after the +text being footnoted, with no intervening space; otherwise, the +formatters the footnote mark might end up starting up a line. + +For example, this clause is followed by a sample +footnote@footnote{Here is the sample footnote.}; in the Texinfo +source, it looks like this:@refill + +@example +@dots{}a sample footnote@@footnote@{Here is the sample +footnote.@}; in the Texinfo source@dots{} +@end example + +@strong{Warning:} Don't use footnotes in the argument of the +@code{@@item} command for a @code{@@table} table. This doesn't work, and +because of limitations of @TeX{}, there is no way to fix it. You must +put the footnote into the body text of the table. + +In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line.@refill + +In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: @samp{(1)}.@refill + + +@node Footnote Styles, , Footnote Commands, Footnotes +@section Footnote Styles + +Info has two footnote styles, which determine where the text of the +footnote is located:@refill + +@itemize @bullet +@cindex @samp{@r{End}} node footnote style +@item +In the `End' node style, all the footnotes for a single node +are placed at the end of that node. The footnotes are separated from +the rest of the node by a line of dashes with the word +@samp{Footnotes} within it. Each footnote begins with an +@samp{(@var{n})} reference mark.@refill + +@need 700 +@noindent +Here is an example of a single footnote in the end of node style:@refill + +@example +@group + --------- Footnotes --------- + +(1) Here is a sample footnote. +@end group +@end example + +@cindex @samp{@r{Separate}} footnote style +@item +In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a ``footnote reference'' follows +each @samp{(@var{n})} reference mark in the body of the +node. The footnote reference is actually a cross reference +which you use to reach the footnote node.@refill + +The name of the node containing the footnotes is constructed +by appending @w{@samp{-Footnotes}} to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the @file{Footnotes} node is +@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an +`Up' node pointer that leads back to its parent node.@refill + +@noindent +Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style:@refill + +@smallexample +@group +File: texinfo.info Node: Overview-Footnotes, Up: Overview + +(1) Note that the first syllable of "Texinfo" is +pronounced like "speck", not "hex". @dots{} +@end group +@end smallexample +@end itemize + +A Texinfo file may be formatted into an Info file with either footnote +style.@refill + +@findex footnotestyle +Use the @code{@@footnotestyle} command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either @samp{end} for the end node style or +@samp{separate} for the separate node style. + +@need 700 +For example, + +@example +@@footnotestyle end +@end example +@noindent +or +@example +@@footnotestyle separate +@end example + +Write an @code{@@footnotestyle} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you +include the @code{@@footnotestyle} command between the start-of-header +and end-of-header lines, the region formatting commands will format +footnotes as specified.)@refill + +If you do not specify a footnote style, the formatting commands use +their default style. Currently, @code{texinfo-format-buffer} and +@code{texinfo-format-region} use the `separate' style and +@code{makeinfo} uses the `end' style.@refill + +@c !!! note: makeinfo's --footnote-style option overrides footnotestyle +@ignore +If you use @code{makeinfo} to create the Info file, the +@samp{--footnote-style} option determines which style is used, +@samp{end} for the end of node style or @samp{separate} for the +separate node style. Thus, to format the Texinfo manual in the +separate node style, you would use the following shell command:@refill + +@example +makeinfo --footnote-style=separate texinfo.texi +@end example + +@noindent +To format the Texinfo manual in the end of node style, you would +type:@refill + +@example +makeinfo --footnote-style=end texinfo.texi +@end example +@end ignore +@ignore +If you use @code{texinfo-format-buffer} or +@code{texinfo-format-region} to create the Info file, the value of the +@code{texinfo-footnote-style} variable controls the footnote style. +It can be either @samp{"separate"} for the separate node style or +@samp{"end"} for the end of node style. (You can change the value of +this variable with the @kbd{M-x edit-options} command (@pxref{Edit +Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or +with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining +and Setting Variables, emacs, The GNU Emacs Manual}).@refill + +The @code{texinfo-footnote-style} variable also controls the style if +you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} +command in Emacs.@refill +@end ignore +This chapter contains two footnotes.@refill + + +@node Conditionals, Macros, Footnotes, Top +@comment node-name, next, previous, up +@chapter Conditionally Visible Text +@cindex Conditionally visible text +@cindex Text, conditionally visible +@cindex Visibility of conditional text +@cindex If text conditionally visible + +Sometimes it is good to use different text for a printed manual and +its corresponding Info file. In this case, you can use the +@dfn{conditional commands} to specify which text is for the printed manual +and which is for the Info file.@refill + +@menu +* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. +* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. +* Raw Formatter Commands:: Using raw @TeX{} or HTML commands. +* set clear value:: Designating which text to format (for + all output formats); and how to set a + flag to a string that you can insert. +@end menu + +@node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals +@ifinfo +@heading Conditional Commands +@end ifinfo + +@findex ifinfo +@code{@@ifinfo} begins segments of text that should be ignored +by @TeX{} when it +typesets the printed manual. The segment of text appears only +in the Info file. +The @code{@@ifinfo} command should appear on a line by itself; end +the Info-only text with a line containing @code{@@end ifinfo} by +itself. At the beginning of a Texinfo file, the Info permissions are +contained within a region marked by @code{@@ifinfo} and @code{@@end +ifinfo}. (@xref{Info Summary and Permissions}.)@refill + +@findex iftex +@findex ifhtml +The @code{@@iftex} and @code{@@end iftex} commands are similar to the +@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they +specify text that will appear in the printed manual but not in the Info +file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which +specify text to appear only in HTML output.@refill + +For example, + +@example +@@iftex +This text will appear only in the printed manual. +@@end iftex +@@ifinfo +However, this text will appear only in Info. +@@end ifinfo +@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. +@end ifinfo + +@noindent +Note how you only see one of the two lines, depending on whether you +are reading the Info version or the printed version of this +manual.@refill + +The @code{@@titlepage} command is a special variant of @code{@@iftex} that +is used for making the title and copyright pages of the printed +manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill + + +@node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals +@section Conditional Not Commands +@findex ifnothtml +@findex ifnotinfo +@findex ifnottex + +You can specify text to be included in any output format @emph{other} +than some given one with the @code{@@ifnot@dots{}} commands: +@example +@@ifnothtml @dots{} @@end ifnothtml +@@ifnotinfo @dots{} @@end ifnotinfo +@@ifnottex @dots{} @@end ifnottex +@end example +@noindent +(The @code{@@ifnot@dots{}} command and the @code{@@end} command must +actually appear on lines by themselves.) + +If the output file is not being made for the given format, the region is +included. Otherwise, it is ignored. + +The regions delimited by these commands are ordinary Texinfo source as +with @code{@@iftex}, not raw formatter source as with @code{@@tex}. + + +@node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals +@section Raw Formatter Commands +@cindex @TeX{} commands, using ordinary +@cindex HTML commands, using ordinary +@cindex Raw formatter commands +@cindex Ordinary @TeX{} commands, using +@cindex Ordinary HTML commands, using +@cindex Commands using raw @TeX{} +@cindex Commands using raw HTML +@cindex plain @TeX{} + +Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you +can embed some raw @TeX{} commands. Info will ignore these commands +since they are only in that part of the file which is seen by @TeX{}. +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, many features of plain @TeX{} will not work, as they are +overridden by Texinfo 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. (The @code{@@tex} command also causes Info to ignore the +region, like the @code{@@iftex} command.) The sole exception is that +@code{@@} chracter still introduces a command, so that @code{@@end tex} +can be recognized properly. + +@cindex Mathematical expressions +For 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 ifhtml} for a region of raw HTML (again, except that @code{@@} is +still the escape character, so the @code{@@end} command can be +recognized.) + + +@node set clear value, , Raw Formatter Commands, Conditionals +@comment node-name, next, previous, up +@section @code{@@set}, @code{@@clear}, and @code{@@value} + +You can direct the Texinfo formatting commands to format or ignore parts +of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, +and @code{@@ifclear} commands.@refill + +In addition, you can use the @code{@@set @var{flag}} command to set the +value of @var{flag} to a string of characters; and use +@code{@@value@{@var{flag}@}} to insert that string. You can use +@code{@@set}, for example, to set a date and use @code{@@value} to +insert the date in several places in the Texinfo file.@refill + +@menu +* ifset ifclear:: Format a region if a flag is set. +* value:: Replace a flag with a string. +* value Example:: An easy way to update edition information. +@end menu + + +@node ifset ifclear, value, set clear value, set clear value +@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. + +Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a +@var{flag}; a @dfn{flag} can be any single word. The format for the +command looks like this:@refill +@findex set + +@example +@@set @var{flag} +@end example + +Write the conditionally formatted text between @code{@@ifset @var{flag}} +and @code{@@end ifset} commands, like this:@refill + +@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:@refill + +@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.@refill + +@findex clear +Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear}, +a flag. Clearing a flag is the opposite of setting a flag. The +command looks like this:@refill + +@example +@@clear @var{flag} +@end example + +@noindent +Write the command on a line of its own. + +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.@refill + +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:@refill + +@example +@@ifclear @var{flag} +@end example + +@need 700 +In brief, the commands are:@refill + +@table @code +@item @@set @var{flag} +Tell the Texinfo formatting commands that @var{flag} is set.@refill + +@item @@clear @var{flag} +Tell the Texinfo formatting commands that @var{flag} is cleared.@refill + +@item @@ifset @var{flag} +If @var{flag} is set, tell the Texinfo formatting commands to format +the text up to the following @code{@@end ifset} command.@refill + +If @var{flag} is cleared, tell the Texinfo formatting commands to +ignore text up to the following @code{@@end ifset} command.@refill + +@item @@ifclear @var{flag} +If @var{flag} is set, tell the Texinfo formatting commands to ignore +the text up to the following @code{@@end ifclear} command.@refill + +If @var{flag} is cleared, tell the Texinfo formatting commands to +format the text up to the following @code{@@end ifclear} +command.@refill +@end table + +@node value, value Example, ifset ifclear, set clear value +@subsection @code{@@value} +@findex value + +You can use the @code{@@set} command to specify a value for a flag, +which is expanded by the @code{@@value} command. The value is a string +a characters. + +Write the @code{@@set} command like this: + +@example +@@set foo This is a string. +@end example + +@noindent +This sets the value of @code{foo} to ``This is a string.'' + +The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with +the string to which @var{flag} is set.@refill + +Thus, when @code{foo} is set as shown above, the Texinfo formatters convert + +@example +@group +@@value@{foo@} +@exdent @r{to} +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 an empty string. + +If you clear a previously set flag with an @code{@@clear @var{flag}} +command, a subsequent @code{@@value@{flag@}} command is invalid and the +string is replaced with an error message that says @samp{@{No value for +"@var{flag}"@}}. + +For example, if you set @code{foo} as follows:@refill + +@example +@@set how-much very, very, very +@end example + +@noindent +then the formatters transform + +@example +@group +It is a @@value@{how-much@} wet day. +@exdent @r{into} +It is a very, very, very wet day. +@end group +@end example + +If you write + +@example +@@clear how-much +@end example + +@noindent +then the formatters transform + +@example +@group +It is a @@value@{how-much@} wet day. +@exdent @r{into} +It is a @{No value for "how-much"@} wet day. +@end group +@end example + +@node value Example, , value, set clear value +@subsection @code{@@value} Example + +You can use the @code{@@value} command to limit the number of places you +need to change when you record an update to a manual. +Here is how it is done in @cite{The GNU Make Manual}: + +@need 1000 +@noindent +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 + +@need 750 +@noindent +Write text for the first @code{@@ifinfo} section, for people reading the +Texinfo file: + +@example +@group +This is Edition @@value@{EDITION@}, +last updated @@value@{UPDATED@}, +of @@cite@{The GNU Make Manual@}, +for @@code@{make@}, Version @@value@{VERSION@}. +@end group +@end example + +@need 1000 +@noindent +Write text for the title page, for people reading the printed manual: +@c List only the month and the year since that looks less fussy on a +@c printed cover than a date that lists the day as well. + +@example +@group +@@title GNU Make +@@subtitle A Program for Directing Recompilation +@@subtitle Edition @@value@{EDITION@}, @dots{} +@@subtitle @@value@{UPDATE-MONTH@} +@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.) + +@need 750 +@noindent +Write text for the Top node, for people reading the Info file: + +@example +@group +This is Edition @@value@{EDITION@} +of the @@cite@{GNU Make Manual@}, +last updated @@value@{UPDATED@} +for @@code@{make@} Version @@value@{VERSION@}. +@end group +@end example + +@need 950 +After you format the manual, the text in the first @code{@@ifinfo} +section looks like this: + +@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 + +When you update the manual, change only the values of the flags; you do +not need to rewrite the three sections. + + +@node Macros, Format/Print Hardcopy, Conditionals, Top +@chapter Macros: Defining New Texinfo Commands +@cindex Macros +@cindex Defining new Texinfo commands +@cindex New Texinfo commands, defining +@cindex Texinfo commands, defining new +@cindex User-defined Texinfo commands + +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. (This has nothing to do with the +@code{@@defmac} command, which is for documenting macros in the subject +of the manual; @pxref{Def Cmd Template}.) + +@menu +* Defining Macros:: Both defining and undefining new commands. +* Invoking Macros:: Using a macro, once you've defined it. +@end menu + + +@node Defining Macros, Invoking Macros, Macros, Macros +@section Defining Macros +@cindex Defining macros +@cindex Macro definitions + +@findex macro +You use the Texinfo @code{@@macro} command to define a macro. For example: + +@example +@@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@} +@var{text} @dots{} \@var{param1}\ @dots{} +@@end macro +@end example + +The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to +arguments supplied when the macro is subsequently used in the document +(see the next section). + +If a macro needs no parameters, you can define it either with an empty +list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro +foo}). + +@cindex Body of a macro +@cindex Mutually recursive macros +@cindex Recursion, mutual +The definition or @dfn{body} of the macro can contain any Texinfo +commands, including previously-defined macros. (It is not possible to +have mutually recursive Texinfo macros.) In the body, instances of a +parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in +the example above, are replaced by the corresponding argument from the +macro invocation. + +@findex unmacro +@cindex Macros, undefining +@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, , Defining Macros, Macros +@section Invoking Macros +@cindex Invoking 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{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@} +@end example + +@noindent and the result will be just as if you typed the body of +@var{macro-name} at that spot. For example: + +@example +@@macro foo @{p, q@} +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. To +insert a comma, brace, or backslash in an argument, prepend a backslash, +as in + +@example +@@@var{macro-name} @{\\\@{\@}\,@} +@end example + +@noindent +which will pass the (almost certainly error-producing) argument +@samp{\@{@},} to @var{macro-name}. + +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: + +@display +Twice: aah, aah. +@end display + + +@node Format/Print Hardcopy, Create an Info File, Macros, Top +@comment node-name, next, previous, up +@chapter Format and Print Hardcopy +@cindex Format and print hardcopy +@cindex 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.@refill + +If you are using GNU Emacs, you can use commands provided by Texinfo +mode instead of shell commands. In addition to the three commands to +format a file, sort the indices, and print the result, Texinfo mode +offers key bindings for commands to recenter the output buffer, show the +print queue, and delete a job from the print queue.@refill + +@menu +* Use TeX:: Use @TeX{} to format for hardcopy. +* Format with tex/texindex:: How to format in a shell. +* Format with texi2dvi:: A simpler way to use the shell. +* Print with lpr:: How to print. +* Within Emacs:: How to format and print from an Emacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using Emacs's compile command. +* Requirements Summary:: @TeX{} formatting requirements summary. +* Preparing for TeX:: What you need to do to use @TeX{}. +* Overfull hboxes:: What are and what to do with overfull hboxes. +* smallbook:: How to print small format books and manuals. +* A4 Paper:: How to print on European A4 paper. +* Cropmarks and Magnification:: How to print marks to indicate the size + of pages and how to print scaled up output. +@end menu + +@node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy +@ifinfo +@heading Use @TeX{} +@end ifinfo + +The typesetting program called @TeX{} is used for formatting a Texinfo +file. @TeX{} is a very powerful typesetting program and, if used right, +does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain +@TeX{}}, for information on how to obtain @TeX{}.) + +The @code{makeinfo}, @code{texinfo-format-region}, and +@code{texinfo-format-buffer} commands read the very same @@-commands +in the Texinfo file as does @TeX{}, but process them differently to +make an Info file; see @ref{Create an Info File}.@refill + +@node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Format using @code{tex} and @code{texindex} +@cindex Shell formatting with @code{tex} and @code{texindex} +@cindex Formatting with @code{tex} and @code{texindex} +@cindex DVI file + +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 printe (see the following sections). + +@pindex texindex +The @code{tex} formatting command itself does not sort the indices; it +writes an output file of unsorted index data. (The @code{texi2dvi} +command automatically generates indices; see @ref{Format with texi2dvi,, +Format using @code{texi2dvi}}.) To generate a printed index after +running the @code{tex} command, you first need a sorted index to work +from. The @code{texindex} command sorts indices. (The source file +@file{texindex.c} comes as part of the standard Texinfo distribution, +among other places.)@refill + +@cindex Names of index files +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}.@refill + +@need 1000 +@cindex Wildcards +@cindex Globbing +Instead of specifying all the unsorted index file names explicitly, you +can use @samp{??} as shell wildcards and give the command in this +form:@refill + +@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.)@refill + +For each file specified, @code{texindex} generates a sorted index file +whose name is made by appending @samp{s} to the input file name. The +@code{@@printindex} command knows to look for a file of that name +(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the +raw index output file.@refill + +After you have sorted the indices, you need to rerun the @code{tex} +formatting command on the Texinfo file. This regenerates the DVI file, +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 four 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 +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}. + +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.@refill + + +@node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Format using @code{texi2dvi} +@pindex texi2dvi @r{(shell script)} + +The @code{texi2dvi} command automatically runs both @code{tex} and +@code{texindex} as many times as necessary to produce a DVI file with +up-to-date, sorted indices. It simplifies the +@code{tex}---@code{texindex}---@code{tex} sequence described in the +previous section. + +The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your +shell prompt):@refill + +@example +prompt$ @kbd{texi2dvi @var{filename}@dots{}} +@end example + +For a list of options, run @samp{texi2dvi --help}. + + +@node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Shell Print Using @code{lpr -d} +@pindex lpr @r{(DVI print command)} + +The precise command to print a DVI file depends on your system +installation, but @samp{lpr -d} is common. The command may require the +DVI file name without any extension or with a @samp{.dvi} +extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.) + +The following commands, for example, will (probably) 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.)@refill + +@need 1000 +Using the @code{texi2dvi} shell script, you simply need type:@refill + +@example +@group +texi2dvi bison.texinfo +lpr -d bison.dvi +@end group +@end example + +@node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy +@comment node-name, next, previous, up +@section From an Emacs Shell +@cindex Print, format from Emacs shell +@cindex Format, print from Emacs shell +@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{Format/Print +Hardcopy, , Format and Print Hardcopy}, for details.@refill + +You can switch to and from the shell buffer while @code{tex} is +running and do other editing. If you are formatting a long document +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 +@ifinfo + +@xref{Texinfo Mode Printing}, for more information about formatting +and printing in Texinfo mode.@refill +@end ifinfo + +@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy +@section Formatting and Printing in Texinfo Mode +@cindex Region printing in Texinfo mode +@cindex Format and print in Texinfo mode +@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 +@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 +edit-options} command (@pxref{Edit Options, , Editing Variable Values, +emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command +(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU +Emacs Manual}), or with your @file{.emacs} initialization file +(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill + +@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Using the Local Variables List +@cindex Local variables +@cindex Compile command for formatting +@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, Preparing for TeX, Compile-Command, Format/Print Hardcopy +@comment node-name, next, previous, up +@section @TeX{} Formatting Requirements Summary +@cindex Requirements for formatting +@cindex Minimal requirements for formatting +@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.) + +@iftex +For more information, see +@ref{settitle, , @code{@@settitle}}, +@ref{setchapternewpage, , @code{@@setchapternewpage}}, +@ref{Headings, ,Page Headings}, +@ref{Titlepage & Copyright Page}, +@ref{Printing Indices & Menus}, and +@ref{Contents}. +@end iftex +@noindent +@ifinfo +For more information, see@* +@ref{settitle, , @code{@@settitle}},@* +@ref{setchapternewpage, , @code{@@setchapternewpage}},@* +@ref{Headings, ,Page Headings},@* +@ref{Titlepage & Copyright Page},@* +@ref{Printing Indices & Menus}, and@* +@ref{Contents}. +@end ifinfo + + +@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Preparing to Use @TeX{} +@cindex Preparing to use @TeX{} +@cindex @TeX{} input initialization +@cindex @code{TEXINPUTS} environment variable +@vindex TEXINPUTS +@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 you +have told it to input with the @samp{\input texinfo} command at the +beginning of the first line. The @file{texinfo.tex} file tells @TeX{} +how to handle @@-commands; it is included in all standard GNU +distributions. + +@pindex texinfo.tex@r{, installing} +Usually, the @file{texinfo.tex} file is put under the default directory +that contains @TeX{} macros +(@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when +GNU Emacs or other GNU software is installed. In this case, @TeX{} will +find the file and you do not need to do anything special. +Alternatively, 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} in the same place as +@file{texinfo.tex}, if it is not already installed from another +distribution. This file is needed to support the @code{@@image} command +(@pxref{Images}). + +@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{} at the @code{@@setfilename} +command (@pxref{setfilename,, @code{@@setfilename}}). You can put any +commands you like there according to local site-wide conventions, and +they will be read by @TeX{} when processing any Texinfo document. For +example, if @file{texinfo.cnf} contains the a single line +@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will +be processed with that page size in effect. If you have nothing to put +in @file{texinfo.cnf}, you do not need to create it. + +@vindex TEXINPUTS +If neither of the above locations for these system files suffice for +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:/usr/lib/tex/macros +@end example + +@need 1000 +In a @file{.profile} file, you could use the following @code{sh} command +sequence: + +@example +@group +TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros +export TEXINPUTS +@end group +@end example + +@noindent +This would cause @TeX{} to look for @file{\input} file first in the current +directory, indicated by the @samp{.}, then in a hypothetical user's +@file{me/mylib} directory, and finally in a system directory. + + +@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Overfull ``hboxes'' +@cindex Overfull @samp{hboxes} +@cindex @samp{hboxes}, overfull +@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:@refill + +@example +Overfull \hbox (20.76302pt too wide) +@end example + +@noindent +(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. +The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill + +@TeX{} also provides the line number in the Texinfo source file and +the text of the offending line, which is marked at all the places that +@TeX{} knows how to hyphenate words. +@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, +for more information about typesetting errors.@refill + +If the Texinfo file has an overfull hbox, you can rewrite the sentence +so the overfull hbox does not occur, or you can decide to leave it. A +small excursion into the right margin often does not matter and may not +even be noticeable.@refill + +@cindex Black rectangle in hardcopy +@cindex Rectangle, ugly, black in hardcopy +However, unless told otherwise, @TeX{} will print a large, ugly, black +rectangle beside the line that contains the overfull hbox. This is so +you will notice the location of the problem if you are correcting a +draft.@refill + +@need 1000 +@findex finalout +To prevent such a monstrosity from marring your final printout, write +the following in the beginning of the Texinfo file on a line of its own, +before the @code{@@titlepage} command:@refill + +@example +@@finalout +@end example + +@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Printing ``Small'' Books +@findex smallbook +@cindex Small book size +@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 regular sized books are often about 7 by 9.25 inches, this +command might better have been called the @code{@@regularbooksize} +command, but it came to be called the @code{@@smallbook} command by +comparison to the 8.5 by 11 inch format.)@refill + +If you write the @code{@@smallbook} command between the +start-of-header and end-of-header lines, the Texinfo mode @TeX{} +region formatting command, @code{texinfo-tex-region}, will format the +region in ``small'' book size (@pxref{Start of Header}).@refill + +The Free Software Foundation distributes printed copies of @cite{The GNU +Emacs Manual} and other manuals in the ``small'' book size. +@xref{smallexample & smalllisp, , @code{@@smallexample} and +@code{@@smalllisp}}, for information about commands that make it easier +to produce examples for a smaller manual.@refill + +Alternatively, to avoid embedding this physical paper size in your +document, use @code{texi2dvi} to format your document (@pxref{Format +with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then +other people do not have to change the document source file to format it +differently. + + +@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Printing on A4 Paper +@cindex A4 paper, printing on +@cindex Paper size, European A4 +@cindex European A4 paper +@findex afourpaper + +You can tell @TeX{} to typeset a document for printing on European size +A4 paper with the @code{@@afourpaper} command. Write the 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:@refill + +For example, this is how you would write the header for this manual:@refill + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename texinfo +@@settitle Texinfo +@@syncodeindex vr fn +@@iftex +@@afourpaper +@@end iftex +@@c %**end of header +@end group +@end example + +Alternatively, to avoid embedding this physical paper size in your +document, use @code{texi2dvi} to format your document (@pxref{Format +with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then +other people do not have to change the document source file to format it +differently. + +@pindex texinfo.cnf +Another alternative: put the @code{@@afourpaper} command in the file +@file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex} +there.) This will automatically typeset all the Texinfo documents at +your site with that paper size in effect. + + +@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy +@comment node-name, next, previous, up +@section Cropmarks and Magnification + +@findex cropmarks +@cindex Cropmarks for printing +@cindex Printing cropmarks +You can attempt to direct @TeX{} to print cropmarks at the corners of +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 the +@file{texinfo.tex} definitions file.@refill + +@findex mag @r{(@TeX{} command)} +@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:@refill + +@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 using a larger-than-normal master.@refill + +Depending on your system, @code{\mag} may not work or may work only at +certain magnifications. Be prepared to experiment.@refill + +@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top +@comment node-name, next, previous, up +@chapter Creating an Info File +@cindex Creating an Info file +@cindex Info, creating an on-line file +@cindex Formatting a file for Info + +@code{makeinfo} is a utility that converts a Texinfo file into an Info +file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are +GNU Emacs functions that do the same.@refill + +A Texinfo file must contain an @code{@@setfilename} line near its +beginning, otherwise the Info formatting commands will fail. + +For information on installing the Info file in the Info system, see +@ref{Install an Info File}.@refill + +@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, Invoking makeinfo, Create an Info File, Create an Info File +@ifinfo +@heading @code{makeinfo} Preferred +@end ifinfo + +The @code{makeinfo} utility creates an Info file from a Texinfo source +file more quickly than either of the Emacs formatting commands and +provides better error messages. We recommend it. @code{makeinfo} is a +C program that is independent of Emacs. You do not need to run Emacs to +use @code{makeinfo}, which means you can use @code{makeinfo} on machines +that are too small to run Emacs. You can run @code{makeinfo} in +any one of three ways: from an operating system shell, from a shell +inside Emacs, or by typing a key command in Texinfo mode in Emacs. +@refill + +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}.@refill + +@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File +@section Running @code{makeinfo} from a Shell + +To create an Info file from a Texinfo file, type @code{makeinfo} +followed by the name of the Texinfo file. Thus, to create the Info +file for Bison, type the following to the shell: +is the prompt):@refill + +@example +makeinfo bison.texinfo +@end example + +(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill + +@ifinfo +Sometimes you will want to specify options. For example, if you wish +to discover which version of @code{makeinfo} you are using, +type:@refill + +@example +makeinfo --version +@end example + +@xref{makeinfo options}, for more information. +@end ifinfo + + +@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File +@comment node-name, next, previous, up +@section Options for @code{makeinfo} +@cindex @code{makeinfo} options +@cindex Options for @code{makeinfo} + +The @code{makeinfo} command takes a number of options. Most often, +options are used to set the value of the fill column and specify the +footnote style. 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.@refill + +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:@refill + +@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.@refill + +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 --error-limit=@var{limit} +@opindex --error-limit=@var{limit} +Set the maximum number of errors that @code{makeinfo} will report +before exiting (on the assumption that continuing would be useless); +default 100. + +@need 150 +@item --fill-column=@var{width} +@opindex --fill-column=@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. + +@item --footnote-style=@var{style} +@opindex --footnote-style=@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. + +@item --force +@opindex --force +Ordinarily, if the input file has errors, the output files are not +created. With this option, they are preserved. + +@item --help +@opindex --help +Print a usage message listing all available options, then exit successfully. + +@item -I @var{dir} +@opindex -I @var{dir} +Add @code{dir} to the directory search list for finding files that are +included using the @code{@@include} command. By default, +@code{makeinfo} searches only the current directory. + +@item --no-headers +@opindex --no-headers +Do not include menus or node lines in the output. This results in an +@sc{ascii} file that you cannot read in Info since it does not contain +the requisite nodes or menus. It is primarily useful to extract certain +pieces of a manual into separate files to be included in a distribution, +such as @file{INSTALL} files. + +@item --no-split +@opindex --no-split +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, each one approximately 50k bytes. + +@item --no-pointer-validate +@itemx --no-validate +@opindex --no-pointer-validate +@opindex --no-validate +Suppress the pointer-validation phase of @code{makeinfo}. Normally, +after a Texinfo file is processed, some consistency checks are made to +ensure that cross references can be resolved, etc. +@xref{Pointer Validation}.@refill + +@item --no-warn +@opindex --no-warn +Suppress warning messages (but @emph{not} error messages). You might +want this if the file you are creating has examples of Texinfo cross +references within it, and the nodes that are referenced do not actually +exist. + +@item --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 --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. + +@item -P @var{dir} +@opindex -P @var{dir} +Prepend @code{dir} to the directory search list for @code{@@include}. +See @samp{-I} for more details. + +@item --paragraph-indent=@var{indent} +@opindex --paragraph-indent=@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 that number of spaces. +@end table + +@item --reference-limit=@var{limit} +@opindex --reference-limit=@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 -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 +@opindex --version +Print the version number, then exit successfully. + +@end table + + +@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File +@section Pointer Validation +@cindex Pointer validation with @code{makeinfo} +@cindex Validation of pointers + +If you do not suppress pointer-validation, @code{makeinfo} will check +the validity of the final Info file. Mostly, this means ensuring that +nodes you have referenced really exist. Here is a complete list of what +is checked:@refill + +@enumerate +@item +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 `Previous' node must also be pointed to by a `Next' node.@refill + +@item +Every node except the `Top' node must have an `Up' pointer.@refill + +@item +The node referenced by an `Up' pointer must contain a reference to the +current node in some manner other than through a `Next' reference. +This includes menu entries and cross references.@refill + +@item +If the `Next' reference of a node is not the same as the `Next' reference +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 +@end enumerate + +@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File +@section Running @code{makeinfo} inside Emacs +@cindex Running @code{makeinfo} in Emacs +@cindex @code{makeinfo} inside Emacs +@cindex Shell, running @code{makeinfo} in + +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 either @code{makeinfo-region} or +@code{makeinfo-buffer}, Emacs prompts for a file name, offering the +name of the visited file as the default. You can edit the default +file name in the minibuffer if you wish, before pressing @key{RET} to +start the @code{makeinfo} process.@refill + +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 created by +@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 +edit-options} or the @kbd{M-x set-variable} command, or by setting the +variable in your @file{.emacs} initialization file.@refill + +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 + +@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 ``Editing Variable Values,''``Examining and +Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs +Manual}. +@end iftex +@noindent +@ifinfo +For more information, see@* +@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* +@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* +@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* +@ref{makeinfo options, , Options for @code{makeinfo}}. +@end ifinfo + +@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File +@comment node-name, next, previous, up +@section The @code{texinfo-format@dots{}} Commands +@findex texinfo-format-region +@findex texinfo-format-buffer + +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} +Format the current region for Info. +@findex texinfo-format-region + +@item C-c C-e C-b +@itemx @code{texinfo-format-buffer} +Format the current buffer for Info. +@findex texinfo-format-buffer +@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, Tag and Split Files, texinfo-format commands, Create an Info File +@comment node-name, next, previous, up +@section Batch Formatting +@cindex Batch formatting for Info +@cindex Info batch formatting + +You can format Texinfo files for Info using @code{batch-texinfo-format} +and Emacs Batch mode. You can run Emacs in Batch mode from any shell, +including a shell inside of Emacs. (@xref{Command Switches, , Command +Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill + +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, , Batch Formatting, Create an Info File +@comment node-name, next, previous, up +@section 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 70,000 +bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the +large Info file into shorter @dfn{indirect} subfiles of about 50,000 +bytes each. Big files are split into smaller files so that Emacs does +not need to make a large buffer to hold the whole of a large Info +file; instead, Emacs allocates just enough memory for the small, split +off file that is needed at the time. This way, Emacs avoids wasting +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 @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.@refill + +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}.@refill + + +@node Install an Info File, Command List, Create an Info File, Top +@comment node-name, next, previous, up +@chapter Installing an Info File +@cindex Installing an Info file +@cindex Info file installation +@cindex @file{dir} directory for Info installation + +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, New Info File, Install an Info File, Install an Info File +@ifinfo +@heading The @file{dir} File +@end ifinfo + +For Info to work, the @file{info} directory must contain a file that +serves as a top level directory for the Info system. By convention, +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 +(Note that in this case, the @file{dir} file name is written in upper +case letters---it can be written in either upper or lower case. Info +has a feature that it will change the case of the file name to lower +case if it cannot find the name as written.)@refill +@c !!! Can any file name be written in upper or lower case, +@c or is dir a special case? +@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 + + +@node New Info File, Other Info Directories, Directory file, Install an Info File +@section Listing a New Info File +@cindex Adding a new info file +@cindex Listing a new info file +@cindex New info file, listing it in @file{dir} file +@cindex Info file, listing new one +@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}; 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, Installing Dir Entries, New Info File, Install an Info File +@comment node-name, next, previous, up +@section Info Files in Other Directories +@cindex Installing Info in another directory +@cindex Info installed in another directory +@cindex Another Info directory + +If an Info file is not in the @file{info} directory, there are three +ways to specify its location:@refill + +@itemize @bullet +@item +Write the pathname in the @file{dir} file as the second part of the +menu.@refill + +@item +If you are using Emacs, list the name of the file in a second @file{dir} +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 tells Emacs where to look for @file{dir} files. Emacs merges the +files named @file{dir} from each of the listed directories. (In Emacs +version 18, you can set the @code{Info-directory} variable to the name +of only one directory.)@refill + +@item +Specify the Info directory name in the @code{INFOPATH} environment +variable in your @file{.profile} or @file{.cshrc} initialization file. +(Only you and others who set this environment variable will be able to +find Info files whose location is specified this way.)@refill +@end itemize + +For example, to reach a test file in the @file{/home/bob/manuals} +directory, you could add an entry like this to the menu in the +@file{dir} file:@refill + +@example +* Test: (/home/bob/manuals/info-test). Bob's own test file. +@end example + +@noindent +In this case, the absolute file name of the @file{info-test} file is +written as the second part of the menu entry.@refill + +@vindex Info-directory-list +Alternatively, you could write the following in your @file{.emacs} +file:@refill + +@example +@group +(setq Info-directory-list + '("/home/bob/manuals" + "/usr/local/info")) +@end group +@end example + +@c reworded to avoid overfill hbox +This tells Emacs to merge the @file{dir} file from the +@file{/home/bob/manuals} directory with the @file{dir} file from the +@file{/usr/local/info} directory. Info will list the +@file{/home/bob/manuals/info-test} file as a menu entry in the +@file{/home/bob/manuals/dir} file.@refill + +@vindex INFOPATH +Finally, you can tell Info where to look by setting the @code{INFOPATH} +environment variable in your @file{.cshrc} or @file{.profile} file. If +you use a Bourne-compatible shell such as @code{sh} or @code{bash} for +your shell command interpreter, you set the @code{INFOPATH} environment +variable in the @file{.profile} initialization file; but if you use +@code{csh} or @code{tcsh}, you must set the variable in the +@file{.cshrc} initialization file. The two types of shells use +different syntax. + +@itemize @bullet +@item +In a @file{.cshrc} file, you could set the @code{INFOPATH} +variable as follows:@refill + +@smallexample +setenv INFOPATH .:~/manuals:/usr/local/emacs/info +@end smallexample + +@item +In a @file{.profile} file, you would achieve the same effect by +writing:@refill + +@smallexample +INFOPATH=.:$HOME/manuals:/usr/local/emacs/info +export INFOPATH +@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. + +@cindex @samp{:} @r{last in @code{INFOPATH}} +However you set @code{INFOPATH}, if its last character is a colon, this +is replaced by the default (compiled-in) path. This gives you a way to +augment the default path with new directories without having to list all +the standard places. For example (using @code{sh} syntax: + +@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. + + +@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File +@section Installing Info Directory Files + +When you install an Info file onto your system, you can use the program +@code{install-info} to update the Info directory file @file{dir}. +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 should +use the commands @code{@@dircategory} and @code{@@direntry} in the +Texinfo source file. Use @code{@@direntry} to specify the menu entry to +add to the Info directory file, and use @code{@@dircategory} to specify +which part of the Info directory to put it in. Here is how these +commands are used in this manual: + +@smallexample +@@dircategory Texinfo documentation system +@@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 one category; the new menu entry is added to the +Info directory file in each of the categories you specify. If you use +@code{@@direntry} more than once, each usage specifies one menu entry; +each of these menu entries is added to the directory in each of the +specified categories. + + +@node Invoking install-info, , Installing Dir Entries, Install an Info File +@section Invoking install-info + +@pindex install-info + +@code{install-info} inserts menu entries from an Info file into the +top-level @file{dir} file in the Info system (see the previous sections +for an explanation of how the @file{dir} file works). It's most often +run as part of software installation, or when constructing a 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 various +options (described below) that define them must be. There are no +compile-time defaults, and standard input is never used. +@code{install-info} can read only one info file and write only one dir +file per invocation. + +@cindex @file{dir}, created by @code{install-info} +If @var{dir-file} (however specified) does not exist, +@code{install-info} creates it if possible (with no entries). + +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} +@opindex --dir-file=@var{name} +Specify file name of the Info directory file. This is equivalent to +using the @var{dir-file} argument. + +@item --entry=@var{text} +@opindex --entry=@var{text} +Insert @var{text} as an Info directory entry; @var{text} should have the +form of an Info menu item line plus zero or more extra lines starting +with whitespace. If you specify more than one entry, they are all +added. If you don't specify any entries, they are determined from +information in the Info file itself. + +@item --help +@opindex --help +Display a usage message listing basic usage and all available options, +then exit successfully. + +@item --info-file=@var{file} +@opindex --info-file=@var{file} +Specify Info file to install in the directory. +This is equivalent to using the @var{info-file} argument. + +@item --info-dir=@var{dir} +@opindex --info-dir=@var{dir} +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 +@opindex --remove +Same as @samp{--delete}. + +@item --section=@var{sec} +@opindex --section=@var{sec} +Put this file's entries in section @var{sec} of the directory. If you +specify more than one section, all the entries are added in each of the +sections. If you don't specify any sections, they are determined from +information in the Info file itself. + +@item --version +@opindex --version +@cindex version number, finding +Display version information and exit successfully. + +@end table + + +@node Command List, Tips, Install an Info File, Top +@appendix @@-Command List +@cindex Alphabetical @@-command list +@cindex List of @@-commands +@cindex @@-command list + +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.@refill + +@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. Do not end a paragraph that uses @code{@@*} with +an @code{@@refill} command. @xref{Line Breaks}.@refill + +@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 @@: +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}.@refill + +@item @@= +Generate a macro (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{Braces Atsigns, , Inserting @@ and braces}. + +@item @@^ +@itemx @@` +Generate a circumflex (hat) or grave accent, respectively, over the next +character, as in @^o. +@xref{Inserting Accents}. + +@item @@@{ +Stands for a left brace, @samp{@{}. +@xref{Braces Atsigns, , Inserting @@ and braces}. + +@item @@@} +Stands for a right-hand brace, @samp{@}}.@* +@xref{Braces Atsigns, , Inserting @@ and braces}. + +@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 @@AE@{@} +@itemx @@ae@{@} +Generate the uppercase and lowercase AE ligatures, respectively: +@AE{}, @ae{}. @xref{Inserting Accents}. + +@item @@afourpaper +Change page dimensions for the A4 paper size. +Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}. +@xref{A4 Paper}. + +@item @@appendix @var{title} +Begin an appendix. The title appears in the table +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, , Comments}.@refill + +@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 @@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, , Comments}.@refill + +@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 a copyright symbol. @xref{copyright symbol, , +@code{@@copyright}}.@refill + +@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 + +@c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96. +@item @@definfoenclose @var{new-command}, @var{before}, @var{after}, +Create new @@-command for Info that marks text by enclosing it in +strings that precede and follow the text. Write definition inside of +@code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized +Highlighting}.@refill + +@item @@defivar @var{class} @var{instance-variable-name} +@itemx @@defivarx @var{class} @var{instance-variable-name} +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{macro-name} @var{arguments}@dots{} +@itemx @@defmacx @var{macro-name} @var{arguments}@dots{} +Format a description for a macro. The command is equivalent to +@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and +@ref{deffnx,, Def Cmds in Detail}. + +@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{deffnx,, Def Cmds in Detail}. + +@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{deffnx,, Def Cmds in Detail}. + +@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} +@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} +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 @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} +@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} +Format a description for a typed method in object-oriented programming. +Takes as arguments the name of the class of the method, the return type +of the method, the name of the method, and its arguments, if any. +@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. + +@item @@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 @@deftypevar @var{data-type} @var{variable-name} +@itemx @@deftypevarx @var{data-type} @var{variable-name} +Format a description for a variable in a typed language. The command is +equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition +Commands}, and @ref{deffnx,, Def Cmds in Detail}. + +@item @@defun @var{function-name} @var{arguments}@dots{} +@itemx @@defunx @var{function-name} @var{arguments}@dots{} +Format a description for functions. The command is equivalent to +@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. +@xref{Installing Dir Entries}. + +@need 100 +@item @@display +Begin a kind of example. Indent text, do not fill, do not select a +new font. Pair with @code{@@end display}. @xref{display, , +@code{@@display}}.@refill + +@item @@dmn@{@var{dimension}@} +Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a +thin space before @var{dimension}. No effect in Info. +@xref{dmn, , @code{@@dmn}}.@refill + +@item @@dotaccent@{@var{c}@} +Generate a dot accent over the character @var{c}, as in @dotaccent{oo}. +@xref{Inserting Accents}. + +@item @@dots@{@} +Insert an ellipsis: @samp{@dots{}}. +@xref{dots, , @code{@@dots}}.@refill + +@item @@email@{@var{address}[, @var{displayed-text}]@} +Indicate an electronic mail address. +@xref{email, , @code{@@email}}.@refill + +@need 100 +@item @@emph@{@var{text}@} +Highlight @var{text}; text is displayed in @emph{italics} in printed +output, and surrounded by asterisks in Info. @xref{Emphasis, , +Emphasizing Text}. + +@item @@end @var{environment} +Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting +Commands,,@@-commands}. + +@item @@enddots@{@} +Generate an end-of-sentence of ellipsis, like this @enddots{} +@xref{dots,,@code{@@dots@{@}}}. + +@need 100 +@item @@enumerate [@var{number-or-letter}] +Begin a numbered list, using @code{@@item} for each entry. +Optionally, start list with @var{number-or-letter}. Pair with +@code{@@end enumerate}. @xref{enumerate, , +@code{@@enumerate}}.@refill + +@need 100 +@item @@equiv@{@} +Indicate to the reader the exact equivalence of two forms with a +glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill + +@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. Only allowed inside @code{@@iftex}. @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 @@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 + +@need 100 +@item @@findex @var{entry} +Add @var{entry} to the index of functions. @xref{Index Entries, , +Defining the Entries of an Index}.@refill + +@need 200 +@item @@flushleft +@itemx @@flushright +Left justify every line but leave the right end ragged. +Leave font as is. Pair with @code{@@end flushleft}. +@code{@@flushright} analogous. +@xref{flushleft & flushright, , @code{@@flushleft} and +@code{@@flushright}}.@refill + +@need 200 +@item @@footnote@{@var{text-of-footnote}@} +Enter a footnote. Footnote text is printed at the bottom of the page +by @TeX{}; Info may format in either `End' node or `Separate' node style. +@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{@@example} or @code{@@display}, +but do not narrow the margins and do not select the fixed-width font. +Pair with @code{@@end format}. @xref{example, , +@code{@@example}}.@refill + +@item @@ftable @var{formatting-command} +Begin a two-column table, using @code{@@item} for each entry. +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}.@refill + +@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 @@ifhtml +@itemx @@ifinfo +Begin a stretch of text that will be ignored by @TeX{} when it typesets +the printed manual. The text appears only in the HTML resp.@: Info +file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. +@xref{Conditionals}. + +@item @@ifnothtml +@itemx @@ifnotinfo +@itemx @@ifnottex +Begin a stretch of text that will be ignored in one output format but +not the others. The text appears only in the format not specified. +Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@: +@code{@@end ifnotinfo}. @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 a stretch of text that will not appear in the Info file, but +will be processed only by @TeX{}. Pair with @code{@@end iftex}. +@xref{Conditionals, , Conditionally Visible Text}.@refill + +@item @@ignore +Begin a stretch of text that will not appear in either the Info file +or the printed output. Pair with @code{@@end ignore}. +@xref{Comments, , Comments and Ignored Text}.@refill + +@item @@image@{@var{filename}, [@var{width}], [@var{height}]@} +Include graphics image in external @var{filename} scaled to the given +@var{width} and/or @var{height}. @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 @@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{Header, , The Texinfo File Header}.@refill + +@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{}. + +@c Possibly this can be tossed now that we have macros. --karl, 16sep96. +@c Yes, let's toss it, it's pretty weird. --karl, 15jun97. +@c @item @@global@@let@var{new-command}=@var{existing-command} +@c Equate a new highlighting command with an existing one. Only for +@c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end +@c iftex}. @xref{Customized Highlighting}.@refill + +@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 Example, , +@code{@@lisp}}.@refill + +@item @@lowersections +Change subsequent chapters to sections, sections to subsections, and so +on. @xref{Raise/lower sections, , @code{@@raisesections} and +@code{@@lowersections}}.@refill + +@item @@macro @var{macro-name} @{@var{params}@} +Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}. +Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining +Macros}. + +@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. In Info, the chapter +heading line is underlined with asterisks. @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, next, previous, 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 @@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. Only allowed inside @code{@@iftex}. @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 @@page +Start a new page in a printed manual. No effect in Info. +@xref{page, , @code{@@page}}.@refill + +@item @@paragraphindent @var{indent} +Indent paragraphs by @var{indent} number of spaces; delete indentation +if the value of @var{indent} is 0; and do not change indentation if +@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph +Indenting}.@refill + +@item @@pindex @var{entry} +Add @var{entry} to the index of programs. @xref{Index Entries, , Defining +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. Write command on a line of its own. Pair with +@code{@@end quotation}. @xref{quotation, , +@code{@@quotation}}.@refill + +@need 100 +@item @@r@{@var{text}@} +Print @var{text} in @r{roman} font. No effect in Info. +@xref{Fonts}.@refill + +@item @@raisesections +Change subsequent sections to chapters, subsections to sections, and so +on. @xref{Raise/lower sections, , @code{@@raisesections} and +@code{@@lowersections}}.@refill + +@need 300 +@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} +Make a reference. In a printed manual, the reference does not start +with a `See'. Follow command with a punctuation mark. Only the first +argument is mandatory. @xref{ref, , @code{@@ref}}.@refill + +@need 300 +@item @@refill +In Info, refill and indent the paragraph after all the other processing +has been done. No effect on @TeX{}, which always refills. This command +is no longer needed, since all formatters now automatically refill. +@xref{Refilling Paragraphs}.@refill + +@need 300 +@item @@result@{@} +Indicate the result of an expression to the reader with a special +glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill + +@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 @@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}}.@refill + +@item @@setchapternewpage @var{on-off-odd} +Specify whether chapters start on new pages, and if so, whether on +odd-numbered (right-hand) new pages. @xref{setchapternewpage, , +@code{@@setchapternewpage}}.@refill + +@item @@setfilename @var{info-file-name} +Provide a name to be used by the Info file. This command is essential +for @TeX{} formatting as well, even though it produces no output. +@xref{setfilename, , @code{@@setfilename}}.@refill + +@item @@settitle @var{title} +Provide a title for page headers in a printed manual. +@xref{settitle, , @code{@@settitle}}.@refill + +@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}}. + +@need 400 +@item @@smallbook +Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format +rather than the regular 8.5 by 11 inch format. @xref{smallbook, , +Printing Small Books}. Also, see @ref{smallexample & smalllisp, , +@code{@@smallexample} and @code{@@smalllisp}}.@refill + +@need 400 +@item @@smallexample +Indent text to indicate an example. Do not fill, select fixed-width +font. In @code{@@smallbook} format, print text in a smaller font than +with @code{@@example}. Pair with @code{@@end smallexample}. +@xref{smallexample & smalllisp, , @code{@@smallexample} and +@code{@@smalllisp}}.@refill + +@need 400 +@item @@smalllisp +Begin an example of Lisp code. Indent text, do not fill, select +fixed-width font. In @code{@@smallbook} format, print text in a +smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & +smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill + +@need 700 +@item @@sp @var{n} +Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill + +@item @@ss@{@} +Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. + +@need 700 +@item @@strong @var{text} +Emphasize @var{text} by typesetting it in a @strong{bold} font for the +printed manual and by surrounding it with asterisks for Info. +@xref{emph & strong, , Emphasizing Text}.@refill + +@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 + +@need 300 +@item @@syncodeindex @var{from-index} @var{into-index} +Merge the index named in the first argument into the index named in +the second argument, printing the entries from the first index in +@code{@@code} font. @xref{Combining Indices}.@refill + +@need 300 +@item @@synindex @var{from-index} @var{into-index} +Merge the index named in the first argument into the index named in +the second argument. Do not change the font of @var{from-index} +entries. @xref{Combining Indices}.@refill + +@need 100 +@item @@t@{@var{text}@} +Print @var{text} in a @t{fixed-width}, typewriter-like font. +No effect in Info. @xref{Fonts}.@refill + +@item @@tab +Separate columns in a multitable. @xref{Multitable Rows}. + +@need 400 +@item @@table @var{formatting-command} +Begin a two-column table, using @code{@@item} for each entry. Write +each first column entry on the same line as @code{@@item}. First +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 and copyright, , Inserting @TeX{} +and @copyright{}}.@refill + +@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 @@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 + +@need 400 +@item @@titlefont@{@var{text}@} +In a printed manual, print @var{text} in a larger than normal font. +Not relevant to Info, which does not have title pages. +@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} +and @code{@@sp} Commands}.@refill + +@need 300 +@item @@titlepage +Indicate to Texinfo the beginning of the title page. Write command on +a line of its own. Pair with @code{@@end titlepage}. Nothing between +@code{@@titlepage} and @code{@@end titlepage} appears in Info. +@xref{titlepage, , @code{@@titlepage}}.@refill + +@need 150 +@item @@today@{@} +Insert the current date, in `1 Jan 1900' style. @xref{Custom +Headings, , How to Make Your Own Headings}.@refill + +@item @@top @var{title} +In a Texinfo file to be formatted with @code{makeinfo}, identify the +topmost @code{@@node} line 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{@@ifinfo} and @code{@@end +ifinfo}. 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}@} +Define a cross reference to an external uniform resource locator for the +World Wide Web. @xref{url, , @code{@@url}}.@refill + +@item @@url@{@var{url}@} +Indicate text that is a uniform resource locator for the World Wide +Web. @xref{url, , @code{@@url}}.@refill + +@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 + +@need 400 +@item @@vindex @var{entry} +Add @var{entry} to the index of variables. @xref{Index Entries, , +Defining the Entries of an Index}.@refill + +@need 400 +@item @@vskip @var{amount} +In a printed manual, insert whitespace so as to push text on the +remainder of the page towards the bottom of the page. Used in +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 & Permissions, , +The Copyright Page and Printed Permissions}.@refill + +@need 400 +@item @@vtable @var{formatting-command} +Begin a two-column table, using @code{@@item} for each entry. +Automatically enter each of the items in the first column into the +index of variables. Pair with @code{@@end vtable}. The same as +@code{@@table}, except for indexing. @xref{ftable vtable, , +@code{@@ftable} and @code{@@vtable}}.@refill + +@need 400 +@item @@w@{@var{text}@} +Prevent @var{text} from being split across two lines. Do not end a +paragraph that uses @code{@@w} with an @code{@@refill} command. +@xref{w, , @code{@@w}}.@refill + +@need 400 +@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} +Make a reference that starts with `See' in a printed manual. Follow +command with a punctuation mark. Only the first argument is +mandatory. @xref{xref, , @code{@@xref}}.@refill +@end table + + +@node Tips, Sample Texinfo File, Command List, Top +@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 +the paragraph before the paragraph. + +@need 1000 +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 + +Write the edition and version numbers and date in three places in every +manual: + +@enumerate +@item +In the first @code{@@ifinfo} section, for people reading the Texinfo file. + +@item +In the @code{@@titlepage} section, for people reading the printed manual. + +@item +In the `Top' node, for people reading the Info file. +@end enumerate + +@noindent +Also, it helps to write a note before the first @code{@@ifinfo} +section to explain what you are doing. + +@need 800 +@noindent +For example: + +@example +@group +@@c ===> NOTE! <== +@@c Specify the edition and version numbers and date +@@c in *three* places: +@@c 1. First ifinfo section 2. title page 3. top node +@@c To find the locations, search for !!set +@end group + +@group +@@ifinfo +@@c !!set edition, date, version +This is Edition 4.03, January 1992, +of the @@cite@{GDB Manual@} for GDB Version 4.3. +@dots{} +@end group +@end example + +@noindent +---or use @code{@@set} and @code{@@value} +(@pxref{value Example, , @code{@@value} Example}). + +@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 similar 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 +@ifinfo +@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 ifinfo + +@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, readers find it hard to search for the +section.@refill + +Name such sections with a phrase beginning with the word +@w{`Invoking @dots{}'}, 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_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 File, Sample Permissions, Tips, Top +@appendix A Sample Texinfo File +@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, , A Short Sample Texinfo File}. + +@sp 1 +@example +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename sample.info +@@settitle Sample Document +@@c %**end of header + +@@setchapternewpage odd + +@@ifinfo +This is a short example of a complete Texinfo file. + +Copyright 1990 Free Software Foundation, Inc. +@@end ifinfo + +@@titlepage +@@sp 10 +@@comment The title is printed in a large font. +@@center @@titlefont@{Sample Title@} + +@@c The following two commands start the copyright page. +@@page +@@vskip 0pt plus 1filll +Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +@@end titlepage + +@@node Top, First Chapter, , (dir) +@@comment node-name, next, previous, up + +@@menu +* First Chapter:: The first chapter is the + only chapter in this sample. +* Concept Index:: This index has two entries. +@@end menu + +@@node First Chapter, Concept Index, Top, Top +@@comment node-name, next, previous, up +@@chapter First Chapter +@@cindex Sample index entry + +This is the contents of the first chapter. +@@cindex Another sample index entry + +Here is a numbered list. + +@@enumerate +@@item +This is the first item. + +@@item +This is the second item. +@@end enumerate + +The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} +commands transform a Texinfo file such as this into +an Info file; and @@TeX@{@} typesets it for a printed +manual. + +@@node Concept Index, , First Chapter, Top +@@comment node-name, next, previous, up +@@unnumbered Concept Index + +@@printindex cp + +@@contents +@@bye +@end example + + +@node Sample Permissions, Include Files, Sample Texinfo File, Top +@appendix Sample Permissions +@cindex Permissions +@cindex Copying permissions + +Texinfo files should contain sections that tell the readers that they +have the right to copy and distribute the Texinfo file, the Info file, +and the printed manual.@refill + +Also, if you are writing a manual about software, you should explain +that the software is free and either include the GNU General Public +License (GPL) or provide a reference to it. @xref{Distrib, , +Distribution, emacs, The GNU Emacs Manual}, for an example of the text +that could be used in the software ``Distribution'', ``General Public +License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, +, Texinfo Copying Conditions}, for an example of a brief explanation +of how the copying conditions provide you with rights. @refill + +@menu +* Inserting Permissions:: How to put permissions in your document. +* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. +* Titlepage Permissions:: Sample Titlepage copying permissions. +@end menu + +@node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions +@ifinfo +@appendixsec Inserting Permissions +@end ifinfo + +In a Texinfo file, the first @code{@@ifinfo} section usually begins +with a line that says what the file documents. This is what a person +reading the unprocessed Texinfo file or using the advanced Info +command @kbd{g *} sees first. @inforef{Expert, Advanced Info +commands, info}, for more information. (A reader using the regular +Info commands usually starts reading at the first node and skips +this first section, which is not in a node.)@refill + +In the @code{@@ifinfo} section, the summary sentence is followed by a +copyright notice and then by the copying permission notice. One of +the copying permission paragraphs is enclosed in @code{@@ignore} and +@code{@@end ignore} commands. This paragraph states that the Texinfo +file can be processed through @TeX{} and printed, provided the printed +manual carries the proper copying permission notice. This paragraph +is not made part of the Info file since it is not relevant to the Info +file; but it is a mandatory part of the Texinfo file since it permits +people to process the Texinfo file in @TeX{} and print the +results.@refill + +In the printed manual, the Free Software Foundation copying permission +notice follows the copyright notice and publishing information and is +located within the region delineated by the @code{@@titlepage} and +@code{@@end titlepage} commands. The copying permission notice is exactly +the same as the notice in the @code{@@ifinfo} section except that the +paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is +not part of the notice.@refill + +To make it simple to insert a permission notice into each section of +the Texinfo file, sample permission notices for each section are +reproduced in full below.@refill + +Note that you may need to specify the correct name of a section +mentioned in the permission notice. For example, in @cite{The GDB +Manual}, the name of the section referring to the General Public +License is called the ``GDB General Public License'', but in the +sample shown below, that section is referred to generically as the +``GNU General Public License''. If the Texinfo file does not carry a +copy of the General Public License, leave out the reference to it, but +be sure to include the rest of the sentence.@refill + +@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions +@comment node-name, next, previous, up +@appendixsec @samp{ifinfo} Copying Permissions +@cindex @samp{ifinfo} permissions + +In the @code{@@ifinfo} section of a Texinfo file, the standard Free +Software Foundation permission notice reads as follows:@refill + +@example +This file documents @dots{} + +Copyright 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. + +@@ignore +Permission is granted to process this file through TeX +and print the results, provided the printed document +carries a copying permission notice identical to this +one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@@end ignore +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided also that the sections +entitled ``Copying'' and ``GNU General Public License'' +are included exactly as in the original, and provided +that the entire resulting derived work is distributed +under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. +@end example + +@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions +@comment node-name, next, previous, up +@appendixsec Titlepage Copying Permissions +@cindex Titlepage permissions + +In the @code{@@titlepage} section of a Texinfo file, the standard Free +Software Foundation copying permission notice follows the copyright +notice and publishing information. The standard phrasing is as +follows:@refill + +@example +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 also that the sections +entitled ``Copying'' and ``GNU General Public License'' +are included exactly as in the original, and provided +that the entire resulting derived work is distributed +under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. +@end example + + +@node Include Files, Headings, Sample Permissions, Top +@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.@refill + +Include files let you keep a single large document as a collection of +conveniently small parts.@refill + +@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 File Requirements:: What @code{texinfo-multiple-files-update} expects. +* 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, texinfo-multiple-files-update, Include Files, Include Files +@appendixsec 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:@refill + +@example +@@include buffers.texi +@end 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.@refill + +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 + +@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files +@appendixsec @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 File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files +@appendixsec Include File Requirements +@cindex Include file 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, Include Files Evolution, Include File Requirements, Include Files +@appendixsec Sample File with @code{@@include} +@cindex Sample @code{@@include} file +@cindex Include file sample +@cindex @code{@@include} file sample + +Here is an example of a complete outer Texinfo file with @code{@@include} files +within it before running @code{texinfo-multiple-files-update}, which +would insert a main or master menu:@refill + +@example +@group +\input texinfo @@c -*-texinfo-*- +@c %**start of header +@@setfilename include-example.info +@@settitle Include Example +@c %**end of header +@end group + +@group +@@setchapternewpage odd +@@titlepage +@@sp 12 +@@center @@titlefont@{Include Example@} +@@sp 2 +@@center by Whom Ever +@end group + +@group +@@page +@@vskip 0pt plus 1filll +Copyright @@copyright@{@} 1998 Free Software Foundation, Inc. +@@end titlepage +@end group + +@group +@@ifinfo +@@node Top, First, , (dir) +@@top Master Menu +@@end ifinfo +@end group + +@group +@@include foo.texinfo +@@include bar.texinfo +@@include concept-index.texinfo +@end group + +@group +@@summarycontents +@@contents + +@@bye +@end group +@end example + +An included file, such as @file{foo.texinfo}, might look like +this:@refill + +@example +@group +@@node First, Second, , Top +@@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, , Second, Top +@@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.@refill + +@node Include Files Evolution, , Sample Include File, Include Files +@comment node-name, next, previous, up +@appendixsec Evolution of Include Files + +When Info was first created, it was customary to create many small +Info files on one subject. Each Info file was formatted from its own +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, Catching Mistakes, Include Files, Top +@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, Heading Format, Headings, Headings +@ifinfo +@heading Headings Introduced +@end ifinfo + +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, Heading Choice, Headings Introduced, Headings +@comment node-name, next, previous, up +@appendixsec Standard Heading Formats + +Texinfo provides two standard heading formats, one for manuals printed +on one side of each sheet of paper, and the other for manuals printed +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, Custom Headings, Heading Format, Headings +@comment node-name, next, previous, up +@appendixsec Specifying the Type of Heading + +@TeX{} does not begin to generate page headings for a standard Texinfo +file until it reaches the @code{@@end titlepage} command. Thus, the +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, , Heading Choice, Headings +@comment node-name, next, previous, up +@appendixsec How to Make Your Own Headings + +You can use the standard headings provided with Texinfo or specify +your own. By default, Texinfo has no footers, so if you specify them, +the available page size for the main text will be slightly reduced. + +@c Following paragraph is verbose to prevent overfull hboxes. +Texinfo provides six commands for specifying headings and +footings. The @code{@@everyheading} command and +@code{@@everyfooting} command generate page headers and footers +that are the same for both even- and odd-numbered pages. +The @code{@@evenheading} command and @code{@@evenfooting} +command generate headers and footers for even-numbered +(left-hand) pages; and the @code{@@oddheading} command and +@code{@@oddfooting} command generate headers and footers for +odd-numbered (right-hand) pages.@refill + +Write custom heading specifications in the Texinfo file immediately +after the @code{@@end titlepage} command. Enclose your specifications +between @code{@@iftex} and @code{@@end iftex} commands since the +@code{texinfo-format-buffer} command may not recognize them. Also, +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 +@@iftex +@@headings off +@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} +@@end iftex +@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 +@@iftex +@@headings off +@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter +@@everyfooting @@| @@| Version: 0.27: @@today@{@} +@@end iftex +@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, Refilling Paragraphs, Headings, Top +@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.@refill + +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, Debugging with Info, Catching Mistakes, Catching Mistakes +@ifinfo +@heading @code{makeinfo} Find Errors +@end ifinfo + +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, Debugging with TeX, makeinfo Preferred, Catching Mistakes +@comment node-name, next, previous, up +@appendixsec 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, Using texinfo-show-structure, Debugging with Info, Catching Mistakes +@comment node-name, next, previous, up +@appendixsec 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. + + @@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 + +Please note that if you are running @TeX{} inside Emacs, you need to +switch to the shell buffer and line at which @TeX{} offers the @samp{?} +prompt.@refill + +Sometimes @TeX{} will format a file without producing error messages even +though there is a problem. This usually occurs if a command is not ended +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, Using occur, Debugging with TeX, Catching Mistakes +@comment node-name, next, previous, up +@appendixsec 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, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes +@comment node-name, next, previous, up +@appendixsec 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, , Using occur, Catching Mistakes +@comment node-name, next, previous, up +@appendixsec 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, Unsplit, Running Info-Validate, Running Info-Validate +@appendixsubsec 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}.)@refill + +If your file is valid, you will receive a message that says ``File appears +valid''. However, if you have a pointer that does not point to a node, +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 + +Note that @code{Info-validate} requires a tag table and does not work +with files that have been split. (The @code{texinfo-format-buffer} +command automatically splits large files.) In order to use +@code{Info-validate} on a large file, you must run +@code{texinfo-format-buffer} with an argument so that it does not split +the Info file; and you must create a tag table for the unsplit +file.@refill + +@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate +@comment node-name, next, previous, up +@appendixsubsec 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 70,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, Splitting, Unsplit, Running Info-Validate +@appendixsubsec Tagifying a File + +After creating an unsplit Info file, you must create a tag table for +it. Visit the Info file you wish to tagify and type:@refill + +@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, , Tagifying, Running Info-Validate +@comment node-name, next, previous, up +@appendixsubsec Splitting a File Manually +@cindex Splitting an Info file manually +@cindex Info file, splitting manually + +You should split a large file or else let the +@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it +for you automatically. (Generally you will let one of the formatting +commands do this job for you. @xref{Create 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 + + +@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top +@appendix Refilling Paragraphs +@cindex Refilling paragraphs +@cindex Filling paragraphs +@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 + + +@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top +@comment node-name, next, previous, up +@appendix @@-Command Syntax +@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.@refill + + +@node Obtaining TeX, Command and Variable Index, Command Syntax, Top +@appendix 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: +@example +@uref{ftp://tug.org/tex/unixtex.ftp} +@uref{http://tug.org/unixtex.ftp} +@end example + +The Free Software Foundation provides a core distribution on its Source +Code CD-ROM suitable for printing Texinfo manuals; the University of +Washington maintains and supports a tape distribution; the @TeX{} Users +Group co-sponsors a complete CD-ROM @TeX{} distribution. + +@itemize @bullet + +@item +For the FSF Source Code CD-ROM, please contact: + +@iftex +@display +@group +Free Software Foundation, Inc. +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 +@end iftex +@ifinfo +@display +@group +Free Software Foundation, Inc. +59 Temple Place Suite 330 +Boston, MA @w{ } 02111-1307 +USA + +Telephone: @w{+1-617-542-5942} +Fax: (including Japan) @w{+1-617-542-2652} +Free Dial Fax (in Japan): +@w{ } @w{ } @w{ } 0031-13-2473 (KDD) +@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) +Electronic mail: @code{gnu@@gnu.org} +@end group +@end display +@end ifinfo + +@item +To order a complete distribution on CD-ROM, please see +@uref{http://tug.org/tex-live.html}. (This distribution is also +available by FTP; see the URL's above.) + +@item +To order a full distribution from the University of Washington on either +a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge, +send $210 to: + +@display +@group +Pierre A. MacKay +Denny Hall, Mail Stop DH-10 +University of Washington +Seattle, WA @w{ } 98195 +USA +Telephone: +1-206-543-2268 +Electronic mail: @code{mackay@@cs.washington.edu} +@end group +@end display + +@noindent Please make checks payable to the University of Washington. +Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas +sites: please add to the base cost, if desired, $20.00 for shipment via +air parcel post, or $30.00 for shipment via courier. + +@end itemize + +Many other @TeX{} distributions are available; see +@uref{http://tug.org/}. + + +@c These are no longer ``new'', and the explanations +@c are all given elsewhere anyway, I think. --karl, 25apr97. +@ignore (the entire appendix) +@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 + +@menu +* New Texinfo Mode Commands:: The updating commands are especially useful. +* New Commands:: Many newly described @@-commands. +@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.@refill + +@ifinfo +@noindent +@xref{Printing}. +@end ifinfo +@iftex +@noindent +@xref{Printing, , Formatting and Printing}. +@end iftex + +@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 node New Commands, , New Texinfo Mode Commands, Obtaining TeX +@c appendixsec New Texinfo @@-Commands + +The second edition of the Texinfo manual describes more than 50 +commands that were not described in the first edition. A third or so +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 (not 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 @r{but for} @@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 Command and Variable Index, Concept Index, Obtaining TeX, Top +@comment node-name, next, previous, up +@unnumbered Command and Variable Index + +This is an alphabetical list of all the @@-commands, assorted Emacs Lisp +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, , Command and Variable Index, Top +@unnumbered Concept Index + +@printindex cp + + +@summarycontents +@contents +@bye diff --git a/contrib/texinfo/doc/userdoc.texi b/contrib/texinfo/doc/userdoc.texi new file mode 100644 index 0000000..cee6b08 --- /dev/null +++ b/contrib/texinfo/doc/userdoc.texi @@ -0,0 +1,1270 @@ +@c This file is meant to be included in any arbitrary piece of +@c documentation that wishes to describe the info program. Some day +@c info-stnd.texi should probably use this file instead of duplicating +@c its contents. +@c +@c This file documents the use of the standalone GNU Info program, +@c versions 2.7 and later. + +@ifclear InfoProgVer +@set InfoProgVer 2.11 +@end ifclear +@synindex vr cp +@synindex fn cp +@synindex ky cp + +@heading What is Info? + +This text documents the use of the GNU Info program, version +@value{InfoProgVer}. + +@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 the Emacs command @code{M-x +texinfo-format-buffer}. Finally, @dfn{texinfo} is a documentation +language which allows a printed manual and online documentation (an info +file) to be produced from a single source file. + +@menu +* Options:: Options you can pass on the command line. +* Cursor Commands:: Commands which move the cursor within a node. +* Scrolling Commands:: Commands for moving the node around in a window. +* 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 behaviour of Info. +@ifset NOTSET +* Info for Sys Admins:: How to setup Info. Using special options. +@end ifset +@ifset STANDALONE +* GNU Info Global Index:: Global index containing keystrokes, command names, + variable names, and general concepts. +@end ifset +@end menu + +@node Options +@chapter Command Line Options +@cindex command line options +@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-name} @var{option-value}] @var{menu-item}@dots{} +@end example + +The following @var{option-names} are available when invoking Info from +the shell: + +@table @code +@cindex directory path +@item --directory @var{directory-path} +@itemx -d @var{directory-path} +Adds @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. +Alternatively, you may specify a value for the environment variable +@code{INFOPATH}; if @code{--directory} is not given, the value of +@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon +separated list of directory names. If you do not supply +@code{INFOPATH} or @code{--directory-path} a default path is used. + +@item --file @var{filename} +@itemx -f @var{filename} +@cindex info file, selecting +Specifies a particular info file to visit. Instead of visiting the file +@code{dir}, Info will start with @code{(@var{filename})Top} as the first +file and node. + +@item --node @var{nodename} +@itemx -n @var{nodename} +@cindex node, selecting +Specifies a particular node to visit in the initial file loaded. 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 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 output to. 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. + +@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 --help +@itemx -h +Produces a relatively brief description of the available Info options. + +@item --version +@cindex version information +Prints the version information of Info and exits. + +@item @var{menu-item} +@cindex menu, following +Remaining arguments to Info are treated as the names of menu items. The +first argument would be a menu item in the initial node visited, while +the second argument would be a menu item in the first argument's node. +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 + +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 + +@node Cursor Commands +@chapter Moving the Cursor +@cindex cursor, moving +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{Characters, , Character +Conventions, emacs, the GNU Emacs Manual}, if you are unfamilar with the +notation. + +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 an @dfn{numeric} argument (@pxref{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 @code{C-n} (@code{next-line}) +@kindex C-n +@findex next-line +Moves the cursor down to the next line. + +@item @code{C-p} (@code{prev-line}) +@kindex C-p +@findex prev-line +Move the cursor up to the previous line. + +@item @code{C-a} (@code{beginning-of-line}) +@kindex C-a, in Info windows +@findex beginning-of-line +Move the cursor to the start of the current line. + +@item @code{C-e} (@code{end-of-line}) +@kindex C-e, in Info windows +@findex end-of-line +Moves the cursor to the end of the current line. + +@item @code{C-f} (@code{forward-char}) +@kindex C-f, in Info windows +@findex forward-char +Move the cursor forward a character. + +@item @code{C-b} (@code{backward-char}) +@kindex C-b, in Info windows +@findex backward-char +Move the cursor backward a character. + +@item @code{M-f} (@code{forward-word}) +@kindex M-f, in Info windows +@findex forward-word +Moves the cursor forward a word. + +@item @code{M-b} (@code{backward-word}) +@kindex M-b, in Info winows +@findex backward-word +Moves the cursor backward a word. + +@item @code{M-<} (@code{beginning-of-node}) +@itemx @code{b} +@kindex b, in Info winows +@kindex M-< +@findex beginning-of-node +Moves the cursor to the start of the current node. + +@item @code{M->} (@code{end-of-node}) +@kindex M-> +@findex end-of-node +Moves the cursor to the end of the current node. + +@item @code{M-r} (@code{move-to-window-line}) +@kindex M-r +@findex move-to-window-line +Moves 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. + +@table @asis +@item @code{SPC} (@code{scroll-forward}) +@itemx @code{C-v} +@kindex SPC, in Info windows +@kindex C-v +@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. + +@item @code{DEL} (@code{scroll-backward}) +@itemx @code{M-v} +@kindex DEL, in Info windows +@kindex M-v +@findex scroll-backward +Shift the text in this window down. The inverse of +@code{scroll-forward}. + +@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-behaviour}. @xref{Variables, +@code{scroll-behaviour}}, for more information. + +@table @asis +@item @code{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 @code{C-x 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. +@end table + +@node Node Commands +@chapter Selecting a New 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}. + +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 @code{n} (@code{next-node}) +@kindex n +@findex next-node +Selects the `Next' node. + +@item @code{p} (@code{prev-node}) +@kindex p +@findex prev-node +Selects the `Prev' node. + +@item @code{u} (@code{up-node}) +@kindex u +@findex up-node +Selects 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 through the list of already visited nodes for this +window. @samp{l} with a negative numeric argument moves forward through +the history of nodes for this window, so you can quickly step between +two adjacent (in viewing history) nodes. + +@table @asis +@item @code{l} (@code{history-node}) +@kindex l +@findex history-node +Selects the most recently selected node in this window. +@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 @code{t} (@code{top-node}) +@kindex t +@findex top-node +Selects the node @samp{Top} in the current info file. + +@item @code{d} (@code{dir-node}) +@kindex d +@findex dir-node +Selects 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 @code{<} (@code{first-node}) +@kindex < +@findex first-node +Selects the first node which appears in this file. This node is most +often @samp{Top}, but it doesn't have to be. + +@item @code{>} (@code{last-node}) +@kindex > +@findex last-node +Selects the last node which appears in this file. + +@item @code{]} (@code{global-next-node}) +@kindex ] +@findex global-next-node +Moves 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 @code{[} (@code{global-prev-node}) +@kindex [ +@findex global-prev-node +Moves 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 behaviour 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-behaviour}}, for +more information. + +@table @asis +@item @code{g} (@code{goto-node}) +@kindex g +@findex goto-node +Reads the name of a node and selects it. No completion is done while +reading the node name, since the desired node may reside in a separate +file. The node must be typed exactly as it appears in the info file. A +file name may be included as with any node specification, for example + +@example +@code{g(emacs)Buffers} +@end example + +finds the node @samp{Buffers} in the info file @file{emacs}. + +@item @code{C-x k} (@code{kill-node}) +@kindex C-x k +@findex kill-node +Kills 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 @code{C-x C-f} (@code{view-file}) +@kindex C-x C-f +@findex view-file +Reads 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 @code{C-x C-b} (@code{list-visited-nodes}) +@kindex C-x C-b +@findex list-visited-nodes +Makes 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 @code{C-x b} (@code{select-visited-node}) +@kindex C-x b +@findex select-visited-node +Selects 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 @code{s} (@code{search}) +@kindex s +@findex search +Reads a string in the echo area and searches for it. + +@item @code{C-s} (@code{isearch-forward}) +@kindex C-s +@findex isearch-forward +Interactively searches forward through the info file for a string as you +type it. + +@item @code{C-r} (@code{isearch-backward}) +@kindex C-r +@findex isearch-backward +Interactively searches backward through the info file for a string as +you type it. + +@item @code{i} (@code{index-search}) +@kindex i +@findex index-search +Looks up a string in the indices for this info file, and selects a node +where the found index entry points to. + +@item @code{,} (@code{next-index-match}) +@kindex , +@findex next-index-match +Moves to the node containing the next matching index item from the last +@samp{i} command. +@end table + +The most basic searching command is @samp{s} (@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 ocurrence 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. + +@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. + +@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 references 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 @code{1} (@code{menu-digit}) +@itemx @code{2} @dots{} @code{9} +@cindex 1 @dots{} 9, in Info windows +@kindex 1 @dots{} 9, in Info windows +@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. + +@item @code{0} (@code{last-menu-item}) +@kindex 0, in Info windows +@findex last-menu-item +Select the last item in the current node's menu. + +@item @code{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. + +@item @code{M-x find-menu} +@findex find-menu +Moves the cursor to the start of this node's menu. +@end table + +This table lists the Info commands which operate on note cross references. + +@table @asis +@item @code{f} (@code{xref-item}) +@itemx @code{r} +@kindex f +@kindex r +@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. +@end table + +Finally, the next few commands operate on menu or note references alike: + +@table @asis +@item @code{TAB} (@code{move-to-next-xref}) +@kindex TAB, in Info windows +@findex move-to-next-xref +Moves 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 @code{M-TAB} (@code{move-to-prev-xref}) +@kindex M-TAB, in Info windows +@findex move-to-prev-xref +Moves the cursor the start of the nearest previous menu item or note +reference in this node. + +@item @code{RET} (@code{select-reference-this-line}) +@kindex RET, in Info windows +@findex select-reference-this-line +Selects 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 +-----Info: (dir)Top, 40 lines --Top--------------------------------------- + ^^ ^ ^^^ ^^ + (file)Node #lines where +@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 + +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 @code{C-x o} (@code{next-window}) +@cindex windows, selecting +@kindex C-x o +@findex next-window +Selects 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 @code{M-x prev-window} +@findex prev-window +Selects the previous window on the screen. This is identical to +@samp{C-x o} with a negative argument. + +@item @code{C-x 2} (@code{split-window}) +@cindex windows, creating +@kindex C-x 2 +@findex split-window +Splits 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, please @pxref{Variables, , automatic-tiling} for more +information. + +@item @code{C-x 0} (@code{delete-window}) +@cindex windows, deleting +@kindex C-x 0 +@findex delete-window +Deletes 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 @code{C-x 1} (@code{keep-one-window}) +@kindex C-x 1 +@findex keep-one-window +Deletes all of the windows excepting the current one. + +@item @code{ESC C-v} (@code{scroll-other-window}) +@kindex ESC C-v, in Info windows +@findex scroll-other-window +Scrolls the other window, in the same fashion that @samp{C-v} might +scroll the current window. Given a negative argument, the "other" +window is scrolled backward. + +@item @code{C-x ^} (@code{grow-window}) +@kindex C-x ^ +@findex grow-window +Grows (or shrinks) the current window. Given a numeric argument, grows +the current window that many lines; with a negative numeric argument, +the window is shrunk instead. + +@item @code{C-x t} (@code{tile-windows}) +@cindex tiling +@kindex C-x t +@findex tile-windows +Divides 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 @code{C-f} (@code{echo-area-forward}) +@kindex C-f, in the echo area +@findex echo-area-forward +Moves forward a character. + +@item @code{C-b} (@code{echo-area-backward}) +@kindex C-b, in the echo area +@findex echo-area-backward +Moves backward a character. + +@item @code{C-a} (@code{echo-area-beg-of-line}) +@kindex C-a, in the echo area +@findex echo-area-beg-of-line +Moves to the start of the input line. + +@item @code{C-e} (@code{echo-area-end-of-line}) +@kindex C-e, in the echo area +@findex echo-area-end-of-line +Moves to the end of the input line. + +@item @code{M-f} (@code{echo-area-forward-word}) +@kindex M-f, in the echo area +@findex echo-area-forward-word +Moves forward a word. + +@item @code{M-b} (@code{echo-area-backward-word}) +@kindex M-b, in the echo area +@findex echo-area-backward-word +Moves backward a word. + +@item @code{C-d} (@code{echo-area-delete}) +@kindex C-d, in the echo area +@findex echo-area-delete +Deletes the character under the cursor. + +@item @code{DEL} (@code{echo-area-rubout}) +@kindex DEL, in the echo area +@findex echo-area-rubout +Deletes the character behind the cursor. + +@item @code{C-g} (@code{echo-area-abort}) +@kindex C-g, in the echo area +@findex echo-area-abort +Cancels or quits the current operation. If completion is being read, +@samp{C-g} discards the text of the input line which does not match any +completion. If the input line is empty, @samp{C-g} aborts the calling +function. + +@item @code{RET} (@code{echo-area-newline}) +@kindex RET, in the echo area +@findex echo-area-newline +Accepts (or forces completion of) the current input line. + +@item @code{C-q} (@code{echo-area-quoted-insert}) +@kindex C-q, in the echo area +@findex echo-area-quoted-insert +Inserts the next character verbatim. This is how you can insert control +characters into a search string, for example. + +@item @var{printing character} (@code{echo-area-insert}) +@kindex printing characters, in the echo area +@findex echo-area-insert +Inserts the character. + +@item @code{M-TAB} (@code{echo-area-tab-insert}) +@kindex M-TAB, in the echo area +@findex echo-area-tab-insert +Inserts a TAB character. + +@item @code{C-t} (@code{echo-area-transpose-chars}) +@kindex C-t, in the echo area +@findex echo-area-transpose-chars +Transposes the characters at the cursor. +@end table + +The next group of commands deal with @dfn{killing}, and @dfn{yanking} +text. For an in depth discussion of killing and yanking, +@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} + +@table @asis +@item @code{M-d} (@code{echo-area-kill-word}) +@kindex M-d, in the echo area +@findex echo-area-kill-word +Kills the word following the cursor. + +@item @code{M-DEL} (@code{echo-area-backward-kill-word}) +@kindex M-DEL, in the echo area +@findex echo-area-backward-kill-word +Kills the word preceding the cursor. + +@item @code{C-k} (@code{echo-area-kill-line}) +@kindex C-k, in the echo area +@findex echo-area-kill-line +Kills the text from the cursor to the end of the line. + +@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) +@kindex C-x DEL, in the echo area +@findex echo-area-backward-kill-line +Kills the text from the cursor to the beginning of the line. + +@item @code{C-y} (@code{echo-area-yank}) +@kindex C-y, in the echo area +@findex echo-area-yank +Yanks back the contents of the last kill. + +@item @code{M-y} (@code{echo-area-yank-pop}) +@kindex M-y, in the echo area +@findex echo-area-yank-pop +Yanks back a previous kill, removing the last yanked text first. +@end table + +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 @code{TAB} (@code{echo-area-complete}) +@itemx @code{SPC} +@kindex TAB, in the echo area +@kindex SPC, in the echo area +@findex echo-area-complete +Inserts as much of a completion as is possible. + +@item @code{?} (@code{echo-area-possible-completions}) +@kindex ?, in the echo area +@findex echo-area-possible-completions +Displays a window containing a list of the possible completions of what +you have typed so far. For example, if the available choices are: +@example +bar +foliate +food +forget +@end example +and you have typed an @samp{f}, followed by @samp{?}, the possible +completions would contain: +@example +foliate +food +forget +@end example +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 @code{ESC C-v} (@code{echo-area-scroll-completions-window}) +@kindex ESC C-v, in the echo area +@findex echo-area-scroll-completions-window +Scrolls the completions window, if that is visible, or the "other" +window if not. +@end table + +@node Printing Nodes +@chapter Printing Out Nodes +@cindex printing + +You may wish to print out the contents of a node as a quick reference +document for later use. Info provides you with a command for doing +this. 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. + +@table @asis +@item @code{M-x print-node} +@findex print-node +@cindex INFO_PRINT_COMMAND, environment variable +Pipes the contents of the current node through the command in the +environment variable @code{INFO_PRINT_COMMAND}. If the variable doesn't +exist, the node is simply piped to @code{lpr}. +@end table + +@node Miscellaneous Commands +@chapter Miscellaneous Commands + +GNU Info contains several commands which self-document GNU Info: + +@table @asis +@item @code{M-x describe-command} +@cindex functions, describing +@cindex commands, describing +@findex describe-command +Reads the name of an Info command in the echo area and then displays a +brief description of what that command does. + +@item @code{M-x describe-key} +@cindex keys, describing +@findex describe-key +Reads a key sequence in the echo area, and then displays the name and +documentation of the Info command that the key sequence invokes. + +@item @code{M-x describe-variable} +Reads the name of a variable in the echo area and then displays a brief +description of what the variable affects. + +@item @code{M-x where-is} +@findex where-is +Reads the name of an Info command in the echo area, and then displays +a key sequence which can be typed in order to invoke that command. + +@item @code{C-h} (@code{get-help-window}) +@itemx @code{?} +@kindex C-h +@kindex ?, in Info windows +@findex get-help-window +Creates (or moves into) the window displaying @code{*Help*}, and places +a node containing a quick reference card into it. This window displays +the most concise information about GNU Info available. + +@item @code{h} (@code{get-info-help-node}) +@kindex h +@findex get-info-help-node +Tries 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 @code{C-u} (@code{universal-argument}) +@cindex numeric arguments +@kindex C-u +@findex universal-argument +Starts (or multiplies 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. + +@item @code{M-1} (@code{add-digit-to-numeric-arg}) +@itemx @code{M-2} @dots{} @code{M-9} +@kindex M-1 @dots{} M-9 +@findex add-digit-to-numeric-arg +Adds 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 +or +@example +@kbd{M-3 2 C-l} +@end example +@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 @code{C-g} (@code{abort-key}) +@cindex cancelling typeahead +@cindex cancelling the current operation +@kindex C-g, in Info windows +@findex abort-key +Cancels current operation. +@end table + +The @samp{q} command of Info simply quits running Info. + +@table @asis +@item @code{q} (@code{quit}) +@cindex quitting +@kindex q +@findex quit +Exits 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 @code{M-x set-screen-height} +@findex set-screen-height +@cindex screen, changing the height of +Reads a height value in the echo area and sets the height of the +displayed screen to that value. +@end table + +Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + +@table @asis +@item @code{ESC C-f} (@code{show-footnotes}) +@kindex ESC C-f +@findex show-footnotes +@cindex footnotes, displaying +Shows 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 behaviour of Info to more closely match your environment and +info file reading manner. + +@table @asis +@item @code{M-x set-variable} +@cindex variables, setting +@findex set-variable +Reads the name of a variable, and the value for it, in the echo area and +then sets the variable to that value. Completion is available when +reading the variable name; 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 @code{M-x describe-variable} +@cindex variables, describing +@findex describe-variable +Reads the name of a variable in the echo area and then displays 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. +This variable is @code{On} 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 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}. + +@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 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 scroll-behaviour +@vindex scroll-behaviour +Controls 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 +Tries 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 behaviour is identical to using the @samp{]} +(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) +commands. + +@item Next Only +Only tries to get the @samp{Next} node. + +@item Page Only +Simply gives up, changing nothing. If @code{scroll-behaviour} 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 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. +@end table + +@c The following node and its children are currently unfinished. Please feel +@c free to finish it! + +@ifset NOTSET +@node Info for Sys Admins +@chapter Info for System Administrators + +This text describes some common ways of setting up an Info heierarchy +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 flexibilty in setups. +* Using `localdir':: Building DIR on the fly. +* Example setups:: Some common ways to origanize Info files. +@end menu + +@node Setting the INFOPATH +@section Setting the INFOPATH +Where are my Info files kept? + +@node Editing the DIR node +@section Editing the DIR node +What goes in `DIR', and why? + +@node Storing Info files +@section Storing Info files +Alternate formats allow flexibilty in setups. + +@node Using `localdir' +@section Using `localdir' +Building DIR on the fly. + +@node Example setups +@section Example setups +Some common ways to origanize Info files. +@end ifset + +@ifset STANDALONE +@node GNU Info Global Index +@appendix Global Index +@printindex cp +@end ifset -- cgit v1.1