readline-6.3/ 0000775 0000436 0000024 00000000000 12302645507 011754 5 ustar chet staff readline-6.3/doc/ 0000775 0000436 0000024 00000000000 12302645513 012516 5 ustar chet staff readline-6.3/doc/Makefile.in 0000664 0000436 0000024 00000016541 12115144571 014572 0 ustar chet staff # This makefile for Readline library documentation is in -*- text -*- mode.
# Emacs likes it that way.
# Copyright (C) 1996-2009 Free Software Foundation, Inc.
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
PACKAGE_TARNAME = @PACKAGE_TARNAME@
topdir = @top_srcdir@
srcdir = @srcdir@
VPATH = @srcdir@
prefix = @prefix@
datarootdir = @datarootdir@
docdir = @docdir@
infodir = @infodir@
mandir = @mandir@
manpfx = man
man1ext = .1
man1dir = $(mandir)/$(manpfx)1
man3ext = .3
man3dir = $(mandir)/$(manpfx)3
# set this to a value to have the HTML documentation installed
htmldir =
# Support an alternate destination root directory for package building
DESTDIR =
SHELL = @MAKE_SHELL@
RM = rm -f
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
BUILD_DIR = @BUILD_DIR@
TEXINPUTDIR = $(srcdir)
MAKEINFO = LANGUAGE= makeinfo
TEXI2DVI = $(srcdir)/texi2dvi
TEXI2HTML = $(srcdir)/texi2html
QUIETPS = #set this to -q to shut up dvips
PAPERSIZE = letter
PSDPI = 600
DVIPS = dvips -D ${PSDPI} $(QUIETPS) -t ${PAPERSIZE} -o $@ # tricky
# These tools might not be available; they're not required
DVIPDF = dvipdfm -o $@ -p ${PAPERSIZE}
PSPDF = gs -sPAPERSIZE=${PAPERSIZE} -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=$@
RLSRC = $(srcdir)/rlman.texi $(srcdir)/rluser.texi \
$(srcdir)/rltech.texi $(srcdir)/version.texi \
$(srcdir)/rluserman.texi $(srcdir)/fdl.texi
HISTSRC = $(srcdir)/history.texi $(srcdir)/hsuser.texi \
$(srcdir)/hstech.texi $(srcdir)/version.texi $(srcdir)/fdl.texi
# This should be a program that converts troff to an ascii-readable format
NROFF = groff -Tascii
# This should be a program that converts troff to postscript
GROFF = groff
DVIOBJ = readline.dvi history.dvi rluserman.dvi
INFOOBJ = readline.info history.info rluserman.info
PSOBJ = readline.ps history.ps rluserman.ps readline_3.ps history_3.ps
HTMLOBJ = readline.html history.html rluserman.html
TEXTOBJ = readline.0 history.0
PDFOBJ = readline.pdf history.pdf rluserman.pdf
INTERMEDIATE_OBJ = rlman.dvi
DIST_DOCS = $(DVIOBJ) $(PSOBJ) $(HTMLOBJ) $(INFOOBJ) $(TEXTOBJ) $(PDFOBJ)
.SUFFIXES: .0 .3 .ps .txt .dvi .html .pdf
.3.0:
$(RM) $@
-${NROFF} -man $< > $@
.ps.pdf:
$(RM) $@
-${PSPDF} $<
.dvi.pdf:
$(RM) $@
-${DVIPDF} $<
all: info dvi html ps text pdf
nodvi: info html text
xdist: $(DIST_DOCS)
info: $(INFOOBJ)
dvi: $(DVIOBJ)
ps: $(PSOBJ)
html: $(HTMLOBJ)
text: $(TEXTOBJ)
pdf: $(PDFOBJ)
readline.dvi: $(RLSRC)
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rlman.texi
mv rlman.dvi readline.dvi
readline.info: $(RLSRC)
$(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rlman.texi
rluserman.dvi: $(RLSRC)
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rluserman.texi
rluserman.info: $(RLSRC)
$(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rluserman.texi
history.dvi: ${HISTSRC}
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/history.texi
history.info: ${HISTSRC}
$(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/history.texi
readline.ps: readline.dvi
$(RM) $@
$(DVIPS) readline.dvi
rluserman.ps: rluserman.dvi
$(RM) $@
$(DVIPS) rluserman.dvi
history.ps: history.dvi
$(RM) $@
$(DVIPS) history.dvi
#
# This leaves readline.html and rlman.html -- rlman.html is for www.gnu.org
#
readline.html: ${RLSRC}
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rlman.texi
sed -e 's:rlman.html:readline.html:g' rlman.html > readline.html
$(RM) rlman.html
rluserman.html: ${RLSRC}
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rluserman.texi
history.html: ${HISTSRC}
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/history.texi
readline.0: readline.3
readline_3.ps: $(srcdir)/readline.3
${RM} $@
${GROFF} -man < $(srcdir)/readline.3 > $@
history.0: history.3
history_3.ps: $(srcdir)/history.3
${RM} $@
${GROFF} -man < $(srcdir)/history.3 > $@
readline.pdf: readline.dvi
history.pdf: history.dvi
rluserman.pdf: rluserman.dvi
clean:
$(RM) *.aux *.bak *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps \
*.pgs *.bt *.bts *.rw *.rws *.fns *.kys *.tps *.vrs *.o \
core *.core
mostlyclean: clean
distclean: clean maybe-clean
$(RM) $(INTERMEDIATE_OBJ)
$(RM) Makefile
maybe-clean:
-if test "X$(topdir)" != "X.." && test "X$(topdir)" != "X$(BUILD_DIR)"; then \
$(RM) $(DIST_DOCS); \
fi
maintainer-clean: clean
$(RM) $(DIST_DOCS)
$(RM) $(INTERMEDIATE_OBJ)
$(RM) $(PDFOBJ)
$(RM) Makefile
installdirs: $(topdir)/support/mkdirs
-$(SHELL) $(topdir)/support/mkdirs $(DESTDIR)$(infodir) $(DESTDIR)$(man3dir)
-if test -n "${htmldir}" ; then \
$(SHELL) $(topdir)/support/mkdirs $(DESTDIR)$(htmldir) ; \
fi
install: installdirs
if test -f readline.info; then \
${INSTALL_DATA} readline.info $(DESTDIR)$(infodir)/readline.info; \
else \
${INSTALL_DATA} $(srcdir)/readline.info $(DESTDIR)$(infodir)/readline.info; \
fi
if test -f rluserman.info; then \
${INSTALL_DATA} rluserman.info $(DESTDIR)$(infodir)/rluserman.info; \
else \
${INSTALL_DATA} $(srcdir)/rluserman.info $(DESTDIR)$(infodir)/rluserman.info; \
fi
if test -f history.info; then \
${INSTALL_DATA} history.info $(DESTDIR)$(infodir)/history.info; \
else \
${INSTALL_DATA} $(srcdir)/history.info $(DESTDIR)$(infodir)/history.info; \
fi
-if $(SHELL) -c 'install-info --version' >/dev/null 2>&1; then \
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
$(DESTDIR)$(infodir)/readline.info ; \
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
$(DESTDIR)$(infodir)/history.info ; \
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
$(DESTDIR)$(infodir)/rluserman.info ; \
else true; fi
-${INSTALL_DATA} $(srcdir)/readline.3 $(DESTDIR)$(man3dir)/readline$(man3ext)
-${INSTALL_DATA} $(srcdir)/history.3 $(DESTDIR)$(man3dir)/history$(man3ext)
-if test -n "${htmldir}" ; then \
if test -f readline.html; then \
${INSTALL_DATA} readline.html $(DESTDIR)$(htmldir)/readline.html; \
else \
${INSTALL_DATA} $(srcdir)/readline.html $(DESTDIR)$(htmldir)/readline.html; \
fi ; \
if test -f history.html; then \
${INSTALL_DATA} history.html $(DESTDIR)$(htmldir)/history.html; \
else \
${INSTALL_DATA} $(srcdir)/history.html $(DESTDIR)$(htmldir)/history.html; \
fi ; \
if test -f rluserman.html; then \
${INSTALL_DATA} rluserman.html $(DESTDIR)$(htmldir)/rluserman.html; \
else \
${INSTALL_DATA} $(srcdir)/rluserman.html $(DESTDIR)$(htmldir)/rluserman.html; \
fi ; \
fi
uninstall:
$(RM) $(DESTDIR)$(infodir)/readline.info
$(RM) $(DESTDIR)$(infodir)/rluserman.info
$(RM) $(DESTDIR)$(infodir)/history.info
$(RM) $(DESTDIR)$(man3dir)/readline$(man3ext)
$(RM) $(DESTDIR)$(man3dir)/history$(man3ext)
-if test -n "${htmldir}" ; then \
$(RM) $(DESTDIR)$(htmldir)/readline.html ; \
$(RM) $(DESTDIR)$(htmldir)/rluserman.html ; \
$(RM) $(DESTDIR)$(htmldir)/history.html ; \
fi
readline-6.3/doc/texinfo.tex 0000644 0000436 0000024 00001174404 12257353261 014732 0 ustar chet staff % texinfo.tex -- TeX macros to handle Texinfo files.
%
% Load plain if necessary, i.e., if running under initex.
\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
%
\def\texinfoversion{2013-09-11.11}
%
% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
% 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
%
% This texinfo.tex file is free software: you can redistribute it and/or
% modify it under the terms of the GNU General Public License as
% published by the Free Software Foundation, either version 3 of the
% License, or (at your option) any later version.
%
% This texinfo.tex file is distributed in the hope that it will be
% useful, but WITHOUT ANY WARRANTY; without even the implied warranty
% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
% General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program. If not, see .
%
% As a special exception, when this file is read by TeX when processing
% a Texinfo source document, you may use the result without
% restriction. This Exception is an additional permission under section 7
% of the GNU General Public License, version 3 ("GPLv3").
%
% Please try the latest version of texinfo.tex before submitting bug
% reports; you can get the latest version from:
% http://ftp.gnu.org/gnu/texinfo/ (the Texinfo release area), or
% http://ftpmirror.gnu.org/texinfo/ (same, via a mirror), or
% http://www.gnu.org/software/texinfo/ (the Texinfo home page)
% The texinfo.tex in any given distribution could well be out
% of date, so if that's what you're using, please check.
%
% Send bug reports to bug-texinfo@gnu.org. Please include including a
% complete document in each bug report with which we can reproduce the
% problem. Patches are, of course, greatly appreciated.
%
% To process a Texinfo manual with TeX, it's most reliable to use the
% texi2dvi shell script that comes with the distribution. For a simple
% manual foo.texi, however, you can get away with this:
% tex foo.texi
% texindex foo.??
% tex foo.texi
% tex foo.texi
% dvips foo.dvi -o # or whatever; this makes foo.ps.
% The extra TeX runs get the cross-reference information correct.
% Sometimes one run after texindex suffices, and sometimes you need more
% than two; texi2dvi does it as many times as necessary.
%
% It is possible to adapt texinfo.tex for other languages, to some
% extent. You can get the existing language-specific files from the
% full Texinfo distribution.
%
% The GNU Texinfo home page is http://www.gnu.org/software/texinfo.
\message{Loading texinfo [version \texinfoversion]:}
% If in a .fmt file, print the version number
% and turn on active characters that we couldn't do earlier because
% they might have appeared in the input file name.
\everyjob{\message{[Texinfo version \texinfoversion]}%
\catcode`+=\active \catcode`\_=\active}
\chardef\other=12
% We never want plain's \outer definition of \+ in Texinfo.
% For @tex, we can use \tabalign.
\let\+ = \relax
% Save some plain tex macros whose names we will redefine.
\let\ptexb=\b
\let\ptexbullet=\bullet
\let\ptexc=\c
\let\ptexcomma=\,
\let\ptexdot=\.
\let\ptexdots=\dots
\let\ptexend=\end
\let\ptexequiv=\equiv
\let\ptexexclam=\!
\let\ptexfootnote=\footnote
\let\ptexgtr=>
\let\ptexhat=^
\let\ptexi=\i
\let\ptexindent=\indent
\let\ptexinsert=\insert
\let\ptexlbrace=\{
\let\ptexless=<
\let\ptexnewwrite\newwrite
\let\ptexnoindent=\noindent
\let\ptexplus=+
\let\ptexraggedright=\raggedright
\let\ptexrbrace=\}
\let\ptexslash=\/
\let\ptexstar=\*
\let\ptext=\t
\let\ptextop=\top
{\catcode`\'=\active \global\let\ptexquoteright'}% active in plain's math mode
% If this character appears in an error message or help string, it
% starts a new line in the output.
\newlinechar = `^^J
% Use TeX 3.0's \inputlineno to get the line number, for better error
% messages, but if we're using an old version of TeX, don't do anything.
%
\ifx\inputlineno\thisisundefined
\let\linenumber = \empty % Pre-3.0.
\else
\def\linenumber{l.\the\inputlineno:\space}
\fi
% Set up fixed words for English if not already set.
\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi
\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi
\ifx\putworderror\undefined \gdef\putworderror{error}\fi
\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi
\ifx\putwordin\undefined \gdef\putwordin{in}\fi
\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi
\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi
\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi
\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi
\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi
\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi
\ifx\putwordof\undefined \gdef\putwordof{of}\fi
\ifx\putwordon\undefined \gdef\putwordon{on}\fi
\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi
\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi
\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi
\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi
\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi
\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi
\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi
%
\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi
\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi
\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi
\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi
\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi
\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi
\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi
\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi
\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi
\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi
\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi
\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi
%
\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi
\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi
\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi
\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi
\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi
% Since the category of space is not known, we have to be careful.
\chardef\spacecat = 10
\def\spaceisspace{\catcode`\ =\spacecat}
% sometimes characters are active, so we need control sequences.
\chardef\ampChar = `\&
\chardef\colonChar = `\:
\chardef\commaChar = `\,
\chardef\dashChar = `\-
\chardef\dotChar = `\.
\chardef\exclamChar= `\!
\chardef\hashChar = `\#
\chardef\lquoteChar= `\`
\chardef\questChar = `\?
\chardef\rquoteChar= `\'
\chardef\semiChar = `\;
\chardef\slashChar = `\/
\chardef\underChar = `\_
% Ignore a token.
%
\def\gobble#1{}
% The following is used inside several \edef's.
\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname}
% Hyphenation fixes.
\hyphenation{
Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script
ap-pen-dix bit-map bit-maps
data-base data-bases eshell fall-ing half-way long-est man-u-script
man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm
par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces
spell-ing spell-ings
stand-alone strong-est time-stamp time-stamps which-ever white-space
wide-spread wrap-around
}
% Margin to add to right of even pages, to left of odd pages.
\newdimen\bindingoffset
\newdimen\normaloffset
\newdimen\pagewidth \newdimen\pageheight
% For a final copy, take out the rectangles
% that mark overfull boxes (in case you have decided
% that the text looks ok even though it passes the margin).
%
\def\finalout{\overfullrule=0pt }
% Sometimes it is convenient to have everything in the transcript file
% and nothing on the terminal. We don't just call \tracingall here,
% since that produces some useless output on the terminal. We also make
% some effort to order the tracing commands to reduce output in the log
% file; cf. trace.sty in LaTeX.
%
\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%
\def\loggingall{%
\tracingstats2
\tracingpages1
\tracinglostchars2 % 2 gives us more in etex
\tracingparagraphs1
\tracingoutput1
\tracingmacros2
\tracingrestores1
\showboxbreadth\maxdimen \showboxdepth\maxdimen
\ifx\eTeXversion\thisisundefined\else % etex gives us more logging
\tracingscantokens1
\tracingifs1
\tracinggroups1
\tracingnesting2
\tracingassigns1
\fi
\tracingcommands3 % 3 gives us more in etex
\errorcontextlines16
}%
% @errormsg{MSG}. Do the index-like expansions on MSG, but if things
% aren't perfect, it's not the end of the world, being an error message,
% after all.
%
\def\errormsg{\begingroup \indexnofonts \doerrormsg}
\def\doerrormsg#1{\errmessage{#1}}
% add check for \lastpenalty to plain's definitions. If the last thing
% we did was a \nobreak, we don't want to insert more space.
%
\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
\removelastskip\penalty-50\smallskip\fi\fi}
\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
\removelastskip\penalty-100\medskip\fi\fi}
\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount
\removelastskip\penalty-200\bigskip\fi\fi}
% Do @cropmarks to get crop marks.
%
\newif\ifcropmarks
\let\cropmarks = \cropmarkstrue
%
% Dimensions to add cropmarks at corners.
% Added by P. A. MacKay, 12 Nov. 1986
%
\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines
\newdimen\cornerlong \cornerlong=1pc
\newdimen\cornerthick \cornerthick=.3pt
\newdimen\topandbottommargin \topandbottommargin=.75in
% Output a mark which sets \thischapter, \thissection and \thiscolor.
% We dump everything together because we only have one kind of mark.
% This works because we only use \botmark / \topmark, not \firstmark.
%
% A mark contains a subexpression of the \ifcase ... \fi construct.
% \get*marks macros below extract the needed part using \ifcase.
%
% Another complication is to let the user choose whether \thischapter
% (\thissection) refers to the chapter (section) in effect at the top
% of a page, or that at the bottom of a page. The solution is
% described on page 260 of The TeXbook. It involves outputting two
% marks for the sectioning macros, one before the section break, and
% one after. I won't pretend I can describe this better than DEK...
\def\domark{%
\toks0=\expandafter{\lastchapterdefs}%
\toks2=\expandafter{\lastsectiondefs}%
\toks4=\expandafter{\prevchapterdefs}%
\toks6=\expandafter{\prevsectiondefs}%
\toks8=\expandafter{\lastcolordefs}%
\mark{%
\the\toks0 \the\toks2 % 0: top marks (\last...)
\noexpand\or \the\toks4 \the\toks6 % 1: bottom marks (default, \prev...)
\noexpand\else \the\toks8 % 2: color marks
}%
}
% \topmark doesn't work for the very first chapter (after the title
% page or the contents), so we use \firstmark there -- this gets us
% the mark with the chapter defs, unless the user sneaks in, e.g.,
% @setcolor (or @url, or @link, etc.) between @contents and the very
% first @chapter.
\def\gettopheadingmarks{%
\ifcase0\topmark\fi
\ifx\thischapter\empty \ifcase0\firstmark\fi \fi
}
\def\getbottomheadingmarks{\ifcase1\botmark\fi}
\def\getcolormarks{\ifcase2\topmark\fi}
% Avoid "undefined control sequence" errors.
\def\lastchapterdefs{}
\def\lastsectiondefs{}
\def\prevchapterdefs{}
\def\prevsectiondefs{}
\def\lastcolordefs{}
% Main output routine.
\chardef\PAGE = 255
\output = {\onepageout{\pagecontents\PAGE}}
\newbox\headlinebox
\newbox\footlinebox
% \onepageout takes a vbox as an argument. Note that \pagecontents
% does insertions, but you have to call it yourself.
\def\onepageout#1{%
\ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi
%
\ifodd\pageno \advance\hoffset by \bindingoffset
\else \advance\hoffset by -\bindingoffset\fi
%
% Do this outside of the \shipout so @code etc. will be expanded in
% the headline as they should be, not taken literally (outputting ''code).
\def\commmonheadfootline{\let\hsize=\pagewidth \texinfochars}
%
\ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
\global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}%
%
\ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi
\global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}%
%
{%
% Have to do this stuff outside the \shipout because we want it to
% take effect in \write's, yet the group defined by the \vbox ends
% before the \shipout runs.
%
\indexdummies % don't expand commands in the output.
\normalturnoffactive % \ in index entries must not stay \, e.g., if
% the page break happens to be in the middle of an example.
% We don't want .vr (or whatever) entries like this:
% \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}}
% "\acronym" won't work when it's read back in;
% it needs to be
% {\code {{\tt \backslashcurfont }acronym}
\shipout\vbox{%
% Do this early so pdf references go to the beginning of the page.
\ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi
%
\ifcropmarks \vbox to \outervsize\bgroup
\hsize = \outerhsize
\vskip-\topandbottommargin
\vtop to0pt{%
\line{\ewtop\hfil\ewtop}%
\nointerlineskip
\line{%
\vbox{\moveleft\cornerthick\nstop}%
\hfill
\vbox{\moveright\cornerthick\nstop}%
}%
\vss}%
\vskip\topandbottommargin
\line\bgroup
\hfil % center the page within the outer (page) hsize.
\ifodd\pageno\hskip\bindingoffset\fi
\vbox\bgroup
\fi
%
\unvbox\headlinebox
\pagebody{#1}%
\ifdim\ht\footlinebox > 0pt
% Only leave this space if the footline is nonempty.
% (We lessened \vsize for it in \oddfootingyyy.)
% The \baselineskip=24pt in plain's \makefootline has no effect.
\vskip 24pt
\unvbox\footlinebox
\fi
%
\ifcropmarks
\egroup % end of \vbox\bgroup
\hfil\egroup % end of (centering) \line\bgroup
\vskip\topandbottommargin plus1fill minus1fill
\boxmaxdepth = \cornerthick
\vbox to0pt{\vss
\line{%
\vbox{\moveleft\cornerthick\nsbot}%
\hfill
\vbox{\moveright\cornerthick\nsbot}%
}%
\nointerlineskip
\line{\ewbot\hfil\ewbot}%
}%
\egroup % \vbox from first cropmarks clause
\fi
}% end of \shipout\vbox
}% end of group with \indexdummies
\advancepageno
\ifnum\outputpenalty>-20000 \else\dosupereject\fi
}
\newinsert\margin \dimen\margin=\maxdimen
\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}
{\catcode`\@ =11
\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi
% marginal hacks, juha@viisa.uucp (Juha Takala)
\ifvoid\margin\else % marginal info is present
\rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi
\dimen@=\dp#1\relax \unvbox#1\relax
\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi
\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
}
% Here are the rules for the cropmarks. Note that they are
% offset so that the space between them is truly \outerhsize or \outervsize
% (P. A. MacKay, 12 November, 1986)
%
\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}
\def\nstop{\vbox
{\hrule height\cornerthick depth\cornerlong width\cornerthick}}
\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}
\def\nsbot{\vbox
{\hrule height\cornerlong depth\cornerthick width\cornerthick}}
% Parse an argument, then pass it to #1. The argument is the rest of
% the input line (except we remove a trailing comment). #1 should be a
% macro which expects an ordinary undelimited TeX argument.
%
\def\parsearg{\parseargusing{}}
\def\parseargusing#1#2{%
\def\argtorun{#2}%
\begingroup
\obeylines
\spaceisspace
#1%
\parseargline\empty% Insert the \empty token, see \finishparsearg below.
}
{\obeylines %
\gdef\parseargline#1^^M{%
\endgroup % End of the group started in \parsearg.
\argremovecomment #1\comment\ArgTerm%
}%
}
% First remove any @comment, then any @c comment.
\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm}
\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm}
% Each occurrence of `\^^M' or `\^^M' is replaced by a single space.
%
% \argremovec might leave us with trailing space, e.g.,
% @end itemize @c foo
% This space token undergoes the same procedure and is eventually removed
% by \finishparsearg.
%
\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M}
\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M}
\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{%
\def\temp{#3}%
\ifx\temp\empty
% Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp:
\let\temp\finishparsearg
\else
\let\temp\argcheckspaces
\fi
% Put the space token in:
\temp#1 #3\ArgTerm
}
% If a _delimited_ argument is enclosed in braces, they get stripped; so
% to get _exactly_ the rest of the line, we had to prevent such situation.
% We prepended an \empty token at the very beginning and we expand it now,
% just before passing the control to \argtorun.
% (Similarly, we have to think about #3 of \argcheckspacesY above: it is
% either the null string, or it ends with \^^M---thus there is no danger
% that a pair of braces would be stripped.
%
% But first, we have to remove the trailing space token.
%
\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}}
% \parseargdef\foo{...}
% is roughly equivalent to
% \def\foo{\parsearg\Xfoo}
% \def\Xfoo#1{...}
%
% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my
% favourite TeX trick. --kasal, 16nov03
\def\parseargdef#1{%
\expandafter \doparseargdef \csname\string#1\endcsname #1%
}
\def\doparseargdef#1#2{%
\def#2{\parsearg#1}%
\def#1##1%
}
% Several utility definitions with active space:
{
\obeyspaces
\gdef\obeyedspace{ }
% Make each space character in the input produce a normal interword
% space in the output. Don't allow a line break at this space, as this
% is used only in environments like @example, where each line of input
% should produce a line of output anyway.
%
\gdef\sepspaces{\obeyspaces\let =\tie}
% If an index command is used in an @example environment, any spaces
% therein should become regular spaces in the raw index file, not the
% expansion of \tie (\leavevmode \penalty \@M \ ).
\gdef\unsepspaces{\let =\space}
}
\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}
% Define the framework for environments in texinfo.tex. It's used like this:
%
% \envdef\foo{...}
% \def\Efoo{...}
%
% It's the responsibility of \envdef to insert \begingroup before the
% actual body; @end closes the group after calling \Efoo. \envdef also
% defines \thisenv, so the current environment is known; @end checks
% whether the environment name matches. The \checkenv macro can also be
% used to check whether the current environment is the one expected.
%
% Non-false conditionals (@iftex, @ifset) don't fit into this, so they
% are not treated as environments; they don't open a group. (The
% implementation of @end takes care not to call \endgroup in this
% special case.)
% At run-time, environments start with this:
\def\startenvironment#1{\begingroup\def\thisenv{#1}}
% initialize
\let\thisenv\empty
% ... but they get defined via ``\envdef\foo{...}'':
\long\def\envdef#1#2{\def#1{\startenvironment#1#2}}
\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}}
% Check whether we're in the right environment:
\def\checkenv#1{%
\def\temp{#1}%
\ifx\thisenv\temp
\else
\badenverr
\fi
}
% Environment mismatch, #1 expected:
\def\badenverr{%
\errhelp = \EMsimple
\errmessage{This command can appear only \inenvironment\temp,
not \inenvironment\thisenv}%
}
\def\inenvironment#1{%
\ifx#1\empty
outside of any environment%
\else
in environment \expandafter\string#1%
\fi
}
% @end foo executes the definition of \Efoo.
% But first, it executes a specialized version of \checkenv
%
\parseargdef\end{%
\if 1\csname iscond.#1\endcsname
\else
% The general wording of \badenverr may not be ideal.
\expandafter\checkenv\csname#1\endcsname
\csname E#1\endcsname
\endgroup
\fi
}
\newhelp\EMsimple{Press RETURN to continue.}
% Be sure we're in horizontal mode when doing a tie, since we make space
% equivalent to this in @example-like environments. Otherwise, a space
% at the beginning of a line will start with \penalty -- and
% since \penalty is valid in vertical mode, we'd end up putting the
% penalty on the vertical list instead of in the new paragraph.
{\catcode`@ = 11
% Avoid using \@M directly, because that causes trouble
% if the definition is written into an index file.
\global\let\tiepenalty = \@M
\gdef\tie{\leavevmode\penalty\tiepenalty\ }
}
% @: forces normal size whitespace following.
\def\:{\spacefactor=1000 }
% @* forces a line break.
\def\*{\unskip\hfil\break\hbox{}\ignorespaces}
% @/ allows a line break.
\let\/=\allowbreak
% @. is an end-of-sentence period.
\def\.{.\spacefactor=\endofsentencespacefactor\space}
% @! is an end-of-sentence bang.
\def\!{!\spacefactor=\endofsentencespacefactor\space}
% @? is an end-of-sentence query.
\def\?{?\spacefactor=\endofsentencespacefactor\space}
% @frenchspacing on|off says whether to put extra space after punctuation.
%
\def\onword{on}
\def\offword{off}
%
\parseargdef\frenchspacing{%
\def\temp{#1}%
\ifx\temp\onword \plainfrenchspacing
\else\ifx\temp\offword \plainnonfrenchspacing
\else
\errhelp = \EMsimple
\errmessage{Unknown @frenchspacing option `\temp', must be on|off}%
\fi\fi
}
% @w prevents a word break. Without the \leavevmode, @w at the
% beginning of a paragraph, when TeX is still in vertical mode, would
% produce a whole line of output instead of starting the paragraph.
\def\w#1{\leavevmode\hbox{#1}}
% @group ... @end group forces ... to be all on one page, by enclosing
% it in a TeX vbox. We use \vtop instead of \vbox to construct the box
% to keep its height that of a normal line. According to the rules for
% \topskip (p.114 of the TeXbook), the glue inserted is
% max (\topskip - \ht (first item), 0). If that height is large,
% therefore, no glue is inserted, and the space between the headline and
% the text is small, which looks bad.
%
% Another complication is that the group might be very large. This can
% cause the glue on the previous page to be unduly stretched, because it
% does not have much material. In this case, it's better to add an
% explicit \vfill so that the extra space is at the bottom. The
% threshold for doing this is if the group is more than \vfilllimit
% percent of a page (\vfilllimit can be changed inside of @tex).
%
\newbox\groupbox
\def\vfilllimit{0.7}
%
\envdef\group{%
\ifnum\catcode`\^^M=\active \else
\errhelp = \groupinvalidhelp
\errmessage{@group invalid in context where filling is enabled}%
\fi
\startsavinginserts
%
\setbox\groupbox = \vtop\bgroup
% Do @comment since we are called inside an environment such as
% @example, where each end-of-line in the input causes an
% end-of-line in the output. We don't want the end-of-line after
% the `@group' to put extra space in the output. Since @group
% should appear on a line by itself (according to the Texinfo
% manual), we don't worry about eating any user text.
\comment
}
%
% The \vtop produces a box with normal height and large depth; thus, TeX puts
% \baselineskip glue before it, and (when the next line of text is done)
% \lineskip glue after it. Thus, space below is not quite equal to space
% above. But it's pretty close.
\def\Egroup{%
% To get correct interline space between the last line of the group
% and the first line afterwards, we have to propagate \prevdepth.
\endgraf % Not \par, as it may have been set to \lisppar.
\global\dimen1 = \prevdepth
\egroup % End the \vtop.
% \dimen0 is the vertical size of the group's box.
\dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox
% \dimen2 is how much space is left on the page (more or less).
\dimen2 = \pageheight \advance\dimen2 by -\pagetotal
% if the group doesn't fit on the current page, and it's a big big
% group, force a page break.
\ifdim \dimen0 > \dimen2
\ifdim \pagetotal < \vfilllimit\pageheight
\page
\fi
\fi
\box\groupbox
\prevdepth = \dimen1
\checkinserts
}
%
% TeX puts in an \escapechar (i.e., `@') at the beginning of the help
% message, so this ends up printing `@group can only ...'.
%
\newhelp\groupinvalidhelp{%
group can only be used in environments such as @example,^^J%
where each line of input produces a line of output.}
% @need space-in-mils
% forces a page break if there is not space-in-mils remaining.
\newdimen\mil \mil=0.001in
\parseargdef\need{%
% Ensure vertical mode, so we don't make a big box in the middle of a
% paragraph.
\par
%
% If the @need value is less than one line space, it's useless.
\dimen0 = #1\mil
\dimen2 = \ht\strutbox
\advance\dimen2 by \dp\strutbox
\ifdim\dimen0 > \dimen2
%
% Do a \strut just to make the height of this box be normal, so the
% normal leading is inserted relative to the preceding line.
% And a page break here is fine.
\vtop to #1\mil{\strut\vfil}%
%
% TeX does not even consider page breaks if a penalty added to the
% main vertical list is 10000 or more. But in order to see if the
% empty box we just added fits on the page, we must make it consider
% page breaks. On the other hand, we don't want to actually break the
% page after the empty box. So we use a penalty of 9999.
%
% There is an extremely small chance that TeX will actually break the
% page at this \penalty, if there are no other feasible breakpoints in
% sight. (If the user is using lots of big @group commands, which
% almost-but-not-quite fill up a page, TeX will have a hard time doing
% good page breaking, for example.) However, I could not construct an
% example where a page broke at this \penalty; if it happens in a real
% document, then we can reconsider our strategy.
\penalty9999
%
% Back up by the size of the box, whether we did a page break or not.
\kern -#1\mil
%
% Do not allow a page break right after this kern.
\nobreak
\fi
}
% @br forces paragraph break (and is undocumented).
\let\br = \par
% @page forces the start of a new page.
%
\def\page{\par\vfill\supereject}
% @exdent text....
% outputs text on separate line in roman font, starting at standard page margin
% This records the amount of indent in the innermost environment.
% That's how much \exdent should take out.
\newskip\exdentamount
% This defn is used inside fill environments such as @defun.
\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}
% This defn is used inside nofill environments such as @example.
\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount
\leftline{\hskip\leftskip{\rm#1}}}}
% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current
% paragraph. For more general purposes, use the \margin insertion
% class. WHICH is `l' or `r'. Not documented, written for gawk manual.
%
\newskip\inmarginspacing \inmarginspacing=1cm
\def\strutdepth{\dp\strutbox}
%
\def\doinmargin#1#2{\strut\vadjust{%
\nobreak
\kern-\strutdepth
\vtop to \strutdepth{%
\baselineskip=\strutdepth
\vss
% if you have multiple lines of stuff to put here, you'll need to
% make the vbox yourself of the appropriate size.
\ifx#1l%
\llap{\ignorespaces #2\hskip\inmarginspacing}%
\else
\rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}%
\fi
\null
}%
}}
\def\inleftmargin{\doinmargin l}
\def\inrightmargin{\doinmargin r}
%
% @inmargin{TEXT [, RIGHT-TEXT]}
% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
% else use TEXT for both).
%
\def\inmargin#1{\parseinmargin #1,,\finish}
\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
\setbox0 = \hbox{\ignorespaces #2}%
\ifdim\wd0 > 0pt
\def\lefttext{#1}% have both texts
\def\righttext{#2}%
\else
\def\lefttext{#1}% have only one text
\def\righttext{#1}%
\fi
%
\ifodd\pageno
\def\temp{\inrightmargin\righttext}% odd page -> outside is right margin
\else
\def\temp{\inleftmargin\lefttext}%
\fi
\temp
}
% @| 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). This command
% is not documented, not supported, and doesn't work.
%
\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
}%
}%
}
% @include FILE -- \input text of FILE.
%
\def\include{\parseargusing\filenamecatcodes\includezzz}
\def\includezzz#1{%
\pushthisfilestack
\def\thisfile{#1}%
{%
\makevalueexpandable % we want to expand any @value in FILE.
\turnoffactive % and allow special characters in the expansion
\indexnofonts % Allow `@@' and other weird things in file names.
\wlog{texinfo.tex: doing @include of #1^^J}%
\edef\temp{\noexpand\input #1 }%
%
% This trickery is to read FILE outside of a group, in case it makes
% definitions, etc.
\expandafter
}\temp
\popthisfilestack
}
\def\filenamecatcodes{%
\catcode`\\=\other
\catcode`~=\other
\catcode`^=\other
\catcode`_=\other
\catcode`|=\other
\catcode`<=\other
\catcode`>=\other
\catcode`+=\other
\catcode`-=\other
\catcode`\`=\other
\catcode`\'=\other
}
\def\pushthisfilestack{%
\expandafter\pushthisfilestackX\popthisfilestack\StackTerm
}
\def\pushthisfilestackX{%
\expandafter\pushthisfilestackY\thisfile\StackTerm
}
\def\pushthisfilestackY #1\StackTerm #2\StackTerm {%
\gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}%
}
\def\popthisfilestack{\errthisfilestackempty}
\def\errthisfilestackempty{\errmessage{Internal error:
the stack of filenames is empty.}}
%
\def\thisfile{}
% @center line
% outputs that line, centered.
%
\parseargdef\center{%
\ifhmode
\let\centersub\centerH
\else
\let\centersub\centerV
\fi
\centersub{\hfil \ignorespaces#1\unskip \hfil}%
\let\centersub\relax % don't let the definition persist, just in case
}
\def\centerH#1{{%
\hfil\break
\advance\hsize by -\leftskip
\advance\hsize by -\rightskip
\line{#1}%
\break
}}
%
\newcount\centerpenalty
\def\centerV#1{%
% The idea here is the same as in \startdefun, \cartouche, etc.: if
% @center is the first thing after a section heading, we need to wipe
% out the negative parskip inserted by \sectionheading, but still
% prevent a page break here.
\centerpenalty = \lastpenalty
\ifnum\centerpenalty>10000 \vskip\parskip \fi
\ifnum\centerpenalty>9999 \penalty\centerpenalty \fi
\line{\kern\leftskip #1\kern\rightskip}%
}
% @sp n outputs n lines of vertical space
%
\parseargdef\sp{\vskip #1\baselineskip}
% @comment ...line which is ignored...
% @c is the same as @comment
% @ignore ... @end ignore is another way to write a comment
%
\def\comment{\begingroup \catcode`\^^M=\other%
\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
\commentxxx}
{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}
%
\let\c=\comment
% @paragraphindent NCHARS
% We'll use ems for NCHARS, close enough.
% NCHARS can also be the word `asis' or `none'.
% We cannot feasibly implement @paragraphindent asis, though.
%
\def\asisword{asis} % no translation, these are keywords
\def\noneword{none}
%
\parseargdef\paragraphindent{%
\def\temp{#1}%
\ifx\temp\asisword
\else
\ifx\temp\noneword
\defaultparindent = 0pt
\else
\defaultparindent = #1em
\fi
\fi
\parindent = \defaultparindent
}
% @exampleindent NCHARS
% We'll use ems for NCHARS like @paragraphindent.
% It seems @exampleindent asis isn't necessary, but
% I preserve it to make it similar to @paragraphindent.
\parseargdef\exampleindent{%
\def\temp{#1}%
\ifx\temp\asisword
\else
\ifx\temp\noneword
\lispnarrowing = 0pt
\else
\lispnarrowing = #1em
\fi
\fi
}
% @firstparagraphindent WORD
% If WORD is `none', then suppress indentation of the first paragraph
% after a section heading. If WORD is `insert', then do indent at such
% paragraphs.
%
% The paragraph indentation is suppressed or not by calling
% \suppressfirstparagraphindent, which the sectioning commands do.
% We switch the definition of this back and forth according to WORD.
% By default, we suppress indentation.
%
\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent}
\def\insertword{insert}
%
\parseargdef\firstparagraphindent{%
\def\temp{#1}%
\ifx\temp\noneword
\let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent
\else\ifx\temp\insertword
\let\suppressfirstparagraphindent = \relax
\else
\errhelp = \EMsimple
\errmessage{Unknown @firstparagraphindent option `\temp'}%
\fi\fi
}
% Here is how we actually suppress indentation. Redefine \everypar to
% \kern backwards by \parindent, and then reset itself to empty.
%
% We also make \indent itself not actually do anything until the next
% paragraph.
%
\gdef\dosuppressfirstparagraphindent{%
\gdef\indent{%
\restorefirstparagraphindent
\indent
}%
\gdef\noindent{%
\restorefirstparagraphindent
\noindent
}%
\global\everypar = {%
\kern -\parindent
\restorefirstparagraphindent
}%
}
\gdef\restorefirstparagraphindent{%
\global \let \indent = \ptexindent
\global \let \noindent = \ptexnoindent
\global \everypar = {}%
}
% @refill is a no-op.
\let\refill=\relax
% If working on a large document in chapters, it is convenient to
% be able to disable indexing, cross-referencing, and contents, for test runs.
% This is done with @novalidate (before @setfilename).
%
\newif\iflinks \linkstrue % by default we want the aux files.
\let\novalidate = \linksfalse
% @setfilename is done at the beginning of every texinfo file.
% So open here the files we need to have open while reading the input.
% This makes it possible to make a .fmt file for texinfo.
\def\setfilename{%
\fixbackslash % Turn off hack to swallow `\input texinfo'.
\iflinks
\tryauxfile
% Open the new aux file. TeX will close it automatically at exit.
\immediate\openout\auxfile=\jobname.aux
\fi % \openindices needs to do some work in any case.
\openindices
\let\setfilename=\comment % Ignore extra @setfilename cmds.
%
% If texinfo.cnf is present on the system, read it.
% Useful for site-wide @afourpaper, etc.
\openin 1 texinfo.cnf
\ifeof 1 \else \input texinfo.cnf \fi
\closein 1
%
\comment % Ignore the actual filename.
}
% Called from \setfilename.
%
\def\openindices{%
\newindex{cp}%
\newcodeindex{fn}%
\newcodeindex{vr}%
\newcodeindex{tp}%
\newcodeindex{ky}%
\newcodeindex{pg}%
}
% @bye.
\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
\message{pdf,}
% adobe `portable' document format
\newcount\tempnum
\newcount\lnkcount
\newtoks\filename
\newcount\filenamelength
\newcount\pgn
\newtoks\toksA
\newtoks\toksB
\newtoks\toksC
\newtoks\toksD
\newbox\boxA
\newcount\countA
\newif\ifpdf
\newif\ifpdfmakepagedest
% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1
% can be set). So we test for \relax and 0 as well as being undefined.
\ifx\pdfoutput\thisisundefined
\else
\ifx\pdfoutput\relax
\else
\ifcase\pdfoutput
\else
\pdftrue
\fi
\fi
\fi
% PDF uses PostScript string constants for the names of xref targets,
% for display in the outlines, and in other places. Thus, we have to
% double any backslashes. Otherwise, a name like "\node" will be
% interpreted as a newline (\n), followed by o, d, e. Not good.
%
% See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and
% related messages. The final outcome is that it is up to the TeX user
% to double the backslashes and otherwise make the string valid, so
% that's what we do. pdftex 1.30.0 (ca.2005) introduced a primitive to
% do this reliably, so we use it.
% #1 is a control sequence in which to do the replacements,
% which we \xdef.
\def\txiescapepdf#1{%
\ifx\pdfescapestring\thisisundefined
% No primitive available; should we give a warning or log?
% Many times it won't matter.
\else
% The expandable \pdfescapestring primitive escapes parentheses,
% backslashes, and other special chars.
\xdef#1{\pdfescapestring{#1}}%
\fi
}
\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images
with PDF output, and none of those formats could be found. (.eps cannot
be supported due to the design of the PDF format; use regular TeX (DVI
output) for that.)}
\ifpdf
%
% Color manipulation macros based on pdfcolor.tex,
% except using rgb instead of cmyk; the latter is said to render as a
% very dark gray on-screen and a very dark halftone in print, instead
% of actual black.
\def\rgbDarkRed{0.50 0.09 0.12}
\def\rgbBlack{0 0 0}
%
% k sets the color for filling (usual text, etc.);
% K sets the color for stroking (thin rules, e.g., normal _'s).
\def\pdfsetcolor#1{\pdfliteral{#1 rg #1 RG}}
%
% Set color, and create a mark which defines \thiscolor accordingly,
% so that \makeheadline knows which color to restore.
\def\setcolor#1{%
\xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}%
\domark
\pdfsetcolor{#1}%
}
%
\def\maincolor{\rgbBlack}
\pdfsetcolor{\maincolor}
\edef\thiscolor{\maincolor}
\def\lastcolordefs{}
%
\def\makefootline{%
\baselineskip24pt
\line{\pdfsetcolor{\maincolor}\the\footline}%
}
%
\def\makeheadline{%
\vbox to 0pt{%
\vskip-22.5pt
\line{%
\vbox to8.5pt{}%
% Extract \thiscolor definition from the marks.
\getcolormarks
% Typeset the headline with \maincolor, then restore the color.
\pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}%
}%
\vss
}%
\nointerlineskip
}
%
%
\pdfcatalog{/PageMode /UseOutlines}
%
% #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto).
\def\dopdfimage#1#2#3{%
\def\pdfimagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
\def\pdfimageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
%
% pdftex (and the PDF format) support .pdf, .png, .jpg (among
% others). Let's try in that order, PDF first since if
% someone has a scalable image, presumably better to use that than a
% bitmap.
\let\pdfimgext=\empty
\begingroup
\openin 1 #1.pdf \ifeof 1
\openin 1 #1.PDF \ifeof 1
\openin 1 #1.png \ifeof 1
\openin 1 #1.jpg \ifeof 1
\openin 1 #1.jpeg \ifeof 1
\openin 1 #1.JPG \ifeof 1
\errhelp = \nopdfimagehelp
\errmessage{Could not find image file #1 for pdf}%
\else \gdef\pdfimgext{JPG}%
\fi
\else \gdef\pdfimgext{jpeg}%
\fi
\else \gdef\pdfimgext{jpg}%
\fi
\else \gdef\pdfimgext{png}%
\fi
\else \gdef\pdfimgext{PDF}%
\fi
\else \gdef\pdfimgext{pdf}%
\fi
\closein 1
\endgroup
%
% without \immediate, ancient pdftex seg faults when the same image is
% included twice. (Version 3.14159-pre-1.0-unofficial-20010704.)
\ifnum\pdftexversion < 14
\immediate\pdfimage
\else
\immediate\pdfximage
\fi
\ifdim \wd0 >0pt width \pdfimagewidth \fi
\ifdim \wd2 >0pt height \pdfimageheight \fi
\ifnum\pdftexversion<13
#1.\pdfimgext
\else
{#1.\pdfimgext}%
\fi
\ifnum\pdftexversion < 14 \else
\pdfrefximage \pdflastximage
\fi}
%
\def\pdfmkdest#1{{%
% We have to set dummies so commands such as @code, and characters
% such as \, aren't expanded when present in a section title.
\indexnofonts
\turnoffactive
\makevalueexpandable
\def\pdfdestname{#1}%
\txiescapepdf\pdfdestname
\safewhatsit{\pdfdest name{\pdfdestname} xyz}%
}}
%
% used to mark target names; must be expandable.
\def\pdfmkpgn#1{#1}
%
% by default, use a color that is dark enough to print on paper as
% nearly black, but still distinguishable for online viewing.
\def\urlcolor{\rgbDarkRed}
\def\linkcolor{\rgbDarkRed}
\def\endlink{\setcolor{\maincolor}\pdfendlink}
%
% Adding outlines to PDF; macros for calculating structure of outlines
% come from Petr Olsak
\def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%
\else \csname#1\endcsname \fi}
\def\advancenumber#1{\tempnum=\expnumber{#1}\relax
\advance\tempnum by 1
\expandafter\xdef\csname#1\endcsname{\the\tempnum}}
%
% #1 is the section text, which is what will be displayed in the
% outline by the pdf viewer. #2 is the pdf expression for the number
% of subentries (or empty, for subsubsections). #3 is the node text,
% which might be empty if this toc entry had no corresponding node.
% #4 is the page number
%
\def\dopdfoutline#1#2#3#4{%
% Generate a link to the node text if that exists; else, use the
% page number. We could generate a destination for the section
% text in the case where a section has no node, but it doesn't
% seem worth the trouble, since most documents are normally structured.
\edef\pdfoutlinedest{#3}%
\ifx\pdfoutlinedest\empty
\def\pdfoutlinedest{#4}%
\else
\txiescapepdf\pdfoutlinedest
\fi
%
% Also escape PDF chars in the display string.
\edef\pdfoutlinetext{#1}%
\txiescapepdf\pdfoutlinetext
%
\pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}%
}
%
\def\pdfmakeoutlines{%
\begingroup
% Read toc silently, to get counts of subentries for \pdfoutline.
\def\partentry##1##2##3##4{}% ignore parts in the outlines
\def\numchapentry##1##2##3##4{%
\def\thischapnum{##2}%
\def\thissecnum{0}%
\def\thissubsecnum{0}%
}%
\def\numsecentry##1##2##3##4{%
\advancenumber{chap\thischapnum}%
\def\thissecnum{##2}%
\def\thissubsecnum{0}%
}%
\def\numsubsecentry##1##2##3##4{%
\advancenumber{sec\thissecnum}%
\def\thissubsecnum{##2}%
}%
\def\numsubsubsecentry##1##2##3##4{%
\advancenumber{subsec\thissubsecnum}%
}%
\def\thischapnum{0}%
\def\thissecnum{0}%
\def\thissubsecnum{0}%
%
% use \def rather than \let here because we redefine \chapentry et
% al. a second time, below.
\def\appentry{\numchapentry}%
\def\appsecentry{\numsecentry}%
\def\appsubsecentry{\numsubsecentry}%
\def\appsubsubsecentry{\numsubsubsecentry}%
\def\unnchapentry{\numchapentry}%
\def\unnsecentry{\numsecentry}%
\def\unnsubsecentry{\numsubsecentry}%
\def\unnsubsubsecentry{\numsubsubsecentry}%
\readdatafile{toc}%
%
% Read toc second time, this time actually producing the outlines.
% The `-' means take the \expnumber as the absolute number of
% subentries, which we calculated on our first read of the .toc above.
%
% We use the node names as the destinations.
\def\numchapentry##1##2##3##4{%
\dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}%
\def\numsecentry##1##2##3##4{%
\dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}%
\def\numsubsecentry##1##2##3##4{%
\dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}%
\def\numsubsubsecentry##1##2##3##4{% count is always zero
\dopdfoutline{##1}{}{##3}{##4}}%
%
% PDF outlines are displayed using system fonts, instead of
% document fonts. Therefore we cannot use special characters,
% since the encoding is unknown. For example, the eogonek from
% Latin 2 (0xea) gets translated to a | character. Info from
% Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100.
%
% TODO this right, we have to translate 8-bit characters to
% their "best" equivalent, based on the @documentencoding. Too
% much work for too little return. Just use the ASCII equivalents
% we use for the index sort strings.
%
\indexnofonts
\setupdatafile
% We can have normal brace characters in the PDF outlines, unlike
% Texinfo index files. So set that up.
\def\{{\lbracecharliteral}%
\def\}{\rbracecharliteral}%
\catcode`\\=\active \otherbackslash
\input \tocreadfilename
\endgroup
}
{\catcode`[=1 \catcode`]=2
\catcode`{=\other \catcode`}=\other
\gdef\lbracecharliteral[{]%
\gdef\rbracecharliteral[}]%
]
%
\def\skipspaces#1{\def\PP{#1}\def\D{|}%
\ifx\PP\D\let\nextsp\relax
\else\let\nextsp\skipspaces
\addtokens{\filename}{\PP}%
\advance\filenamelength by 1
\fi
\nextsp}
\def\getfilename#1{%
\filenamelength=0
% If we don't expand the argument now, \skipspaces will get
% snagged on things like "@value{foo}".
\edef\temp{#1}%
\expandafter\skipspaces\temp|\relax
}
\ifnum\pdftexversion < 14
\let \startlink \pdfannotlink
\else
\let \startlink \pdfstartlink
\fi
% make a live url in pdf output.
\def\pdfurl#1{%
\begingroup
% it seems we really need yet another set of dummies; have not
% tried to figure out what each command should do in the context
% of @url. for now, just make @/ a no-op, that's the only one
% people have actually reported a problem with.
%
\normalturnoffactive
\def\@{@}%
\let\/=\empty
\makevalueexpandable
% do we want to go so far as to use \indexnofonts instead of just
% special-casing \var here?
\def\var##1{##1}%
%
\leavevmode\setcolor{\urlcolor}%
\startlink attr{/Border [0 0 0]}%
user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
\endgroup}
\def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}
\def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
\def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}
\def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}
\def\maketoks{%
\expandafter\poptoks\the\toksA|ENDTOKS|\relax
\ifx\first0\adn0
\else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
\else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
\else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
\else
\ifnum0=\countA\else\makelink\fi
\ifx\first.\let\next=\done\else
\let\next=\maketoks
\addtokens{\toksB}{\the\toksD}
\ifx\first,\addtokens{\toksB}{\space}\fi
\fi
\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
\next}
\def\makelink{\addtokens{\toksB}%
{\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
\def\pdflink#1{%
\startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}}
\setcolor{\linkcolor}#1\endlink}
\def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
\else
% non-pdf mode
\let\pdfmkdest = \gobble
\let\pdfurl = \gobble
\let\endlink = \relax
\let\setcolor = \gobble
\let\pdfsetcolor = \gobble
\let\pdfmakeoutlines = \relax
\fi % \ifx\pdfoutput
\message{fonts,}
% Change the current font style to #1, remembering it in \curfontstyle.
% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in
% italics, not bold italics.
%
\def\setfontstyle#1{%
\def\curfontstyle{#1}% not as a control sequence, because we are \edef'd.
\csname ten#1\endcsname % change the current font
}
% Select #1 fonts with the current style.
%
\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname}
\def\rm{\fam=0 \setfontstyle{rm}}
\def\it{\fam=\itfam \setfontstyle{it}}
\def\sl{\fam=\slfam \setfontstyle{sl}}
\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
\def\tt{\fam=\ttfam \setfontstyle{tt}}
% Unfortunately, we have to override this for titles and the like, since
% in those cases "rm" is bold. Sigh.
\def\rmisbold{\rm\def\curfontstyle{bf}}
% Texinfo sort of supports the sans serif font style, which plain TeX does not.
% So we set up a \sf.
\newfam\sffam
\def\sf{\fam=\sffam \setfontstyle{sf}}
\let\li = \sf % Sometimes we call it \li, not \sf.
% We don't need math for this font style.
\def\ttsl{\setfontstyle{ttsl}}
% Set the baselineskip to #1, and the lineskip and strut size
% correspondingly. There is no deep meaning behind these magic numbers
% used as factors; they just match (closely enough) what Knuth defined.
%
\def\lineskipfactor{.08333}
\def\strutheightpercent{.70833}
\def\strutdepthpercent {.29167}
%
% can get a sort of poor man's double spacing by redefining this.
\def\baselinefactor{1}
%
\newdimen\textleading
\def\setleading#1{%
\dimen0 = #1\relax
\normalbaselineskip = \baselinefactor\dimen0
\normallineskip = \lineskipfactor\normalbaselineskip
\normalbaselines
\setbox\strutbox =\hbox{%
\vrule width0pt height\strutheightpercent\baselineskip
depth \strutdepthpercent \baselineskip
}%
}
% PDF CMaps. See also LaTeX's t1.cmap.
%
% do nothing with this by default.
\expandafter\let\csname cmapOT1\endcsname\gobble
\expandafter\let\csname cmapOT1IT\endcsname\gobble
\expandafter\let\csname cmapOT1TT\endcsname\gobble
% if we are producing pdf, and we have \pdffontattr, then define cmaps.
% (\pdffontattr was introduced many years ago, but people still run
% older pdftex's; it's easy to conditionalize, so we do.)
\ifpdf \ifx\pdffontattr\thisisundefined \else
\begingroup
\catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
\catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
%%DocumentNeededResources: ProcSet (CIDInit)
%%IncludeResource: ProcSet (CIDInit)
%%BeginResource: CMap (TeX-OT1-0)
%%Title: (TeX-OT1-0 TeX OT1 0)
%%Version: 1.000
%%EndComments
/CIDInit /ProcSet findresource begin
12 dict begin
begincmap
/CIDSystemInfo
<< /Registry (TeX)
/Ordering (OT1)
/Supplement 0
>> def
/CMapName /TeX-OT1-0 def
/CMapType 2 def
1 begincodespacerange
<00> <7F>
endcodespacerange
8 beginbfrange
<00> <01> <0393>
<09> <0A> <03A8>
<23> <26> <0023>
<28> <3B> <0028>
<3F> <5B> <003F>
<5D> <5E> <005D>
<61> <7A> <0061>
<7B> <7C> <2013>
endbfrange
40 beginbfchar
<02> <0398>
<03> <039B>
<04> <039E>
<05> <03A0>
<06> <03A3>
<07> <03D2>
<08> <03A6>
<0B> <00660066>
<0C> <00660069>
<0D> <0066006C>
<0E> <006600660069>
<0F> <00660066006C>
<10> <0131>
<11> <0237>
<12> <0060>
<13> <00B4>
<14> <02C7>
<15> <02D8>
<16> <00AF>
<17> <02DA>
<18> <00B8>
<19> <00DF>
<1A> <00E6>
<1B> <0153>
<1C> <00F8>
<1D> <00C6>
<1E> <0152>
<1F> <00D8>
<21> <0021>
<22> <201D>
<27> <2019>
<3C> <00A1>
<3D> <003D>
<3E> <00BF>
<5C> <201C>
<5F> <02D9>
<60> <2018>
<7D> <02DD>
<7E> <007E>
<7F> <00A8>
endbfchar
endcmap
CMapName currentdict /CMap defineresource pop
end
end
%%EndResource
%%EOF
}\endgroup
\expandafter\edef\csname cmapOT1\endcsname#1{%
\pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
}%
%
% \cmapOT1IT
\begingroup
\catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
\catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
%%DocumentNeededResources: ProcSet (CIDInit)
%%IncludeResource: ProcSet (CIDInit)
%%BeginResource: CMap (TeX-OT1IT-0)
%%Title: (TeX-OT1IT-0 TeX OT1IT 0)
%%Version: 1.000
%%EndComments
/CIDInit /ProcSet findresource begin
12 dict begin
begincmap
/CIDSystemInfo
<< /Registry (TeX)
/Ordering (OT1IT)
/Supplement 0
>> def
/CMapName /TeX-OT1IT-0 def
/CMapType 2 def
1 begincodespacerange
<00> <7F>
endcodespacerange
8 beginbfrange
<00> <01> <0393>
<09> <0A> <03A8>
<25> <26> <0025>
<28> <3B> <0028>
<3F> <5B> <003F>
<5D> <5E> <005D>
<61> <7A> <0061>
<7B> <7C> <2013>
endbfrange
42 beginbfchar
<02> <0398>
<03> <039B>
<04> <039E>
<05> <03A0>
<06> <03A3>
<07> <03D2>
<08> <03A6>
<0B> <00660066>
<0C> <00660069>
<0D> <0066006C>
<0E> <006600660069>
<0F> <00660066006C>
<10> <0131>
<11> <0237>
<12> <0060>
<13> <00B4>
<14> <02C7>
<15> <02D8>
<16> <00AF>
<17> <02DA>
<18> <00B8>
<19> <00DF>
<1A> <00E6>
<1B> <0153>
<1C> <00F8>
<1D> <00C6>
<1E> <0152>
<1F> <00D8>
<21> <0021>
<22> <201D>
<23> <0023>
<24> <00A3>
<27> <2019>
<3C> <00A1>
<3D> <003D>
<3E> <00BF>
<5C> <201C>
<5F> <02D9>
<60> <2018>
<7D> <02DD>
<7E> <007E>
<7F> <00A8>
endbfchar
endcmap
CMapName currentdict /CMap defineresource pop
end
end
%%EndResource
%%EOF
}\endgroup
\expandafter\edef\csname cmapOT1IT\endcsname#1{%
\pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
}%
%
% \cmapOT1TT
\begingroup
\catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
\catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
%%DocumentNeededResources: ProcSet (CIDInit)
%%IncludeResource: ProcSet (CIDInit)
%%BeginResource: CMap (TeX-OT1TT-0)
%%Title: (TeX-OT1TT-0 TeX OT1TT 0)
%%Version: 1.000
%%EndComments
/CIDInit /ProcSet findresource begin
12 dict begin
begincmap
/CIDSystemInfo
<< /Registry (TeX)
/Ordering (OT1TT)
/Supplement 0
>> def
/CMapName /TeX-OT1TT-0 def
/CMapType 2 def
1 begincodespacerange
<00> <7F>
endcodespacerange
5 beginbfrange
<00> <01> <0393>
<09> <0A> <03A8>
<21> <26> <0021>
<28> <5F> <0028>
<61> <7E> <0061>
endbfrange
32 beginbfchar
<02> <0398>
<03> <039B>
<04> <039E>
<05> <03A0>
<06> <03A3>
<07> <03D2>
<08> <03A6>
<0B> <2191>
<0C> <2193>
<0D> <0027>
<0E> <00A1>
<0F> <00BF>
<10> <0131>
<11> <0237>
<12> <0060>
<13> <00B4>
<14> <02C7>
<15> <02D8>
<16> <00AF>
<17> <02DA>
<18> <00B8>
<19> <00DF>
<1A> <00E6>
<1B> <0153>
<1C> <00F8>
<1D> <00C6>
<1E> <0152>
<1F> <00D8>
<20> <2423>
<27> <2019>
<60> <2018>
<7F> <00A8>
endbfchar
endcmap
CMapName currentdict /CMap defineresource pop
end
end
%%EndResource
%%EOF
}\endgroup
\expandafter\edef\csname cmapOT1TT\endcsname#1{%
\pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
}%
\fi\fi
% Set the font macro #1 to the font named \fontprefix#2.
% #3 is the font's design size, #4 is a scale factor, #5 is the CMap
% encoding (only OT1, OT1IT and OT1TT are allowed, or empty to omit).
% Example:
% #1 = \textrm
% #2 = \rmshape
% #3 = 10
% #4 = \mainmagstep
% #5 = OT1
%
\def\setfont#1#2#3#4#5{%
\font#1=\fontprefix#2#3 scaled #4
\csname cmap#5\endcsname#1%
}
% This is what gets called when #5 of \setfont is empty.
\let\cmap\gobble
%
% (end of cmaps)
% Use cm as the default font prefix.
% To specify the font prefix, you must define \fontprefix
% before you read in texinfo.tex.
\ifx\fontprefix\thisisundefined
\def\fontprefix{cm}
\fi
% Support font families that don't use the same naming scheme as CM.
\def\rmshape{r}
\def\rmbshape{bx} % where the normal face is bold
\def\bfshape{b}
\def\bxshape{bx}
\def\ttshape{tt}
\def\ttbshape{tt}
\def\ttslshape{sltt}
\def\itshape{ti}
\def\itbshape{bxti}
\def\slshape{sl}
\def\slbshape{bxsl}
\def\sfshape{ss}
\def\sfbshape{ss}
\def\scshape{csc}
\def\scbshape{csc}
% Definitions for a main text size of 11pt. (The default in Texinfo.)
%
\def\definetextfontsizexi{%
% Text fonts (11.2pt, magstep1).
\def\textnominalsize{11pt}
\edef\mainmagstep{\magstephalf}
\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
\font\texti=cmmi10 scaled \mainmagstep
\font\textsy=cmsy10 scaled \mainmagstep
\def\textecsize{1095}
% A few fonts for @defun names and args.
\setfont\defbf\bfshape{10}{\magstep1}{OT1}
\setfont\deftt\ttshape{10}{\magstep1}{OT1TT}
\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT}
\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
% Fonts for indices, footnotes, small examples (9pt).
\def\smallnominalsize{9pt}
\setfont\smallrm\rmshape{9}{1000}{OT1}
\setfont\smalltt\ttshape{9}{1000}{OT1TT}
\setfont\smallbf\bfshape{10}{900}{OT1}
\setfont\smallit\itshape{9}{1000}{OT1IT}
\setfont\smallsl\slshape{9}{1000}{OT1}
\setfont\smallsf\sfshape{9}{1000}{OT1}
\setfont\smallsc\scshape{10}{900}{OT1}
\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
\font\smalli=cmmi9
\font\smallsy=cmsy9
\def\smallecsize{0900}
% Fonts for small examples (8pt).
\def\smallernominalsize{8pt}
\setfont\smallerrm\rmshape{8}{1000}{OT1}
\setfont\smallertt\ttshape{8}{1000}{OT1TT}
\setfont\smallerbf\bfshape{10}{800}{OT1}
\setfont\smallerit\itshape{8}{1000}{OT1IT}
\setfont\smallersl\slshape{8}{1000}{OT1}
\setfont\smallersf\sfshape{8}{1000}{OT1}
\setfont\smallersc\scshape{10}{800}{OT1}
\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
\font\smalleri=cmmi8
\font\smallersy=cmsy8
\def\smallerecsize{0800}
% Fonts for title page (20.4pt):
\def\titlenominalsize{20pt}
\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
\let\titlebf=\titlerm
\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
\font\titlei=cmmi12 scaled \magstep3
\font\titlesy=cmsy10 scaled \magstep4
\def\titleecsize{2074}
% Chapter (and unnumbered) fonts (17.28pt).
\def\chapnominalsize{17pt}
\setfont\chaprm\rmbshape{12}{\magstep2}{OT1}
\setfont\chapit\itbshape{10}{\magstep3}{OT1IT}
\setfont\chapsl\slbshape{10}{\magstep3}{OT1}
\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT}
\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT}
\setfont\chapsf\sfbshape{17}{1000}{OT1}
\let\chapbf=\chaprm
\setfont\chapsc\scbshape{10}{\magstep3}{OT1}
\font\chapi=cmmi12 scaled \magstep2
\font\chapsy=cmsy10 scaled \magstep3
\def\chapecsize{1728}
% Section fonts (14.4pt).
\def\secnominalsize{14pt}
\setfont\secrm\rmbshape{12}{\magstep1}{OT1}
\setfont\secit\itbshape{10}{\magstep2}{OT1IT}
\setfont\secsl\slbshape{10}{\magstep2}{OT1}
\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT}
\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT}
\setfont\secsf\sfbshape{12}{\magstep1}{OT1}
\let\secbf\secrm
\setfont\secsc\scbshape{10}{\magstep2}{OT1}
\font\seci=cmmi12 scaled \magstep1
\font\secsy=cmsy10 scaled \magstep2
\def\sececsize{1440}
% Subsection fonts (13.15pt).
\def\ssecnominalsize{13pt}
\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1}
\setfont\ssecit\itbshape{10}{1315}{OT1IT}
\setfont\ssecsl\slbshape{10}{1315}{OT1}
\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT}
\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT}
\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1}
\let\ssecbf\ssecrm
\setfont\ssecsc\scbshape{10}{1315}{OT1}
\font\sseci=cmmi12 scaled \magstephalf
\font\ssecsy=cmsy10 scaled 1315
\def\ssececsize{1200}
% Reduced fonts for @acro in text (10pt).
\def\reducednominalsize{10pt}
\setfont\reducedrm\rmshape{10}{1000}{OT1}
\setfont\reducedtt\ttshape{10}{1000}{OT1TT}
\setfont\reducedbf\bfshape{10}{1000}{OT1}
\setfont\reducedit\itshape{10}{1000}{OT1IT}
\setfont\reducedsl\slshape{10}{1000}{OT1}
\setfont\reducedsf\sfshape{10}{1000}{OT1}
\setfont\reducedsc\scshape{10}{1000}{OT1}
\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT}
\font\reducedi=cmmi10
\font\reducedsy=cmsy10
\def\reducedecsize{1000}
\textleading = 13.2pt % line spacing for 11pt CM
\textfonts % reset the current fonts
\rm
} % end of 11pt text font size definitions, \definetextfontsizexi
% Definitions to make the main text be 10pt Computer Modern, with
% section, chapter, etc., sizes following suit. This is for the GNU
% Press printing of the Emacs 22 manual. Maybe other manuals in the
% future. Used with @smallbook, which sets the leading to 12pt.
%
\def\definetextfontsizex{%
% Text fonts (10pt).
\def\textnominalsize{10pt}
\edef\mainmagstep{1000}
\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
\font\texti=cmmi10 scaled \mainmagstep
\font\textsy=cmsy10 scaled \mainmagstep
\def\textecsize{1000}
% A few fonts for @defun names and args.
\setfont\defbf\bfshape{10}{\magstephalf}{OT1}
\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT}
\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT}
\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
% Fonts for indices, footnotes, small examples (9pt).
\def\smallnominalsize{9pt}
\setfont\smallrm\rmshape{9}{1000}{OT1}
\setfont\smalltt\ttshape{9}{1000}{OT1TT}
\setfont\smallbf\bfshape{10}{900}{OT1}
\setfont\smallit\itshape{9}{1000}{OT1IT}
\setfont\smallsl\slshape{9}{1000}{OT1}
\setfont\smallsf\sfshape{9}{1000}{OT1}
\setfont\smallsc\scshape{10}{900}{OT1}
\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
\font\smalli=cmmi9
\font\smallsy=cmsy9
\def\smallecsize{0900}
% Fonts for small examples (8pt).
\def\smallernominalsize{8pt}
\setfont\smallerrm\rmshape{8}{1000}{OT1}
\setfont\smallertt\ttshape{8}{1000}{OT1TT}
\setfont\smallerbf\bfshape{10}{800}{OT1}
\setfont\smallerit\itshape{8}{1000}{OT1IT}
\setfont\smallersl\slshape{8}{1000}{OT1}
\setfont\smallersf\sfshape{8}{1000}{OT1}
\setfont\smallersc\scshape{10}{800}{OT1}
\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
\font\smalleri=cmmi8
\font\smallersy=cmsy8
\def\smallerecsize{0800}
% Fonts for title page (20.4pt):
\def\titlenominalsize{20pt}
\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
\let\titlebf=\titlerm
\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
\font\titlei=cmmi12 scaled \magstep3
\font\titlesy=cmsy10 scaled \magstep4
\def\titleecsize{2074}
% Chapter fonts (14.4pt).
\def\chapnominalsize{14pt}
\setfont\chaprm\rmbshape{12}{\magstep1}{OT1}
\setfont\chapit\itbshape{10}{\magstep2}{OT1IT}
\setfont\chapsl\slbshape{10}{\magstep2}{OT1}
\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT}
\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT}
\setfont\chapsf\sfbshape{12}{\magstep1}{OT1}
\let\chapbf\chaprm
\setfont\chapsc\scbshape{10}{\magstep2}{OT1}
\font\chapi=cmmi12 scaled \magstep1
\font\chapsy=cmsy10 scaled \magstep2
\def\chapecsize{1440}
% Section fonts (12pt).
\def\secnominalsize{12pt}
\setfont\secrm\rmbshape{12}{1000}{OT1}
\setfont\secit\itbshape{10}{\magstep1}{OT1IT}
\setfont\secsl\slbshape{10}{\magstep1}{OT1}
\setfont\sectt\ttbshape{12}{1000}{OT1TT}
\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT}
\setfont\secsf\sfbshape{12}{1000}{OT1}
\let\secbf\secrm
\setfont\secsc\scbshape{10}{\magstep1}{OT1}
\font\seci=cmmi12
\font\secsy=cmsy10 scaled \magstep1
\def\sececsize{1200}
% Subsection fonts (10pt).
\def\ssecnominalsize{10pt}
\setfont\ssecrm\rmbshape{10}{1000}{OT1}
\setfont\ssecit\itbshape{10}{1000}{OT1IT}
\setfont\ssecsl\slbshape{10}{1000}{OT1}
\setfont\ssectt\ttbshape{10}{1000}{OT1TT}
\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT}
\setfont\ssecsf\sfbshape{10}{1000}{OT1}
\let\ssecbf\ssecrm
\setfont\ssecsc\scbshape{10}{1000}{OT1}
\font\sseci=cmmi10
\font\ssecsy=cmsy10
\def\ssececsize{1000}
% Reduced fonts for @acro in text (9pt).
\def\reducednominalsize{9pt}
\setfont\reducedrm\rmshape{9}{1000}{OT1}
\setfont\reducedtt\ttshape{9}{1000}{OT1TT}
\setfont\reducedbf\bfshape{10}{900}{OT1}
\setfont\reducedit\itshape{9}{1000}{OT1IT}
\setfont\reducedsl\slshape{9}{1000}{OT1}
\setfont\reducedsf\sfshape{9}{1000}{OT1}
\setfont\reducedsc\scshape{10}{900}{OT1}
\setfont\reducedttsl\ttslshape{10}{900}{OT1TT}
\font\reducedi=cmmi9
\font\reducedsy=cmsy9
\def\reducedecsize{0900}
\divide\parskip by 2 % reduce space between paragraphs
\textleading = 12pt % line spacing for 10pt CM
\textfonts % reset the current fonts
\rm
} % end of 10pt text font size definitions, \definetextfontsizex
% We provide the user-level command
% @fonttextsize 10
% (or 11) to redefine the text font size. pt is assumed.
%
\def\xiword{11}
\def\xword{10}
\def\xwordpt{10pt}
%
\parseargdef\fonttextsize{%
\def\textsizearg{#1}%
%\wlog{doing @fonttextsize \textsizearg}%
%
% Set \globaldefs so that documents can use this inside @tex, since
% makeinfo 4.8 does not support it, but we need it nonetheless.
%
\begingroup \globaldefs=1
\ifx\textsizearg\xword \definetextfontsizex
\else \ifx\textsizearg\xiword \definetextfontsizexi
\else
\errhelp=\EMsimple
\errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'}
\fi\fi
\endgroup
}
% In order for the font changes to affect most math symbols and letters,
% we have to define the \textfont of the standard families. Since
% texinfo doesn't allow for producing subscripts and superscripts except
% in the main text, we don't bother to reset \scriptfont and
% \scriptscriptfont (which would also require loading a lot more fonts).
%
\def\resetmathfonts{%
\textfont0=\tenrm \textfont1=\teni \textfont2=\tensy
\textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf
\textfont\ttfam=\tentt \textfont\sffam=\tensf
}
% The font-changing commands redefine the meanings of \tenSTYLE, instead
% of just \STYLE. We do this because \STYLE needs to also set the
% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire
% \tenSTYLE to set the current font.
%
% Each font-changing command also sets the names \lsize (one size lower)
% and \lllsize (three sizes lower). These relative commands are used in
% the LaTeX logo and acronyms.
%
% This all needs generalizing, badly.
%
\def\textfonts{%
\let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
\let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
\let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy
\let\tenttsl=\textttsl
\def\curfontsize{text}%
\def\lsize{reduced}\def\lllsize{smaller}%
\resetmathfonts \setleading{\textleading}}
\def\titlefonts{%
\let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
\let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
\let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy
\let\tenttsl=\titlettsl
\def\curfontsize{title}%
\def\lsize{chap}\def\lllsize{subsec}%
\resetmathfonts \setleading{27pt}}
\def\titlefont#1{{\titlefonts\rmisbold #1}}
\def\chapfonts{%
\let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
\let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
\let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy
\let\tenttsl=\chapttsl
\def\curfontsize{chap}%
\def\lsize{sec}\def\lllsize{text}%
\resetmathfonts \setleading{19pt}}
\def\secfonts{%
\let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl
\let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc
\let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy
\let\tenttsl=\secttsl
\def\curfontsize{sec}%
\def\lsize{subsec}\def\lllsize{reduced}%
\resetmathfonts \setleading{16pt}}
\def\subsecfonts{%
\let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl
\let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc
\let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy
\let\tenttsl=\ssecttsl
\def\curfontsize{ssec}%
\def\lsize{text}\def\lllsize{small}%
\resetmathfonts \setleading{15pt}}
\let\subsubsecfonts = \subsecfonts
\def\reducedfonts{%
\let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl
\let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc
\let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy
\let\tenttsl=\reducedttsl
\def\curfontsize{reduced}%
\def\lsize{small}\def\lllsize{smaller}%
\resetmathfonts \setleading{10.5pt}}
\def\smallfonts{%
\let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl
\let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
\let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
\let\tenttsl=\smallttsl
\def\curfontsize{small}%
\def\lsize{smaller}\def\lllsize{smaller}%
\resetmathfonts \setleading{10.5pt}}
\def\smallerfonts{%
\let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl
\let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc
\let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy
\let\tenttsl=\smallerttsl
\def\curfontsize{smaller}%
\def\lsize{smaller}\def\lllsize{smaller}%
\resetmathfonts \setleading{9.5pt}}
% Fonts for short table of contents.
\setfont\shortcontrm\rmshape{12}{1000}{OT1}
\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12
\setfont\shortcontsl\slshape{12}{1000}{OT1}
\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
% Define these just so they can be easily changed for other fonts.
\def\angleleft{$\langle$}
\def\angleright{$\rangle$}
% Set the fonts to use with the @small... environments.
\let\smallexamplefonts = \smallfonts
% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample
% can fit this many characters:
% 8.5x11=86 smallbook=72 a4=90 a5=69
% If we use \scriptfonts (8pt), then we can fit this many characters:
% 8.5x11=90+ smallbook=80 a4=90+ a5=77
% For me, subjectively, the few extra characters that fit aren't worth
% the additional smallness of 8pt. So I'm making the default 9pt.
%
% By the way, for comparison, here's what fits with @example (10pt):
% 8.5x11=71 smallbook=60 a4=75 a5=58
% --karl, 24jan03.
% Set up the default fonts, so we can use them for creating boxes.
%
\definetextfontsizexi
\message{markup,}
% 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 }
% Markup style infrastructure. \defmarkupstylesetup\INITMACRO will
% define and register \INITMACRO to be called on markup style changes.
% \INITMACRO can check \currentmarkupstyle for the innermost
% style and the set of \ifmarkupSTYLE switches for all styles
% currently in effect.
\newif\ifmarkupvar
\newif\ifmarkupsamp
\newif\ifmarkupkey
%\newif\ifmarkupfile % @file == @samp.
%\newif\ifmarkupoption % @option == @samp.
\newif\ifmarkupcode
\newif\ifmarkupkbd
%\newif\ifmarkupenv % @env == @code.
%\newif\ifmarkupcommand % @command == @code.
\newif\ifmarkuptex % @tex (and part of @math, for now).
\newif\ifmarkupexample
\newif\ifmarkupverb
\newif\ifmarkupverbatim
\let\currentmarkupstyle\empty
\def\setupmarkupstyle#1{%
\csname markup#1true\endcsname
\def\currentmarkupstyle{#1}%
\markupstylesetup
}
\let\markupstylesetup\empty
\def\defmarkupstylesetup#1{%
\expandafter\def\expandafter\markupstylesetup
\expandafter{\markupstylesetup #1}%
\def#1%
}
% Markup style setup for left and right quotes.
\defmarkupstylesetup\markupsetuplq{%
\expandafter\let\expandafter \temp
\csname markupsetuplq\currentmarkupstyle\endcsname
\ifx\temp\relax \markupsetuplqdefault \else \temp \fi
}
\defmarkupstylesetup\markupsetuprq{%
\expandafter\let\expandafter \temp
\csname markupsetuprq\currentmarkupstyle\endcsname
\ifx\temp\relax \markupsetuprqdefault \else \temp \fi
}
{
\catcode`\'=\active
\catcode`\`=\active
\gdef\markupsetuplqdefault{\let`\lq}
\gdef\markupsetuprqdefault{\let'\rq}
\gdef\markupsetcodequoteleft{\let`\codequoteleft}
\gdef\markupsetcodequoteright{\let'\codequoteright}
}
\let\markupsetuplqcode \markupsetcodequoteleft
\let\markupsetuprqcode \markupsetcodequoteright
%
\let\markupsetuplqexample \markupsetcodequoteleft
\let\markupsetuprqexample \markupsetcodequoteright
%
\let\markupsetuplqkbd \markupsetcodequoteleft
\let\markupsetuprqkbd \markupsetcodequoteright
%
\let\markupsetuplqsamp \markupsetcodequoteleft
\let\markupsetuprqsamp \markupsetcodequoteright
%
\let\markupsetuplqverb \markupsetcodequoteleft
\let\markupsetuprqverb \markupsetcodequoteright
%
\let\markupsetuplqverbatim \markupsetcodequoteleft
\let\markupsetuprqverbatim \markupsetcodequoteright
% Allow an option to not use regular directed right quote/apostrophe
% (char 0x27), but instead the undirected quote from cmtt (char 0x0d).
% The undirected quote is ugly, so don't make it the default, but it
% works for pasting with more pdf viewers (at least evince), the
% lilypond developers report. xpdf does work with the regular 0x27.
%
\def\codequoteright{%
\expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
\expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
'%
\else \char'15 \fi
\else \char'15 \fi
}
%
% and a similar option for the left quote char vs. a grave accent.
% Modern fonts display ASCII 0x60 as a grave accent, so some people like
% the code environments to do likewise.
%
\def\codequoteleft{%
\expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
\expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
% [Knuth] pp. 380,381,391
% \relax disables Spanish ligatures ?` and !` of \tt font.
\relax`%
\else \char'22 \fi
\else \char'22 \fi
}
% Commands to set the quote options.
%
\parseargdef\codequoteundirected{%
\def\temp{#1}%
\ifx\temp\onword
\expandafter\let\csname SETtxicodequoteundirected\endcsname
= t%
\else\ifx\temp\offword
\expandafter\let\csname SETtxicodequoteundirected\endcsname
= \relax
\else
\errhelp = \EMsimple
\errmessage{Unknown @codequoteundirected value `\temp', must be on|off}%
\fi\fi
}
%
\parseargdef\codequotebacktick{%
\def\temp{#1}%
\ifx\temp\onword
\expandafter\let\csname SETtxicodequotebacktick\endcsname
= t%
\else\ifx\temp\offword
\expandafter\let\csname SETtxicodequotebacktick\endcsname
= \relax
\else
\errhelp = \EMsimple
\errmessage{Unknown @codequotebacktick value `\temp', must be on|off}%
\fi\fi
}
% [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font.
\def\noligaturesquoteleft{\relax\lq}
% Count depth in font-changes, for error checks
\newcount\fontdepth \fontdepth=0
% Font commands.
% #1 is the font command (\sl or \it), #2 is the text to slant.
% If we are in a monospaced environment, however, 1) always use \ttsl,
% and 2) do not add an italic correction.
\def\dosmartslant#1#2{%
\ifusingtt
{{\ttsl #2}\let\next=\relax}%
{\def\next{{#1#2}\futurelet\next\smartitaliccorrection}}%
\next
}
\def\smartslanted{\dosmartslant\sl}
\def\smartitalic{\dosmartslant\it}
% Output an italic correction unless \next (presumed to be the following
% character) is such as not to need one.
\def\smartitaliccorrection{%
\ifx\next,%
\else\ifx\next-%
\else\ifx\next.%
\else\ifx\next\.%
\else\ifx\next\comma%
\else\ptexslash
\fi\fi\fi\fi\fi
\aftersmartic
}
% Unconditional use \ttsl, and no ic. @var is set to this for defuns.
\def\ttslanted#1{{\ttsl #1}}
% @cite is like \smartslanted except unconditionally use \sl. We never want
% ttsl for book titles, do we?
\def\cite#1{{\sl #1}\futurelet\next\smartitaliccorrection}
\def\aftersmartic{}
\def\var#1{%
\let\saveaftersmartic = \aftersmartic
\def\aftersmartic{\null\let\aftersmartic=\saveaftersmartic}%
\smartslanted{#1}%
}
\let\i=\smartitalic
\let\slanted=\smartslanted
\let\dfn=\smartslanted
\let\emph=\smartitalic
% Explicit font changes: @r, @sc, undocumented @ii.
\def\r#1{{\rm #1}} % roman font
\def\sc#1{{\smallcaps#1}} % smallcaps font
\def\ii#1{{\it #1}} % italic font
% @b, explicit bold. Also @strong.
\def\b#1{{\bf #1}}
\let\strong=\b
% @sansserif, explicit sans.
\def\sansserif#1{{\sf #1}}
% We can't just use \exhyphenpenalty, because that only has effect at
% the end of a paragraph. Restore normal hyphenation at the end of the
% group within which \nohyphenation is presumably called.
%
\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation}
\def\restorehyphenation{\hyphenchar\font = `- }
% Set sfcode to normal for the chars that usually have another value.
% Can't use plain's \frenchspacing because it uses the `\x notation, and
% sometimes \x has an active definition that messes things up.
%
\catcode`@=11
\def\plainfrenchspacing{%
\sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m
\sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m
\def\endofsentencespacefactor{1000}% for @. and friends
}
\def\plainnonfrenchspacing{%
\sfcode`\.3000\sfcode`\?3000\sfcode`\!3000
\sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
\def\endofsentencespacefactor{3000}% for @. and friends
}
\catcode`@=\other
\def\endofsentencespacefactor{3000}% default
% @t, explicit typewriter.
\def\t#1{%
{\tt \rawbackslash \plainfrenchspacing #1}%
\null
}
% @samp.
\def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}}
% @indicateurl is \samp, that is, with quotes.
\let\indicateurl=\samp
% @code (and similar) prints in typewriter, but with spaces the same
% size as normal in the surrounding text, without hyphenation, etc.
% This is a subroutine for that.
\def\tclose#1{%
{%
% Change normal interword space to be same as for the current font.
\spaceskip = \fontdimen2\font
%
% Switch to typewriter.
\tt
%
% But `\ ' produces the large typewriter interword space.
\def\ {{\spaceskip = 0pt{} }}%
%
% Turn off hyphenation.
\nohyphenation
%
\rawbackslash
\plainfrenchspacing
#1%
}%
\null % reset spacefactor to 1000
}
% We *must* turn on hyphenation at `-' and `_' in @code.
% (But see \codedashfinish below.)
% Otherwise, it is too hard to avoid overfull hboxes
% in the Emacs manual, the Library manual, etc.
%
% Unfortunately, TeX uses one parameter (\hyphenchar) to control
% both hyphenation at - and hyphenation within words.
% We must therefore turn them both off (\tclose does that)
% and arrange explicitly to hyphenate at a dash. -- rms.
{
\catcode`\-=\active \catcode`\_=\active
\catcode`\'=\active \catcode`\`=\active
\global\let'=\rq \global\let`=\lq % default definitions
%
\global\def\code{\begingroup
\setupmarkupstyle{code}%
% The following should really be moved into \setupmarkupstyle handlers.
\catcode\dashChar=\active \catcode\underChar=\active
\ifallowcodebreaks
\let-\codedash
\let_\codeunder
\else
\let-\normaldash
\let_\realunder
\fi
% Given -foo (with a single dash), we do not want to allow a break
% after the hyphen.
\global\let\codedashprev=\codedash
%
\codex
}
%
\gdef\codedash{\futurelet\next\codedashfinish}
\gdef\codedashfinish{%
\normaldash % always output the dash character itself.
%
% Now, output a discretionary to allow a line break, unless
% (a) the next character is a -, or
% (b) the preceding character is a -.
% E.g., given --posix, we do not want to allow a break after either -.
% Given --foo-bar, we do want to allow a break between the - and the b.
\ifx\next\codedash \else
\ifx\codedashprev\codedash
\else \discretionary{}{}{}\fi
\fi
% we need the space after the = for the case when \next itself is a
% space token; it would get swallowed otherwise. As in @code{- a}.
\global\let\codedashprev= \next
}
}
\def\normaldash{-}
%
\def\codex #1{\tclose{#1}\endgroup}
\def\codeunder{%
% this is all so @math{@code{var_name}+1} can work. In math mode, _
% is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.)
% will therefore expand the active definition of _, which is us
% (inside @code that is), therefore an endless loop.
\ifusingtt{\ifmmode
\mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_.
\else\normalunderscore \fi
\discretionary{}{}{}}%
{\_}%
}
% An additional complication: the above will allow breaks after, e.g.,
% each of the four underscores in __typeof__. This is bad.
% @allowcodebreaks provides a document-level way to turn breaking at -
% and _ on and off.
%
\newif\ifallowcodebreaks \allowcodebreakstrue
\def\keywordtrue{true}
\def\keywordfalse{false}
\parseargdef\allowcodebreaks{%
\def\txiarg{#1}%
\ifx\txiarg\keywordtrue
\allowcodebreakstrue
\else\ifx\txiarg\keywordfalse
\allowcodebreaksfalse
\else
\errhelp = \EMsimple
\errmessage{Unknown @allowcodebreaks option `\txiarg', must be true|false}%
\fi\fi
}
% For @command, @env, @file, @option quotes seem unnecessary,
% so use \code rather than \samp.
\let\command=\code
\let\env=\code
\let\file=\code
\let\option=\code
% @uref (abbreviation for `urlref') takes an optional (comma-separated)
% second argument specifying the text to display and an optional third
% arg as text to display instead of (rather than in addition to) the url
% itself. First (mandatory) arg is the url.
% (This \urefnobreak definition isn't used now, leaving it for a while
% for comparison.)
\def\urefnobreak#1{\dourefnobreak #1,,,\finish}
\def\dourefnobreak#1,#2,#3,#4\finish{\begingroup
\unsepspaces
\pdfurl{#1}%
\setbox0 = \hbox{\ignorespaces #3}%
\ifdim\wd0 > 0pt
\unhbox0 % third arg given, show only that
\else
\setbox0 = \hbox{\ignorespaces #2}%
\ifdim\wd0 > 0pt
\ifpdf
\unhbox0 % PDF: 2nd arg given, show only it
\else
\unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url
\fi
\else
\code{#1}% only url given, so show it
\fi
\fi
\endlink
\endgroup}
% This \urefbreak definition is the active one.
\def\urefbreak{\begingroup \urefcatcodes \dourefbreak}
\let\uref=\urefbreak
\def\dourefbreak#1{\urefbreakfinish #1,,,\finish}
\def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example
\unsepspaces
\pdfurl{#1}%
\setbox0 = \hbox{\ignorespaces #3}%
\ifdim\wd0 > 0pt
\unhbox0 % third arg given, show only that
\else
\setbox0 = \hbox{\ignorespaces #2}%
\ifdim\wd0 > 0pt
\ifpdf
\unhbox0 % PDF: 2nd arg given, show only it
\else
\unhbox0\ (\urefcode{#1})% DVI: 2nd arg given, show both it and url
\fi
\else
\urefcode{#1}% only url given, so show it
\fi
\fi
\endlink
\endgroup}
% Allow line breaks around only a few characters (only).
\def\urefcatcodes{%
\catcode\ampChar=\active \catcode\dotChar=\active
\catcode\hashChar=\active \catcode\questChar=\active
\catcode\slashChar=\active
}
{
\urefcatcodes
%
\global\def\urefcode{\begingroup
\setupmarkupstyle{code}%
\urefcatcodes
\let&\urefcodeamp
\let.\urefcodedot
\let#\urefcodehash
\let?\urefcodequest
\let/\urefcodeslash
\codex
}
%
% By default, they are just regular characters.
\global\def&{\normalamp}
\global\def.{\normaldot}
\global\def#{\normalhash}
\global\def?{\normalquest}
\global\def/{\normalslash}
}
% we put a little stretch before and after the breakable chars, to help
% line breaking of long url's. The unequal skips make look better in
% cmtt at least, especially for dots.
\def\urefprestretch{\urefprebreak \hskip0pt plus.13em }
\def\urefpoststretch{\urefpostbreak \hskip0pt plus.1em }
%
\def\urefcodeamp{\urefprestretch \&\urefpoststretch}
\def\urefcodedot{\urefprestretch .\urefpoststretch}
\def\urefcodehash{\urefprestretch \#\urefpoststretch}
\def\urefcodequest{\urefprestretch ?\urefpoststretch}
\def\urefcodeslash{\futurelet\next\urefcodeslashfinish}
{
\catcode`\/=\active
\global\def\urefcodeslashfinish{%
\urefprestretch \slashChar
% Allow line break only after the final / in a sequence of
% slashes, to avoid line break between the slashes in http://.
\ifx\next/\else \urefpoststretch \fi
}
}
% One more complication: by default we'll break after the special
% characters, but some people like to break before the special chars, so
% allow that. Also allow no breaking at all, for manual control.
%
\parseargdef\urefbreakstyle{%
\def\txiarg{#1}%
\ifx\txiarg\wordnone
\def\urefprebreak{\nobreak}\def\urefpostbreak{\nobreak}
\else\ifx\txiarg\wordbefore
\def\urefprebreak{\allowbreak}\def\urefpostbreak{\nobreak}
\else\ifx\txiarg\wordafter
\def\urefprebreak{\nobreak}\def\urefpostbreak{\allowbreak}
\else
\errhelp = \EMsimple
\errmessage{Unknown @urefbreakstyle setting `\txiarg'}%
\fi\fi\fi
}
\def\wordafter{after}
\def\wordbefore{before}
\def\wordnone{none}
\urefbreakstyle after
% @url synonym for @uref, since that's how everyone uses it.
%
\let\url=\uref
% rms does not like angle brackets --karl, 17may97.
% So now @email is just like @uref, unless we are pdf.
%
%\def\email#1{\angleleft{\tt #1}\angleright}
\ifpdf
\def\email#1{\doemail#1,,\finish}
\def\doemail#1,#2,#3\finish{\begingroup
\unsepspaces
\pdfurl{mailto:#1}%
\setbox0 = \hbox{\ignorespaces #2}%
\ifdim\wd0>0pt\unhbox0\else\code{#1}\fi
\endlink
\endgroup}
\else
\let\email=\uref
\fi
% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
% `example' (@kbd uses ttsl only inside of @example and friends),
% or `code' (@kbd uses normal tty font always).
\parseargdef\kbdinputstyle{%
\def\txiarg{#1}%
\ifx\txiarg\worddistinct
\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%
\else\ifx\txiarg\wordexample
\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%
\else\ifx\txiarg\wordcode
\gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%
\else
\errhelp = \EMsimple
\errmessage{Unknown @kbdinputstyle setting `\txiarg'}%
\fi\fi\fi
}
\def\worddistinct{distinct}
\def\wordexample{example}
\def\wordcode{code}
% Default is `distinct'.
\kbdinputstyle distinct
% @kbd is like @code, except that if the argument is just one @key command,
% then @kbd has no effect.
\def\kbd#1{{\def\look{#1}\expandafter\kbdsub\look??\par}}
\def\xkey{\key}
\def\kbdsub#1#2#3\par{%
\def\one{#1}\def\three{#3}\def\threex{??}%
\ifx\one\xkey\ifx\threex\three \key{#2}%
\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
}
% definition of @key that produces a lozenge. Doesn't adjust to text size.
%\setfont\keyrm\rmshape{8}{1000}{OT1}
%\font\keysy=cmsy9
%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
% \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
% \vbox{\hrule\kern-0.4pt
% \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
% \kern-0.4pt\hrule}%
% \kern-.06em\raise0.4pt\hbox{\angleright}}}}
% definition of @key with no lozenge. If the current font is already
% monospace, don't change it; that way, we respect @kbdinputstyle. But
% if it isn't monospace, then use \tt.
%
\def\key#1{{\setupmarkupstyle{key}%
\nohyphenation
\ifmonospace\else\tt\fi
#1}\null}
% @clicksequence{File @click{} Open ...}
\def\clicksequence#1{\begingroup #1\endgroup}
% @clickstyle @arrow (by default)
\parseargdef\clickstyle{\def\click{#1}}
\def\click{\arrow}
% 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}
% @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}
% @acronym for "FBI", "NATO", and the like.
% We print this one point size smaller, since it's intended for
% all-uppercase.
%
\def\acronym#1{\doacronym #1,,\finish}
\def\doacronym#1,#2,#3\finish{%
{\selectfonts\lsize #1}%
\def\temp{#2}%
\ifx\temp\empty \else
\space ({\unsepspaces \ignorespaces \temp \unskip})%
\fi
\null % reset \spacefactor=1000
}
% @abbr for "Comput. J." and the like.
% No font change, but don't do end-of-sentence spacing.
%
\def\abbr#1{\doabbr #1,,\finish}
\def\doabbr#1,#2,#3\finish{%
{\plainfrenchspacing #1}%
\def\temp{#2}%
\ifx\temp\empty \else
\space ({\unsepspaces \ignorespaces \temp \unskip})%
\fi
\null % reset \spacefactor=1000
}
% @asis just yields its argument. Used with @table, for example.
%
\def\asis#1{#1}
% @math outputs its argument in math mode.
%
% One complication: _ usually means subscripts, but it could also mean
% an actual _ character, as in @math{@var{some_variable} + 1}. So make
% _ active, and distinguish by seeing if the current family is \slfam,
% which is what @var uses.
{
\catcode`\_ = \active
\gdef\mathunderscore{%
\catcode`\_=\active
\def_{\ifnum\fam=\slfam \_\else\sb\fi}%
}
}
% Another complication: we want \\ (and @\) to output a math (or tt) \.
% FYI, plain.tex uses \\ as a temporary control sequence (for no
% particular reason), but this is not advertised and we don't care.
%
% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
%
\def\math{%
\tex
\mathunderscore
\let\\ = \mathbackslash
\mathactive
% make the texinfo accent commands work in math mode
\let\"=\ddot
\let\'=\acute
\let\==\bar
\let\^=\hat
\let\`=\grave
\let\u=\breve
\let\v=\check
\let\~=\tilde
\let\dotaccent=\dot
$\finishmath
}
\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex.
% Some active characters (such as <) are spaced differently in math.
% We have to reset their definitions in case the @math was an argument
% to a command which sets the catcodes (such as @item or @section).
%
{
\catcode`^ = \active
\catcode`< = \active
\catcode`> = \active
\catcode`+ = \active
\catcode`' = \active
\gdef\mathactive{%
\let^ = \ptexhat
\let< = \ptexless
\let> = \ptexgtr
\let+ = \ptexplus
\let' = \ptexquoteright
}
}
% ctrl is no longer a Texinfo command, but leave this definition for fun.
\def\ctrl #1{{\tt \rawbackslash \hat}#1}
% @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}.
% Ignore unless FMTNAME == tex; then it is like @iftex and @tex,
% except specified as a normal braced arg, so no newlines to worry about.
%
\def\outfmtnametex{tex}
%
\long\def\inlinefmt#1{\doinlinefmt #1,\finish}
\long\def\doinlinefmt#1,#2,\finish{%
\def\inlinefmtname{#1}%
\ifx\inlinefmtname\outfmtnametex \ignorespaces #2\fi
}
%
% @inlinefmtifelse{FMTNAME,THEN-TEXT,ELSE-TEXT} expands THEN-TEXT if
% FMTNAME is tex, else ELSE-TEXT.
\long\def\inlinefmtifelse#1{\doinlinefmtifelse #1,,,\finish}
\long\def\doinlinefmtifelse#1,#2,#3,#4,\finish{%
\def\inlinefmtname{#1}%
\ifx\inlinefmtname\outfmtnametex \ignorespaces #2\else \ignorespaces #3\fi
}
%
% For raw, must switch into @tex before parsing the argument, to avoid
% setting catcodes prematurely. Doing it this way means that, for
% example, @inlineraw{html, foo{bar} gets a parse error instead of being
% ignored. But this isn't important because if people want a literal
% *right* brace they would have to use a command anyway, so they may as
% well use a command to get a left brace too. We could re-use the
% delimiter character idea from \verb, but it seems like overkill.
%
\long\def\inlineraw{\tex \doinlineraw}
\long\def\doinlineraw#1{\doinlinerawtwo #1,\finish}
\def\doinlinerawtwo#1,#2,\finish{%
\def\inlinerawname{#1}%
\ifx\inlinerawname\outfmtnametex \ignorespaces #2\fi
\endgroup % close group opened by \tex.
}
% @inlineifset{VAR, TEXT} expands TEXT if VAR is @set.
%
\long\def\inlineifset#1{\doinlineifset #1,\finish}
\long\def\doinlineifset#1,#2,\finish{%
\def\inlinevarname{#1}%
\expandafter\ifx\csname SET\inlinevarname\endcsname\relax
\else\ignorespaces#2\fi
}
% @inlineifclear{VAR, TEXT} expands TEXT if VAR is not @set.
%
\long\def\inlineifclear#1{\doinlineifclear #1,\finish}
\long\def\doinlineifclear#1,#2,\finish{%
\def\inlinevarname{#1}%
\expandafter\ifx\csname SET\inlinevarname\endcsname\relax \ignorespaces#2\fi
}
\message{glyphs,}
% and logos.
% @@ prints an @, as does @atchar{}.
\def\@{\char64 }
\let\atchar=\@
% @{ @} @lbracechar{} @rbracechar{} all generate brace characters.
% Unless we're in typewriter, use \ecfont because the CM text fonts do
% not have braces, and we don't want to switch into math.
\def\mylbrace{{\ifmonospace\else\ecfont\fi \char123}}
\def\myrbrace{{\ifmonospace\else\ecfont\fi \char125}}
\let\{=\mylbrace \let\lbracechar=\{
\let\}=\myrbrace \let\rbracechar=\}
\begingroup
% Definitions to produce \{ and \} commands for indices,
% and @{ and @} for the aux/toc files.
\catcode`\{ = \other \catcode`\} = \other
\catcode`\[ = 1 \catcode`\] = 2
\catcode`\! = 0 \catcode`\\ = \other
!gdef!lbracecmd[\{]%
!gdef!rbracecmd[\}]%
!gdef!lbraceatcmd[@{]%
!gdef!rbraceatcmd[@}]%
!endgroup
% @comma{} to avoid , parsing problems.
\let\comma = ,
% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent
% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H.
\let\, = \ptexc
\let\dotaccent = \ptexdot
\def\ringaccent#1{{\accent23 #1}}
\let\tieaccent = \ptext
\let\ubaraccent = \ptexb
\let\udotaccent = \d
% Other special characters: @questiondown @exclamdown @ordf @ordm
% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss.
\def\questiondown{?`}
\def\exclamdown{!`}
\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}}
\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}}
% Dotless i and dotless j, used for accents.
\def\imacro{i}
\def\jmacro{j}
\def\dotless#1{%
\def\temp{#1}%
\ifx\temp\imacro \ifmmode\imath \else\ptexi \fi
\else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi
\else \errmessage{@dotless can be used only with i or j}%
\fi\fi
}
% The \TeX{} logo, as in plain, but resetting the spacing so that a
% period following counts as ending a sentence. (Idea found in latex.)
%
\edef\TeX{\TeX \spacefactor=1000 }
% @LaTeX{} logo. Not quite the same results as the definition in
% latex.ltx, since we use a different font for the raised A; it's most
% convenient for us to use an explicitly smaller font, rather than using
% the \scriptstyle font (since we don't reset \scriptstyle and
% \scriptscriptstyle).
%
\def\LaTeX{%
L\kern-.36em
{\setbox0=\hbox{T}%
\vbox to \ht0{\hbox{%
\ifx\textnominalsize\xwordpt
% for 10pt running text, \lllsize (8pt) is too small for the A in LaTeX.
% Revert to plain's \scriptsize, which is 7pt.
\count255=\the\fam $\fam\count255 \scriptstyle A$%
\else
% For 11pt, we can use our lllsize.
\selectfonts\lllsize A%
\fi
}%
\vss
}}%
\kern-.15em
\TeX
}
% Some math mode symbols.
\def\bullet{$\ptexbullet$}
\def\geq{\ifmmode \ge\else $\ge$\fi}
\def\leq{\ifmmode \le\else $\le$\fi}
\def\minus{\ifmmode -\else $-$\fi}
% @dots{} outputs an ellipsis using the current font.
% We do .5em per period so that it has the same spacing in the cm
% typewriter fonts as three actual period characters; on the other hand,
% in other typewriter fonts three periods are wider than 1.5em. So do
% whichever is larger.
%
\def\dots{%
\leavevmode
\setbox0=\hbox{...}% get width of three periods
\ifdim\wd0 > 1.5em
\dimen0 = \wd0
\else
\dimen0 = 1.5em
\fi
\hbox to \dimen0{%
\hskip 0pt plus.25fil
.\hskip 0pt plus1fil
.\hskip 0pt plus1fil
.\hskip 0pt plus.5fil
}%
}
% @enddots{} is an end-of-sentence ellipsis.
%
\def\enddots{%
\dots
\spacefactor=\endofsentencespacefactor
}
% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
%
% Since these characters are used in examples, they should be an even number of
% \tt widths. Each \tt character is 1en, so two makes it 1em.
%
\def\point{$\star$}
\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}}
\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}}
\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}}
% The @error{} command.
% Adapted from the TeXbook's \boxit.
%
\newbox\errorbox
%
{\tentt \global\dimen0 = 3em}% Width of the box.
\dimen2 = .55pt % Thickness of rules
% The text. (`r' is open on the right, `e' somewhat less so on the left.)
\setbox0 = \hbox{\kern-.75pt \reducedsf \putworderror\kern-1.5pt}
%
\setbox\errorbox=\hbox to \dimen0{\hfil
\hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
\advance\hsize by -2\dimen2 % Rules.
\vbox{%
\hrule height\dimen2
\hbox{\vrule width\dimen2 \kern3pt % Space to left of text.
\vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
\kern3pt\vrule width\dimen2}% Space to right.
\hrule height\dimen2}
\hfil}
%
\def\error{\leavevmode\lower.7ex\copy\errorbox}
% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
%
\def\pounds{{\it\$}}
% @euro{} comes from a separate font, depending on the current style.
% We use the free feym* fonts from the eurosym package by Henrik
% Theiling, which support regular, slanted, bold and bold slanted (and
% "outlined" (blackboard board, sort of) versions, which we don't need).
% It is available from http://www.ctan.org/tex-archive/fonts/eurosym.
%
% Although only regular is the truly official Euro symbol, we ignore
% that. The Euro is designed to be slightly taller than the regular
% font height.
%
% feymr - regular
% feymo - slanted
% feybr - bold
% feybo - bold slanted
%
% There is no good (free) typewriter version, to my knowledge.
% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide.
% Hmm.
%
% Also doesn't work in math. Do we need to do math with euro symbols?
% Hope not.
%
%
\def\euro{{\eurofont e}}
\def\eurofont{%
% We set the font at each command, rather than predefining it in
% \textfonts and the other font-switching commands, so that
% installations which never need the symbol don't have to have the
% font installed.
%
% There is only one designed size (nominal 10pt), so we always scale
% that to the current nominal size.
%
% By the way, simply using "at 1em" works for cmr10 and the like, but
% does not work for cmbx10 and other extended/shrunken fonts.
%
\def\eurosize{\csname\curfontsize nominalsize\endcsname}%
%
\ifx\curfontstyle\bfstylename
% bold:
\font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize
\else
% regular:
\font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize
\fi
\thiseurofont
}
% Glyphs from the EC fonts. We don't use \let for the aliases, because
% sometimes we redefine the original macro, and the alias should reflect
% the redefinition.
%
% Use LaTeX names for the Icelandic letters.
\def\DH{{\ecfont \char"D0}} % Eth
\def\dh{{\ecfont \char"F0}} % eth
\def\TH{{\ecfont \char"DE}} % Thorn
\def\th{{\ecfont \char"FE}} % thorn
%
\def\guillemetleft{{\ecfont \char"13}}
\def\guillemotleft{\guillemetleft}
\def\guillemetright{{\ecfont \char"14}}
\def\guillemotright{\guillemetright}
\def\guilsinglleft{{\ecfont \char"0E}}
\def\guilsinglright{{\ecfont \char"0F}}
\def\quotedblbase{{\ecfont \char"12}}
\def\quotesinglbase{{\ecfont \char"0D}}
%
% This positioning is not perfect (see the ogonek LaTeX package), but
% we have the precomposed glyphs for the most common cases. We put the
% tests to use those glyphs in the single \ogonek macro so we have fewer
% dummy definitions to worry about for index entries, etc.
%
% ogonek is also used with other letters in Lithuanian (IOU), but using
% the precomposed glyphs for those is not so easy since they aren't in
% the same EC font.
\def\ogonek#1{{%
\def\temp{#1}%
\ifx\temp\macrocharA\Aogonek
\else\ifx\temp\macrochara\aogonek
\else\ifx\temp\macrocharE\Eogonek
\else\ifx\temp\macrochare\eogonek
\else
\ecfont \setbox0=\hbox{#1}%
\ifdim\ht0=1ex\accent"0C #1%
\else\ooalign{\unhbox0\crcr\hidewidth\char"0C \hidewidth}%
\fi
\fi\fi\fi\fi
}%
}
\def\Aogonek{{\ecfont \char"81}}\def\macrocharA{A}
\def\aogonek{{\ecfont \char"A1}}\def\macrochara{a}
\def\Eogonek{{\ecfont \char"86}}\def\macrocharE{E}
\def\eogonek{{\ecfont \char"A6}}\def\macrochare{e}
%
% Use the ec* fonts (cm-super in outline format) for non-CM glyphs.
\def\ecfont{%
% We can't distinguish serif/sans and italic/slanted, but this
% is used for crude hacks anyway (like adding French and German
% quotes to documents typeset with CM, where we lose kerning), so
% hopefully nobody will notice/care.
\edef\ecsize{\csname\curfontsize ecsize\endcsname}%
\edef\nominalsize{\csname\curfontsize nominalsize\endcsname}%
\ifmonospace
% typewriter:
\font\thisecfont = ectt\ecsize \space at \nominalsize
\else
\ifx\curfontstyle\bfstylename
% bold:
\font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize
\else
% regular:
\font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize
\fi
\fi
\thisecfont
}
% @registeredsymbol - R in a circle. The font for the R should really
% be smaller yet, but lllsize is the best we can do for now.
% Adapted from the plain.tex definition of \copyright.
%
\def\registeredsymbol{%
$^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}%
\hfil\crcr\Orb}}%
}$%
}
% @textdegree - the normal degrees sign.
%
\def\textdegree{$^\circ$}
% Laurent Siebenmann reports \Orb undefined with:
% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38
% so we'll define it if necessary.
%
\ifx\Orb\thisisundefined
\def\Orb{\mathhexbox20D}
\fi
% Quotes.
\chardef\quotedblleft="5C
\chardef\quotedblright=`\"
\chardef\quoteleft=`\`
\chardef\quoteright=`\'
\message{page headings,}
\newskip\titlepagetopglue \titlepagetopglue = 1.5in
\newskip\titlepagebottomglue \titlepagebottomglue = 2pc
% First the title page. Must do @settitle before @titlepage.
\newif\ifseenauthor
\newif\iffinishedtitlepage
% Do an implicit @contents or @shortcontents after @end titlepage if the
% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.
%
\newif\ifsetcontentsaftertitlepage
\let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue
\newif\ifsetshortcontentsaftertitlepage
\let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue
\parseargdef\shorttitlepage{%
\begingroup \hbox{}\vskip 1.5in \chaprm \centerline{#1}%
\endgroup\page\hbox{}\page}
\envdef\titlepage{%
% Open one extra group, as we want to close it in the middle of \Etitlepage.
\begingroup
\parindent=0pt \textfonts
% Leave some space at the very top of the page.
\vglue\titlepagetopglue
% No rule at page bottom unless we print one at the top with @title.
\finishedtitlepagetrue
%
% Most title ``pages'' are actually two pages long, with space
% at the top of the second. We don't want the ragged left on the second.
\let\oldpage = \page
\def\page{%
\iffinishedtitlepage\else
\finishtitlepage
\fi
\let\page = \oldpage
\page
\null
}%
}
\def\Etitlepage{%
\iffinishedtitlepage\else
\finishtitlepage
\fi
% It is important to do the page break before ending the group,
% because the headline and footline are only empty inside the group.
% If we use the new definition of \page, we always get a blank page
% after the title page, which we certainly don't want.
\oldpage
\endgroup
%
% Need this before the \...aftertitlepage checks so that if they are
% in effect the toc pages will come out with page numbers.
\HEADINGSon
%
% If they want short, they certainly want long too.
\ifsetshortcontentsaftertitlepage
\shortcontents
\contents
\global\let\shortcontents = \relax
\global\let\contents = \relax
\fi
%
\ifsetcontentsaftertitlepage
\contents
\global\let\contents = \relax
\global\let\shortcontents = \relax
\fi
}
\def\finishtitlepage{%
\vskip4pt \hrule height 2pt width \hsize
\vskip\titlepagebottomglue
\finishedtitlepagetrue
}
% Settings used for typesetting titles: no hyphenation, no indentation,
% don't worry much about spacing, ragged right. This should be used
% inside a \vbox, and fonts need to be set appropriately first. Because
% it is always used for titles, nothing else, we call \rmisbold. \par
% should be specified before the end of the \vbox, since a vbox is a group.
%
\def\raggedtitlesettings{%
\rmisbold
\hyphenpenalty=10000
\parindent=0pt
\tolerance=5000
\ptexraggedright
}
% Macros to be used within @titlepage:
\let\subtitlerm=\tenrm
\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}
\parseargdef\title{%
\checkenv\titlepage
\vbox{\titlefonts \raggedtitlesettings #1\par}%
% print a rule at the page bottom also.
\finishedtitlepagefalse
\vskip4pt \hrule height 4pt width \hsize \vskip4pt
}
\parseargdef\subtitle{%
\checkenv\titlepage
{\subtitlefont \rightline{#1}}%
}
% @author should come last, but may come many times.
% It can also be used inside @quotation.
%
\parseargdef\author{%
\def\temp{\quotation}%
\ifx\thisenv\temp
\def\quotationauthor{#1}% printed in \Equotation.
\else
\checkenv\titlepage
\ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi
{\secfonts\rmisbold \leftline{#1}}%
\fi
}
% Set up page headings and footings.
\let\thispage=\folio
\newtoks\evenheadline % headline on even pages
\newtoks\oddheadline % headline on odd pages
\newtoks\evenfootline % footline on even pages
\newtoks\oddfootline % footline on odd pages
% Now make TeX use those variables
\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
\else \the\evenheadline \fi}}
\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
\else \the\evenfootline \fi}\HEADINGShook}
\let\HEADINGShook=\relax
% Commands to set those variables.
% For example, this is what @headings on does
% @evenheading @thistitle|@thispage|@thischapter
% @oddheading @thischapter|@thispage|@thistitle
% @evenfooting @thisfile||
% @oddfooting ||@thisfile
\def\evenheading{\parsearg\evenheadingxxx}
\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish}
\def\evenheadingyyy #1\|#2\|#3\|#4\finish{%
\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
\def\oddheading{\parsearg\oddheadingxxx}
\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish}
\def\oddheadingyyy #1\|#2\|#3\|#4\finish{%
\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
\def\evenfooting{\parsearg\evenfootingxxx}
\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish}
\def\evenfootingyyy #1\|#2\|#3\|#4\finish{%
\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
\def\oddfooting{\parsearg\oddfootingxxx}
\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish}
\def\oddfootingyyy #1\|#2\|#3\|#4\finish{%
\global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%
%
% Leave some space for the footline. Hopefully ok to assume
% @evenfooting will not be used by itself.
\global\advance\pageheight by -12pt
\global\advance\vsize by -12pt
}
\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}}
% @evenheadingmarks top \thischapter <- chapter at the top of a page
% @evenheadingmarks bottom \thischapter <- chapter at the bottom of a page
%
% The same set of arguments for:
%
% @oddheadingmarks
% @evenfootingmarks
% @oddfootingmarks
% @everyheadingmarks
% @everyfootingmarks
\def\evenheadingmarks{\headingmarks{even}{heading}}
\def\oddheadingmarks{\headingmarks{odd}{heading}}
\def\evenfootingmarks{\headingmarks{even}{footing}}
\def\oddfootingmarks{\headingmarks{odd}{footing}}
\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1}
\headingmarks{odd}{heading}{#1} }
\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1}
\headingmarks{odd}{footing}{#1} }
% #1 = even/odd, #2 = heading/footing, #3 = top/bottom.
\def\headingmarks#1#2#3 {%
\expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname
\global\expandafter\let\csname get#1#2marks\endcsname \temp
}
\everyheadingmarks bottom
\everyfootingmarks bottom
% @headings double turns headings on for double-sided printing.
% @headings single turns headings on for single-sided printing.
% @headings off turns them off.
% @headings on same as @headings double, retained for compatibility.
% @headings after turns on double-sided headings after this page.
% @headings doubleafter turns on double-sided headings after this page.
% @headings singleafter turns on single-sided headings after this page.
% By default, they are off at the start of a document,
% and turned `on' after @end titlepage.
\def\headings #1 {\csname HEADINGS#1\endcsname}
\def\headingsoff{% non-global headings elimination
\evenheadline={\hfil}\evenfootline={\hfil}%
\oddheadline={\hfil}\oddfootline={\hfil}%
}
\def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting
\HEADINGSoff % it's the default
% When we turn headings on, set the page number to 1.
% For double-sided printing, put current file name in lower left corner,
% chapter name on inside top of right hand pages, document
% title on inside top of left hand pages, and page numbers on outside top
% edge of all pages.
\def\HEADINGSdouble{%
\global\pageno=1
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\folio\hfil\thistitle}}
\global\oddheadline={\line{\thischapter\hfil\folio}}
\global\let\contentsalignmacro = \chapoddpage
}
\let\contentsalignmacro = \chappager
% For single-sided printing, chapter title goes across top left of page,
% page number on top right.
\def\HEADINGSsingle{%
\global\pageno=1
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\thischapter\hfil\folio}}
\global\oddheadline={\line{\thischapter\hfil\folio}}
\global\let\contentsalignmacro = \chappager
}
\def\HEADINGSon{\HEADINGSdouble}
\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
\let\HEADINGSdoubleafter=\HEADINGSafter
\def\HEADINGSdoublex{%
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\folio\hfil\thistitle}}
\global\oddheadline={\line{\thischapter\hfil\folio}}
\global\let\contentsalignmacro = \chapoddpage
}
\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
\def\HEADINGSsinglex{%
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\thischapter\hfil\folio}}
\global\oddheadline={\line{\thischapter\hfil\folio}}
\global\let\contentsalignmacro = \chappager
}
% Subroutines used in generating headings
% This produces Day Month Year style of output.
% Only define if not already defined, in case a txi-??.tex file has set
% up a different format (e.g., txi-cs.tex does this).
\ifx\today\thisisundefined
\def\today{%
\number\day\space
\ifcase\month
\or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr
\or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug
\or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec
\fi
\space\number\year}
\fi
% @settitle line... specifies the title of the document, for headings.
% It generates no output of its own.
\def\thistitle{\putwordNoTitle}
\def\settitle{\parsearg{\gdef\thistitle}}
\message{tables,}
% Tables -- @table, @ftable, @vtable, @item(x).
% default indentation of table text
\newdimen\tableindent \tableindent=.8in
% default indentation of @itemize and @enumerate text
\newdimen\itemindent \itemindent=.3in
% margin between end of table item and start of table text.
\newdimen\itemmargin \itemmargin=.1in
% used internally for \itemindent minus \itemmargin
\newdimen\itemmax
% Note @table, @ftable, and @vtable define @item, @itemx, etc., with
% these defs.
% They also define \itemindex
% to index the item name in whatever manner is desired (perhaps none).
\newif\ifitemxneedsnegativevskip
\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}
\def\internalBitem{\smallbreak \parsearg\itemzzz}
\def\internalBitemx{\itemxpar \parsearg\itemzzz}
\def\itemzzz #1{\begingroup %
\advance\hsize by -\rightskip
\advance\hsize by -\tableindent
\setbox0=\hbox{\itemindicate{#1}}%
\itemindex{#1}%
\nobreak % This prevents a break before @itemx.
%
% If the item text does not fit in the space we have, put it on a line
% by itself, and do not allow a page break either before or after that
% line. We do not start a paragraph here because then if the next
% command is, e.g., @kindex, the whatsit would get put into the
% horizontal list on a line by itself, resulting in extra blank space.
\ifdim \wd0>\itemmax
%
% Make this a paragraph so we get the \parskip glue and wrapping,
% but leave it ragged-right.
\begingroup
\advance\leftskip by-\tableindent
\advance\hsize by\tableindent
\advance\rightskip by0pt plus1fil\relax
\leavevmode\unhbox0\par
\endgroup
%
% We're going to be starting a paragraph, but we don't want the
% \parskip glue -- logically it's part of the @item we just started.
\nobreak \vskip-\parskip
%
% Stop a page break at the \parskip glue coming up. However, if
% what follows is an environment such as @example, there will be no
% \parskip glue; then the negative vskip we just inserted would
% cause the example and the item to crash together. So we use this
% bizarre value of 10001 as a signal to \aboveenvbreak to insert
% \parskip glue after all. Section titles are handled this way also.
%
\penalty 10001
\endgroup
\itemxneedsnegativevskipfalse
\else
% The item text fits into the space. Start a paragraph, so that the
% following text (if any) will end up on the same line.
\noindent
% Do this with kerns and \unhbox so that if there is a footnote in
% the item text, it can migrate to the main vertical list and
% eventually be printed.
\nobreak\kern-\tableindent
\dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0
\unhbox0
\nobreak\kern\dimen0
\endgroup
\itemxneedsnegativevskiptrue
\fi
}
\def\item{\errmessage{@item while not in a list environment}}
\def\itemx{\errmessage{@itemx while not in a list environment}}
% @table, @ftable, @vtable.
\envdef\table{%
\let\itemindex\gobble
\tablecheck{table}%
}
\envdef\ftable{%
\def\itemindex ##1{\doind {fn}{\code{##1}}}%
\tablecheck{ftable}%
}
\envdef\vtable{%
\def\itemindex ##1{\doind {vr}{\code{##1}}}%
\tablecheck{vtable}%
}
\def\tablecheck#1{%
\ifnum \the\catcode`\^^M=\active
\endgroup
\errmessage{This command won't work in this context; perhaps the problem is
that we are \inenvironment\thisenv}%
\def\next{\doignore{#1}}%
\else
\let\next\tablex
\fi
\next
}
\def\tablex#1{%
\def\itemindicate{#1}%
\parsearg\tabley
}
\def\tabley#1{%
{%
\makevalueexpandable
\edef\temp{\noexpand\tablez #1\space\space\space}%
\expandafter
}\temp \endtablez
}
\def\tablez #1 #2 #3 #4\endtablez{%
\aboveenvbreak
\ifnum 0#1>0 \advance \leftskip by #1\mil \fi
\ifnum 0#2>0 \tableindent=#2\mil \fi
\ifnum 0#3>0 \advance \rightskip by #3\mil \fi
\itemmax=\tableindent
\advance \itemmax by -\itemmargin
\advance \leftskip by \tableindent
\exdentamount=\tableindent
\parindent = 0pt
\parskip = \smallskipamount
\ifdim \parskip=0pt \parskip=2pt \fi
\let\item = \internalBitem
\let\itemx = \internalBitemx
}
\def\Etable{\endgraf\afterenvbreak}
\let\Eftable\Etable
\let\Evtable\Etable
\let\Eitemize\Etable
\let\Eenumerate\Etable
% This is the counter used by @enumerate, which is really @itemize
\newcount \itemno
\envdef\itemize{\parsearg\doitemize}
\def\doitemize#1{%
\aboveenvbreak
\itemmax=\itemindent
\advance\itemmax by -\itemmargin
\advance\leftskip by \itemindent
\exdentamount=\itemindent
\parindent=0pt
\parskip=\smallskipamount
\ifdim\parskip=0pt \parskip=2pt \fi
%
% Try typesetting the item mark that if the document erroneously says
% something like @itemize @samp (intending @table), there's an error
% right away at the @itemize. It's not the best error message in the
% world, but it's better than leaving it to the @item. This means if
% the user wants an empty mark, they have to say @w{} not just @w.
\def\itemcontents{#1}%
\setbox0 = \hbox{\itemcontents}%
%
% @itemize with no arg is equivalent to @itemize @bullet.
\ifx\itemcontents\empty\def\itemcontents{\bullet}\fi
%
\let\item=\itemizeitem
}
% Definition of @item while inside @itemize and @enumerate.
%
\def\itemizeitem{%
\advance\itemno by 1 % for enumerations
{\let\par=\endgraf \smallbreak}% reasonable place to break
{%
% If the document has an @itemize directly after a section title, a
% \nobreak will be last on the list, and \sectionheading will have
% done a \vskip-\parskip. In that case, we don't want to zero
% parskip, or the item text will crash with the heading. On the
% other hand, when there is normal text preceding the item (as there
% usually is), we do want to zero parskip, or there would be too much
% space. In that case, we won't have a \nobreak before. At least
% that's the theory.
\ifnum\lastpenalty<10000 \parskip=0in \fi
\noindent
\hbox to 0pt{\hss \itemcontents \kern\itemmargin}%
%
\vadjust{\penalty 1200}}% not good to break after first line of item.
\flushcr
}
% \splitoff TOKENS\endmark defines \first to be the first token in
% TOKENS, and \rest to be the remainder.
%
\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%
% Allow an optional argument of an uppercase letter, lowercase letter,
% or number, to specify the first label in the enumerated list. No
% argument is the same as `1'.
%
\envparseargdef\enumerate{\enumeratey #1 \endenumeratey}
\def\enumeratey #1 #2\endenumeratey{%
% If we were given no argument, pretend we were given `1'.
\def\thearg{#1}%
\ifx\thearg\empty \def\thearg{1}\fi
%
% Detect if the argument is a single token. If so, it might be a
% letter. Otherwise, the only valid thing it can be is a number.
% (We will always have one token, because of the test we just made.
% This is a good thing, since \splitoff doesn't work given nothing at
% all -- the first parameter is undelimited.)
\expandafter\splitoff\thearg\endmark
\ifx\rest\empty
% Only one token in the argument. It could still be anything.
% A ``lowercase letter'' is one whose \lccode is nonzero.
% An ``uppercase letter'' is one whose \lccode is both nonzero, and
% not equal to itself.
% Otherwise, we assume it's a number.
%
% We need the \relax at the end of the \ifnum lines to stop TeX from
% continuing to look for a .
%
\ifnum\lccode\expandafter`\thearg=0\relax
\numericenumerate % a number (we hope)
\else
% It's a letter.
\ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax
\lowercaseenumerate % lowercase letter
\else
\uppercaseenumerate % uppercase letter
\fi
\fi
\else
% Multiple tokens in the argument. We hope it's a number.
\numericenumerate
\fi
}
% An @enumerate whose labels are integers. The starting integer is
% given in \thearg.
%
\def\numericenumerate{%
\itemno = \thearg
\startenumeration{\the\itemno}%
}
% The starting (lowercase) letter is in \thearg.
\def\lowercaseenumerate{%
\itemno = \expandafter`\thearg
\startenumeration{%
% Be sure we're not beyond the end of the alphabet.
\ifnum\itemno=0
\errmessage{No more lowercase letters in @enumerate; get a bigger
alphabet}%
\fi
\char\lccode\itemno
}%
}
% The starting (uppercase) letter is in \thearg.
\def\uppercaseenumerate{%
\itemno = \expandafter`\thearg
\startenumeration{%
% Be sure we're not beyond the end of the alphabet.
\ifnum\itemno=0
\errmessage{No more uppercase letters in @enumerate; get a bigger
alphabet}
\fi
\char\uccode\itemno
}%
}
% Call \doitemize, adding a period to the first argument and supplying the
% common last two arguments. Also subtract one from the initial value in
% \itemno, since @item increments \itemno.
%
\def\startenumeration#1{%
\advance\itemno by -1
\doitemize{#1.}\flushcr
}
% @alphaenumerate and @capsenumerate are abbreviations for giving an arg
% to @enumerate.
%
\def\alphaenumerate{\enumerate{a}}
\def\capsenumerate{\enumerate{A}}
\def\Ealphaenumerate{\Eenumerate}
\def\Ecapsenumerate{\Eenumerate}
% @multitable macros
% Amy Hendrickson, 8/18/94, 3/6/96
%
% @multitable ... @end multitable will make as many columns as desired.
% Contents of each column will wrap at width given in preamble. Width
% can be specified either with sample text given in a template line,
% or in percent of \hsize, the current width of text on page.
% Table can continue over pages but will only break between lines.
% To make preamble:
%
% Either define widths of columns in terms of percent of \hsize:
% @multitable @columnfractions .25 .3 .45
% @item ...
%
% Numbers following @columnfractions are the percent of the total
% current hsize to be used for each column. You may use as many
% columns as desired.
% Or use a template:
% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
% @item ...
% using the widest term desired in each column.
% Each new table line starts with @item, each subsequent new column
% starts with @tab. Empty columns may be produced by supplying @tab's
% with nothing between them for as many times as empty columns are needed,
% ie, @tab@tab@tab will produce two empty columns.
% @item, @tab do not need to be on their own lines, but it will not hurt
% if they are.
% Sample multitable:
% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
% @item first col stuff @tab second col stuff @tab third col
% @item
% first col stuff
% @tab
% second col stuff
% @tab
% third col
% @item first col stuff @tab second col stuff
% @tab Many paragraphs of text may be used in any column.
%
% They will wrap at the width determined by the template.
% @item@tab@tab This will be in third column.
% @end multitable
% Default dimensions may be reset by user.
% @multitableparskip is vertical space between paragraphs in table.
% @multitableparindent is paragraph indent in table.
% @multitablecolmargin is horizontal space to be left between columns.
% @multitablelinespace is space to leave between table items, baseline
% to baseline.
% 0pt means it depends on current normal line spacing.
%
\newskip\multitableparskip
\newskip\multitableparindent
\newdimen\multitablecolspace
\newskip\multitablelinespace
\multitableparskip=0pt
\multitableparindent=6pt
\multitablecolspace=12pt
\multitablelinespace=0pt
% Macros used to set up halign preamble:
%
\let\endsetuptable\relax
\def\xendsetuptable{\endsetuptable}
\let\columnfractions\relax
\def\xcolumnfractions{\columnfractions}
\newif\ifsetpercent
% #1 is the @columnfraction, usually a decimal number like .5, but might
% be just 1. We just use it, whatever it is.
%
\def\pickupwholefraction#1 {%
\global\advance\colcount by 1
\expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}%
\setuptable
}
\newcount\colcount
\def\setuptable#1{%
\def\firstarg{#1}%
\ifx\firstarg\xendsetuptable
\let\go = \relax
\else
\ifx\firstarg\xcolumnfractions
\global\setpercenttrue
\else
\ifsetpercent
\let\go\pickupwholefraction
\else
\global\advance\colcount by 1
\setbox0=\hbox{#1\unskip\space}% Add a normal word space as a
% separator; typically that is always in the input, anyway.
\expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%
\fi
\fi
\ifx\go\pickupwholefraction
% Put the argument back for the \pickupwholefraction call, so
% we'll always have a period there to be parsed.
\def\go{\pickupwholefraction#1}%
\else
\let\go = \setuptable
\fi%
\fi
\go
}
% multitable-only commands.
%
% @headitem starts a heading row, which we typeset in bold.
% Assignments have to be global since we are inside the implicit group
% of an alignment entry. \everycr resets \everytab so we don't have to
% undo it ourselves.
\def\headitemfont{\b}% for people to use in the template row; not changeable
\def\headitem{%
\checkenv\multitable
\crcr
\global\everytab={\bf}% can't use \headitemfont since the parsing differs
\the\everytab % for the first item
}%
%
% A \tab used to include \hskip1sp. But then the space in a template
% line is not enough. That is bad. So let's go back to just `&' until
% we again encounter the problem the 1sp was intended to solve.
% --karl, nathan@acm.org, 20apr99.
\def\tab{\checkenv\multitable &\the\everytab}%
% @multitable ... @end multitable definitions:
%
\newtoks\everytab % insert after every tab.
%
\envdef\multitable{%
\vskip\parskip
\startsavinginserts
%
% @item within a multitable starts a normal row.
% We use \def instead of \let so that if one of the multitable entries
% contains an @itemize, we don't choke on the \item (seen as \crcr aka
% \endtemplate) expanding \doitemize.
\def\item{\crcr}%
%
\tolerance=9500
\hbadness=9500
\setmultitablespacing
\parskip=\multitableparskip
\parindent=\multitableparindent
\overfullrule=0pt
\global\colcount=0
%
\everycr = {%
\noalign{%
\global\everytab={}%
\global\colcount=0 % Reset the column counter.
% Check for saved footnotes, etc.
\checkinserts
% Keeps underfull box messages off when table breaks over pages.
%\filbreak
% Maybe so, but it also creates really weird page breaks when the
% table breaks over pages. Wouldn't \vfil be better? Wait until the
% problem manifests itself, so it can be fixed for real --karl.
}%
}%
%
\parsearg\domultitable
}
\def\domultitable#1{%
% To parse everything between @multitable and @item:
\setuptable#1 \endsetuptable
%
% This preamble sets up a generic column definition, which will
% be used as many times as user calls for columns.
% \vtop will set a single line and will also let text wrap and
% continue for many paragraphs if desired.
\halign\bgroup &%
\global\advance\colcount by 1
\multistrut
\vtop{%
% Use the current \colcount to find the correct column width:
\hsize=\expandafter\csname col\the\colcount\endcsname
%
% In order to keep entries from bumping into each other
% we will add a \leftskip of \multitablecolspace to all columns after
% the first one.
%
% If a template has been used, we will add \multitablecolspace
% to the width of each template entry.
%
% If the user has set preamble in terms of percent of \hsize we will
% use that dimension as the width of the column, and the \leftskip
% will keep entries from bumping into each other. Table will start at
% left margin and final column will justify at right margin.
%
% Make sure we don't inherit \rightskip from the outer environment.
\rightskip=0pt
\ifnum\colcount=1
% The first column will be indented with the surrounding text.
\advance\hsize by\leftskip
\else
\ifsetpercent \else
% If user has not set preamble in terms of percent of \hsize
% we will advance \hsize by \multitablecolspace.
\advance\hsize by \multitablecolspace
\fi
% In either case we will make \leftskip=\multitablecolspace:
\leftskip=\multitablecolspace
\fi
% Ignoring space at the beginning and end avoids an occasional spurious
% blank line, when TeX decides to break the line at the space before the
% box from the multistrut, so the strut ends up on a line by itself.
% For example:
% @multitable @columnfractions .11 .89
% @item @code{#}
% @tab Legal holiday which is valid in major parts of the whole country.
% Is automatically provided with highlighting sequences respectively
% marking characters.
\noindent\ignorespaces##\unskip\multistrut
}\cr
}
\def\Emultitable{%
\crcr
\egroup % end the \halign
\global\setpercentfalse
}
\def\setmultitablespacing{%
\def\multistrut{\strut}% just use the standard line spacing
%
% Compute \multitablelinespace (if not defined by user) for use in
% \multitableparskip calculation. We used define \multistrut based on
% this, but (ironically) that caused the spacing to be off.
% See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100.
\ifdim\multitablelinespace=0pt
\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip
\global\advance\multitablelinespace by-\ht0
\fi
% Test to see if parskip is larger than space between lines of
% table. If not, do nothing.
% If so, set to same dimension as multitablelinespace.
\ifdim\multitableparskip>\multitablelinespace
\global\multitableparskip=\multitablelinespace
\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller
% than skip between lines in the table.
\fi%
\ifdim\multitableparskip=0pt
\global\multitableparskip=\multitablelinespace
\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller
% than skip between lines in the table.
\fi}
\message{conditionals,}
% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext,
% @ifnotxml always succeed. They currently do nothing; we don't
% attempt to check whether the conditionals are properly nested. But we
% have to remember that they are conditionals, so that @end doesn't
% attempt to close an environment group.
%
\def\makecond#1{%
\expandafter\let\csname #1\endcsname = \relax
\expandafter\let\csname iscond.#1\endcsname = 1
}
\makecond{iftex}
\makecond{ifnotdocbook}
\makecond{ifnothtml}
\makecond{ifnotinfo}
\makecond{ifnotplaintext}
\makecond{ifnotxml}
% Ignore @ignore, @ifhtml, @ifinfo, and the like.
%
\def\direntry{\doignore{direntry}}
\def\documentdescription{\doignore{documentdescription}}
\def\docbook{\doignore{docbook}}
\def\html{\doignore{html}}
\def\ifdocbook{\doignore{ifdocbook}}
\def\ifhtml{\doignore{ifhtml}}
\def\ifinfo{\doignore{ifinfo}}
\def\ifnottex{\doignore{ifnottex}}
\def\ifplaintext{\doignore{ifplaintext}}
\def\ifxml{\doignore{ifxml}}
\def\ignore{\doignore{ignore}}
\def\menu{\doignore{menu}}
\def\xml{\doignore{xml}}
% Ignore text until a line `@end #1', keeping track of nested conditionals.
%
% A count to remember the depth of nesting.
\newcount\doignorecount
\def\doignore#1{\begingroup
% Scan in ``verbatim'' mode:
\obeylines
\catcode`\@ = \other
\catcode`\{ = \other
\catcode`\} = \other
%
% Make sure that spaces turn into tokens that match what \doignoretext wants.
\spaceisspace
%
% Count number of #1's that we've seen.
\doignorecount = 0
%
% Swallow text until we reach the matching `@end #1'.
\dodoignore{#1}%
}
{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source.
\obeylines %
%
\gdef\dodoignore#1{%
% #1 contains the command name as a string, e.g., `ifinfo'.
%
% Define a command to find the next `@end #1'.
\long\def\doignoretext##1^^M@end #1{%
\doignoretextyyy##1^^M@#1\_STOP_}%
%
% And this command to find another #1 command, at the beginning of a
% line. (Otherwise, we would consider a line `@c @ifset', for
% example, to count as an @ifset for nesting.)
\long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}%
%
% And now expand that command.
\doignoretext ^^M%
}%
}
\def\doignoreyyy#1{%
\def\temp{#1}%
\ifx\temp\empty % Nothing found.
\let\next\doignoretextzzz
\else % Found a nested condition, ...
\advance\doignorecount by 1
\let\next\doignoretextyyy % ..., look for another.
% If we're here, #1 ends with ^^M\ifinfo (for example).
\fi
\next #1% the token \_STOP_ is present just after this macro.
}
% We have to swallow the remaining "\_STOP_".
%
\def\doignoretextzzz#1{%
\ifnum\doignorecount = 0 % We have just found the outermost @end.
\let\next\enddoignore
\else % Still inside a nested condition.
\advance\doignorecount by -1
\let\next\doignoretext % Look for the next @end.
\fi
\next
}
% Finish off ignored text.
{ \obeylines%
% Ignore anything after the last `@end #1'; this matters in verbatim
% environments, where otherwise the newline after an ignored conditional
% would result in a blank line in the output.
\gdef\enddoignore#1^^M{\endgroup\ignorespaces}%
}
% @set VAR sets the variable VAR to an empty value.
% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.
%
% Since we want to separate VAR from REST-OF-LINE (which might be
% empty), we can't just use \parsearg; we have to insert a space of our
% own to delimit the rest of the line, and then take it out again if we
% didn't need it.
% We rely on the fact that \parsearg sets \catcode`\ =10.
%
\parseargdef\set{\setyyy#1 \endsetyyy}
\def\setyyy#1 #2\endsetyyy{%
{%
\makevalueexpandable
\def\temp{#2}%
\edef\next{\gdef\makecsname{SET#1}}%
\ifx\temp\empty
\next{}%
\else
\setzzz#2\endsetzzz
\fi
}%
}
% Remove the trailing space \setxxx inserted.
\def\setzzz#1 \endsetzzz{\next{#1}}
% @clear VAR clears (i.e., unsets) the variable VAR.
%
\parseargdef\clear{%
{%
\makevalueexpandable
\global\expandafter\let\csname SET#1\endcsname=\relax
}%
}
% @value{foo} gets the text saved in variable foo.
\def\value{\begingroup\makevalueexpandable\valuexxx}
\def\valuexxx#1{\expandablevalue{#1}\endgroup}
{
\catcode`\-=\active \catcode`\_=\active
%
\gdef\makevalueexpandable{%
\let\value = \expandablevalue
% We don't want these characters active, ...
\catcode`\-=\other \catcode`\_=\other
% ..., but we might end up with active ones in the argument if
% we're called from @code, as @code{@value{foo-bar_}}, though.
% So \let them to their normal equivalents.
\let-\normaldash \let_\normalunderscore
}
}
% We have this subroutine so that we can handle at least some @value's
% properly in indexes (we call \makevalueexpandable in \indexdummies).
% The command has to be fully expandable (if the variable is set), since
% the result winds up in the index file. This means that if the
% variable's value contains other Texinfo commands, it's almost certain
% it will fail (although perhaps we could fix that with sufficient work
% to do a one-level expansion on the result, instead of complete).
%
% Unfortunately, this has the consequence that when _ is in the *value*
% of an @set, it does not print properly in the roman fonts (get the cmr
% dot accent at position 126 instead). No fix comes to mind, and it's
% been this way since 2003 or earlier, so just ignore it.
%
\def\expandablevalue#1{%
\expandafter\ifx\csname SET#1\endcsname\relax
{[No value for ``#1'']}%
\message{Variable `#1', used in @value, is not set.}%
\else
\csname SET#1\endcsname
\fi
}
% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined
% with @set.
%
% To get the special treatment we need for `@end ifset,' we call
% \makecond and then redefine.
%
\makecond{ifset}
\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}}
\def\doifset#1#2{%
{%
\makevalueexpandable
\let\next=\empty
\expandafter\ifx\csname SET#2\endcsname\relax
#1% If not set, redefine \next.
\fi
\expandafter
}\next
}
\def\ifsetfail{\doignore{ifset}}
% @ifclear VAR ... @end executes the `...' iff VAR has never been
% defined with @set, or has been undefined with @clear.
%
% The `\else' inside the `\doifset' parameter is a trick to reuse the
% above code: if the variable is not set, do nothing, if it is set,
% then redefine \next to \ifclearfail.
%
\makecond{ifclear}
\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}}
\def\ifclearfail{\doignore{ifclear}}
% @ifcommandisdefined CMD ... @end executes the `...' if CMD (written
% without the @) is in fact defined. We can only feasibly check at the
% TeX level, so something like `mathcode' is going to considered
% defined even though it is not a Texinfo command.
%
\makecond{ifcommanddefined}
\def\ifcommanddefined{\parsearg{\doifcmddefined{\let\next=\ifcmddefinedfail}}}
%
\def\doifcmddefined#1#2{{%
\makevalueexpandable
\let\next=\empty
\expandafter\ifx\csname #2\endcsname\relax
#1% If not defined, \let\next as above.
\fi
\expandafter
}\next
}
\def\ifcmddefinedfail{\doignore{ifcommanddefined}}
% @ifcommandnotdefined CMD ... handled similar to @ifclear above.
\makecond{ifcommandnotdefined}
\def\ifcommandnotdefined{%
\parsearg{\doifcmddefined{\else \let\next=\ifcmdnotdefinedfail}}}
\def\ifcmdnotdefinedfail{\doignore{ifcommandnotdefined}}
% Set the `txicommandconditionals' variable, so documents have a way to
% test if the @ifcommand...defined conditionals are available.
\set txicommandconditionals
% @dircategory CATEGORY -- specify a category of the dir file
% which this file should belong to. Ignore this in TeX.
\let\dircategory=\comment
% @defininfoenclose.
\let\definfoenclose=\comment
\message{indexing,}
% Index generation facilities
% Define \newwrite to be identical to plain tex's \newwrite
% except not \outer, so it can be used within macros and \if's.
\edef\newwrite{\makecsname{ptexnewwrite}}
% \newindex {foo} defines an index named foo.
% It automatically defines \fooindex such that
% \fooindex ...rest of line... puts an entry in the index foo.
% It also defines \fooindfile to be the number of the output channel for
% the file that accumulates this index. The file's extension is foo.
% The name of an index should be no more than 2 characters long
% for the sake of vms.
%
\def\newindex#1{%
\iflinks
\expandafter\newwrite \csname#1indfile\endcsname
\openout \csname#1indfile\endcsname \jobname.#1 % Open the file
\fi
\expandafter\xdef\csname#1index\endcsname{% % Define @#1index
\noexpand\doindex{#1}}
}
% @defindex foo == \newindex{foo}
%
\def\defindex{\parsearg\newindex}
% Define @defcodeindex, like @defindex except put all entries in @code.
%
\def\defcodeindex{\parsearg\newcodeindex}
%
\def\newcodeindex#1{%
\iflinks
\expandafter\newwrite \csname#1indfile\endcsname
\openout \csname#1indfile\endcsname \jobname.#1
\fi
\expandafter\xdef\csname#1index\endcsname{%
\noexpand\docodeindex{#1}}%
}
% @synindex foo bar makes index foo feed into index bar.
% Do this instead of @defindex foo if you don't want it as a separate index.
%
% @syncodeindex foo bar similar, but put all entries made for index foo
% inside @code.
%
\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}
% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
% #3 the target index (bar).
\def\dosynindex#1#2#3{%
% Only do \closeout if we haven't already done it, else we'll end up
% closing the target index.
\expandafter \ifx\csname donesynindex#2\endcsname \relax
% The \closeout helps reduce unnecessary open files; the limit on the
% Acorn RISC OS is a mere 16 files.
\expandafter\closeout\csname#2indfile\endcsname
\expandafter\let\csname donesynindex#2\endcsname = 1
\fi
% redefine \fooindfile:
\expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname
\expandafter\let\csname#2indfile\endcsname=\temp
% redefine \fooindex:
\expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}%
}
% Define \doindex, the driver for all \fooindex macros.
% Argument #1 is generated by the calling \fooindex macro,
% and it is "foo", the name of the index.
% \doindex just uses \parsearg; it calls \doind for the actual work.
% This is because \doind is more useful to call from other macros.
% There is also \dosubind {index}{topic}{subtopic}
% which makes an entry in a two-level index such as the operation index.
\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer}
\def\singleindexer #1{\doind{\indexname}{#1}}
% like the previous two, but they put @code around the argument.
\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}
\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}
% Take care of Texinfo commands that can appear in an index entry.
% Since there are some commands we want to expand, and others we don't,
% we have to laboriously prevent expansion for those that we don't.
%
\def\indexdummies{%
\escapechar = `\\ % use backslash in output files.
\def\@{@}% change to @@ when we switch to @ as escape char in index files.
\def\ {\realbackslash\space }%
%
% Need these unexpandable (because we define \tt as a dummy)
% definitions when @{ or @} appear in index entry text. Also, more
% complicated, when \tex is in effect and \{ is a \delimiter again.
% We can't use \lbracecmd and \rbracecmd because texindex assumes
% braces and backslashes are used only as delimiters. Perhaps we
% should define @lbrace and @rbrace commands a la @comma.
\def\{{{\tt\char123}}%
\def\}{{\tt\char125}}%
%
% I don't entirely understand this, but when an index entry is
% generated from a macro call, the \endinput which \scanmacro inserts
% causes processing to be prematurely terminated. This is,
% apparently, because \indexsorttmp is fully expanded, and \endinput
% is an expandable command. The redefinition below makes \endinput
% disappear altogether for that purpose -- although logging shows that
% processing continues to some further point. On the other hand, it
% seems \endinput does not hurt in the printed index arg, since that
% is still getting written without apparent harm.
%
% Sample source (mac-idx3.tex, reported by Graham Percival to
% help-texinfo, 22may06):
% @macro funindex {WORD}
% @findex xyz
% @end macro
% ...
% @funindex commtest
%
% The above is not enough to reproduce the bug, but it gives the flavor.
%
% Sample whatsit resulting:
% .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}}
%
% So:
\let\endinput = \empty
%
% Do the redefinitions.
\commondummies
}
% For the aux and toc files, @ is the escape character. So we want to
% redefine everything using @ as the escape character (instead of
% \realbackslash, still used for index files). When everything uses @,
% this will be simpler.
%
\def\atdummies{%
\def\@{@@}%
\def\ {@ }%
\let\{ = \lbraceatcmd
\let\} = \rbraceatcmd
%
% Do the redefinitions.
\commondummies
\otherbackslash
}
% Called from \indexdummies and \atdummies.
%
\def\commondummies{%
%
% \definedummyword defines \#1 as \string\#1\space, thus effectively
% preventing its expansion. This is used only for control words,
% not control letters, because the \space would be incorrect for
% control characters, but is needed to separate the control word
% from whatever follows.
%
% For control letters, we have \definedummyletter, which omits the
% space.
%
% These can be used both for control words that take an argument and
% those that do not. If it is followed by {arg} in the input, then
% that will dutifully get written to the index (or wherever).
%
\def\definedummyword ##1{\def##1{\string##1\space}}%
\def\definedummyletter##1{\def##1{\string##1}}%
\let\definedummyaccent\definedummyletter
%
\commondummiesnofonts
%
\definedummyletter\_%
\definedummyletter\-%
%
% Non-English letters.
\definedummyword\AA
\definedummyword\AE
\definedummyword\DH
\definedummyword\L
\definedummyword\O
\definedummyword\OE
\definedummyword\TH
\definedummyword\aa
\definedummyword\ae
\definedummyword\dh
\definedummyword\exclamdown
\definedummyword\l
\definedummyword\o
\definedummyword\oe
\definedummyword\ordf
\definedummyword\ordm
\definedummyword\questiondown
\definedummyword\ss
\definedummyword\th
%
% Although these internal commands shouldn't show up, sometimes they do.
\definedummyword\bf
\definedummyword\gtr
\definedummyword\hat
\definedummyword\less
\definedummyword\sf
\definedummyword\sl
\definedummyword\tclose
\definedummyword\tt
%
\definedummyword\LaTeX
\definedummyword\TeX
%
% Assorted special characters.
\definedummyword\arrow
\definedummyword\bullet
\definedummyword\comma
\definedummyword\copyright
\definedummyword\registeredsymbol
\definedummyword\dots
\definedummyword\enddots
\definedummyword\entrybreak
\definedummyword\equiv
\definedummyword\error
\definedummyword\euro
\definedummyword\expansion
\definedummyword\geq
\definedummyword\guillemetleft
\definedummyword\guillemetright
\definedummyword\guilsinglleft
\definedummyword\guilsinglright
\definedummyword\lbracechar
\definedummyword\leq
\definedummyword\minus
\definedummyword\ogonek
\definedummyword\pounds
\definedummyword\point
\definedummyword\print
\definedummyword\quotedblbase
\definedummyword\quotedblleft
\definedummyword\quotedblright
\definedummyword\quoteleft
\definedummyword\quoteright
\definedummyword\quotesinglbase
\definedummyword\rbracechar
\definedummyword\result
\definedummyword\textdegree
%
% We want to disable all macros so that they are not expanded by \write.
\macrolist
%
\normalturnoffactive
%
% Handle some cases of @value -- where it does not contain any
% (non-fully-expandable) commands.
\makevalueexpandable
}
% \commondummiesnofonts: common to \commondummies and \indexnofonts.
%
\def\commondummiesnofonts{%
% Control letters and accents.
\definedummyletter\!%
\definedummyaccent\"%
\definedummyaccent\'%
\definedummyletter\*%
\definedummyaccent\,%
\definedummyletter\.%
\definedummyletter\/%
\definedummyletter\:%
\definedummyaccent\=%
\definedummyletter\?%
\definedummyaccent\^%
\definedummyaccent\`%
\definedummyaccent\~%
\definedummyword\u
\definedummyword\v
\definedummyword\H
\definedummyword\dotaccent
\definedummyword\ogonek
\definedummyword\ringaccent
\definedummyword\tieaccent
\definedummyword\ubaraccent
\definedummyword\udotaccent
\definedummyword\dotless
%
% Texinfo font commands.
\definedummyword\b
\definedummyword\i
\definedummyword\r
\definedummyword\sansserif
\definedummyword\sc
\definedummyword\slanted
\definedummyword\t
%
% Commands that take arguments.
\definedummyword\abbr
\definedummyword\acronym
\definedummyword\anchor
\definedummyword\cite
\definedummyword\code
\definedummyword\command
\definedummyword\dfn
\definedummyword\dmn
\definedummyword\email
\definedummyword\emph
\definedummyword\env
\definedummyword\file
\definedummyword\image
\definedummyword\indicateurl
\definedummyword\inforef
\definedummyword\kbd
\definedummyword\key
\definedummyword\math
\definedummyword\option
\definedummyword\pxref
\definedummyword\ref
\definedummyword\samp
\definedummyword\strong
\definedummyword\tie
\definedummyword\uref
\definedummyword\url
\definedummyword\var
\definedummyword\verb
\definedummyword\w
\definedummyword\xref
}
% \indexnofonts is used when outputting the strings to sort the index
% by, and when constructing control sequence names. It eliminates all
% control sequences and just writes whatever the best ASCII sort string
% would be for a given command (usually its argument).
%
\def\indexnofonts{%
% Accent commands should become @asis.
\def\definedummyaccent##1{\let##1\asis}%
% We can just ignore other control letters.
\def\definedummyletter##1{\let##1\empty}%
% All control words become @asis by default; overrides below.
\let\definedummyword\definedummyaccent
%
\commondummiesnofonts
%
% Don't no-op \tt, since it isn't a user-level command
% and is used in the definitions of the active chars like <, >, |, etc.
% Likewise with the other plain tex font commands.
%\let\tt=\asis
%
\def\ { }%
\def\@{@}%
\def\_{\normalunderscore}%
\def\-{}% @- shouldn't affect sorting
%
% Unfortunately, texindex is not prepared to handle braces in the
% content at all. So for index sorting, we map @{ and @} to strings
% starting with |, since that ASCII character is between ASCII { and }.
\def\{{|a}%
\def\lbracechar{|a}%
%
\def\}{|b}%
\def\rbracechar{|b}%
%
% Non-English letters.
\def\AA{AA}%
\def\AE{AE}%
\def\DH{DZZ}%
\def\L{L}%
\def\OE{OE}%
\def\O{O}%
\def\TH{ZZZ}%
\def\aa{aa}%
\def\ae{ae}%
\def\dh{dzz}%
\def\exclamdown{!}%
\def\l{l}%
\def\oe{oe}%
\def\ordf{a}%
\def\ordm{o}%
\def\o{o}%
\def\questiondown{?}%
\def\ss{ss}%
\def\th{zzz}%
%
\def\LaTeX{LaTeX}%
\def\TeX{TeX}%
%
% Assorted special characters.
% (The following {} will end up in the sort string, but that's ok.)
\def\arrow{->}%
\def\bullet{bullet}%
\def\comma{,}%
\def\copyright{copyright}%
\def\dots{...}%
\def\enddots{...}%
\def\equiv{==}%
\def\error{error}%
\def\euro{euro}%
\def\expansion{==>}%
\def\geq{>=}%
\def\guillemetleft{<<}%
\def\guillemetright{>>}%
\def\guilsinglleft{<}%
\def\guilsinglright{>}%
\def\leq{<=}%
\def\minus{-}%
\def\point{.}%
\def\pounds{pounds}%
\def\print{-|}%
\def\quotedblbase{"}%
\def\quotedblleft{"}%
\def\quotedblright{"}%
\def\quoteleft{`}%
\def\quoteright{'}%
\def\quotesinglbase{,}%
\def\registeredsymbol{R}%
\def\result{=>}%
\def\textdegree{o}%
%
\expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax
\else \indexlquoteignore \fi
%
% We need to get rid of all macros, leaving only the arguments (if present).
% Of course this is not nearly correct, but it is the best we can do for now.
% makeinfo does not expand macros in the argument to @deffn, which ends up
% writing an index entry, and texindex isn't prepared for an index sort entry
% that starts with \.
%
% Since macro invocations are followed by braces, we can just redefine them
% to take a single TeX argument. The case of a macro invocation that
% goes to end-of-line is not handled.
%
\macrolist
}
% Undocumented (for FSFS 2nd ed.): @set txiindexlquoteignore makes us
% ignore left quotes in the sort term.
{\catcode`\`=\active
\gdef\indexlquoteignore{\let`=\empty}}
\let\indexbackslash=0 %overridden during \printindex.
\let\SETmarginindex=\relax % put index entries in margin (undocumented)?
% Most index entries go through here, but \dosubind is the general case.
% #1 is the index name, #2 is the entry text.
\def\doind#1#2{\dosubind{#1}{#2}{}}
% Workhorse for all \fooindexes.
% #1 is name of index, #2 is stuff to put there, #3 is subentry --
% empty if called from \doind, as we usually are (the main exception
% is with most defuns, which call us directly).
%
\def\dosubind#1#2#3{%
\iflinks
{%
% Store the main index entry text (including the third arg).
\toks0 = {#2}%
% If third arg is present, precede it with a space.
\def\thirdarg{#3}%
\ifx\thirdarg\empty \else
\toks0 = \expandafter{\the\toks0 \space #3}%
\fi
%
\edef\writeto{\csname#1indfile\endcsname}%
%
\safewhatsit\dosubindwrite
}%
\fi
}
% Write the entry in \toks0 to the index file:
%
\def\dosubindwrite{%
% Put the index entry in the margin if desired.
\ifx\SETmarginindex\relax\else
\insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}%
\fi
%
% Remember, we are within a group.
\indexdummies % Must do this here, since \bf, etc expand at this stage
\def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now
% so it will be output as is; and it will print as backslash.
%
% Process the index entry with all font commands turned off, to
% get the string to sort by.
{\indexnofonts
\edef\temp{\the\toks0}% need full expansion
\xdef\indexsorttmp{\temp}%
}%
%
% Set up the complete index entry, with both the sort key and
% the original text, including any font commands. We write
% three arguments to \entry to the .?? file (four in the
% subentry case), texindex reduces to two when writing the .??s
% sorted result.
\edef\temp{%
\write\writeto{%
\string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}%
}%
\temp
}
% Take care of unwanted page breaks/skips around a whatsit:
%
% If a skip is the last thing on the list now, preserve it
% by backing up by \lastskip, doing the \write, then inserting
% the skip again. Otherwise, the whatsit generated by the
% \write or \pdfdest will make \lastskip zero. The result is that
% sequences like this:
% @end defun
% @tindex whatever
% @defun ...
% will have extra space inserted, because the \medbreak in the
% start of the @defun won't see the skip inserted by the @end of
% the previous defun.
%
% But don't do any of this if we're not in vertical mode. We
% don't want to do a \vskip and prematurely end a paragraph.
%
% Avoid page breaks due to these extra skips, too.
%
% But wait, there is a catch there:
% We'll have to check whether \lastskip is zero skip. \ifdim is not
% sufficient for this purpose, as it ignores stretch and shrink parts
% of the skip. The only way seems to be to check the textual
% representation of the skip.
%
% The following is almost like \def\zeroskipmacro{0.0pt} except that
% the ``p'' and ``t'' characters have catcode \other, not 11 (letter).
%
\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname}
%
\newskip\whatsitskip
\newcount\whatsitpenalty
%
% ..., ready, GO:
%
\def\safewhatsit#1{\ifhmode
#1%
\else
% \lastskip and \lastpenalty cannot both be nonzero simultaneously.
\whatsitskip = \lastskip
\edef\lastskipmacro{\the\lastskip}%
\whatsitpenalty = \lastpenalty
%
% If \lastskip is nonzero, that means the last item was a
% skip. And since a skip is discardable, that means this
% -\whatsitskip glue we're inserting is preceded by a
% non-discardable item, therefore it is not a potential
% breakpoint, therefore no \nobreak needed.
\ifx\lastskipmacro\zeroskipmacro
\else
\vskip-\whatsitskip
\fi
%
#1%
%
\ifx\lastskipmacro\zeroskipmacro
% If \lastskip was zero, perhaps the last item was a penalty, and
% perhaps it was >=10000, e.g., a \nobreak. In that case, we want
% to re-insert the same penalty (values >10000 are used for various
% signals); since we just inserted a non-discardable item, any
% following glue (such as a \parskip) would be a breakpoint. For example:
% @deffn deffn-whatever
% @vindex index-whatever
% Description.
% would allow a break between the index-whatever whatsit
% and the "Description." paragraph.
\ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi
\else
% On the other hand, if we had a nonzero \lastskip,
% this make-up glue would be preceded by a non-discardable item
% (the whatsit from the \write), so we must insert a \nobreak.
\nobreak\vskip\whatsitskip
\fi
\fi}
% The index entry written in the file actually looks like
% \entry {sortstring}{page}{topic}
% or
% \entry {sortstring}{page}{topic}{subtopic}
% The texindex program reads in these files and writes files
% containing these kinds of lines:
% \initial {c}
% before the first topic whose initial is c
% \entry {topic}{pagelist}
% for a topic that is used without subtopics
% \primary {topic}
% for the beginning of a topic that is used with subtopics
% \secondary {subtopic}{pagelist}
% for each subtopic.
% Define the user-accessible indexing commands
% @findex, @vindex, @kindex, @cindex.
\def\findex {\fnindex}
\def\kindex {\kyindex}
\def\cindex {\cpindex}
\def\vindex {\vrindex}
\def\tindex {\tpindex}
\def\pindex {\pgindex}
\def\cindexsub {\begingroup\obeylines\cindexsub}
{\obeylines %
\gdef\cindexsub "#1" #2^^M{\endgroup %
\dosubind{cp}{#2}{#1}}}
% Define the macros used in formatting output of the sorted index material.
% @printindex causes a particular index (the ??s file) to get printed.
% It does not print any chapter heading (usually an @unnumbered).
%
\parseargdef\printindex{\begingroup
\dobreak \chapheadingskip{10000}%
%
\smallfonts \rm
\tolerance = 9500
\plainfrenchspacing
\everypar = {}% don't want the \kern\-parindent from indentation suppression.
%
% See if the index file exists and is nonempty.
% Change catcode of @ here so that if the index file contains
% \initial {@}
% as its first line, TeX doesn't complain about mismatched braces
% (because it thinks @} is a control sequence).
\catcode`\@ = 11
\openin 1 \jobname.#1s
\ifeof 1
% \enddoublecolumns gets confused if there is no text in the index,
% and it loses the chapter title and the aux file entries for the
% index. The easiest way to prevent this problem is to make sure
% there is some text.
\putwordIndexNonexistent
\else
%
% If the index file exists but is empty, then \openin leaves \ifeof
% false. We have to make TeX try to read something from the file, so
% it can discover if there is anything in it.
\read 1 to \temp
\ifeof 1
\putwordIndexIsEmpty
\else
% Index files are almost Texinfo source, but we use \ as the escape
% character. It would be better to use @, but that's too big a change
% to make right now.
\def\indexbackslash{\backslashcurfont}%
\catcode`\\ = 0
\escapechar = `\\
\begindoublecolumns
\input \jobname.#1s
\enddoublecolumns
\fi
\fi
\closein 1
\endgroup}
% These macros are used by the sorted index file itself.
% Change them to control the appearance of the index.
\def\initial#1{{%
% Some minor font changes for the special characters.
\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt
%
% Remove any glue we may have, we'll be inserting our own.
\removelastskip
%
% We like breaks before the index initials, so insert a bonus.
\nobreak
\vskip 0pt plus 3\baselineskip
\penalty 0
\vskip 0pt plus -3\baselineskip
%
% Typeset the initial. Making this add up to a whole number of
% baselineskips increases the chance of the dots lining up from column
% to column. It still won't often be perfect, because of the stretch
% we need before each entry, but it's better.
%
% No shrink because it confuses \balancecolumns.
\vskip 1.67\baselineskip plus .5\baselineskip
\leftline{\secbf #1}%
% Do our best not to break after the initial.
\nobreak
\vskip .33\baselineskip plus .1\baselineskip
}}
% \entry typesets a paragraph consisting of the text (#1), dot leaders, and
% then page number (#2) flushed to the right margin. It is used for index
% and table of contents entries. The paragraph is indented by \leftskip.
%
% A straightforward implementation would start like this:
% \def\entry#1#2{...
% But this freezes the catcodes in the argument, and can cause problems to
% @code, which sets - active. This problem was fixed by a kludge---
% ``-'' was active throughout whole index, but this isn't really right.
% The right solution is to prevent \entry from swallowing the whole text.
% --kasal, 21nov03
\def\entry{%
\begingroup
%
% Start a new paragraph if necessary, so our assignments below can't
% affect previous text.
\par
%
% Do not fill out the last line with white space.
\parfillskip = 0in
%
% No extra space above this paragraph.
\parskip = 0in
%
% Do not prefer a separate line ending with a hyphen to fewer lines.
\finalhyphendemerits = 0
%
% \hangindent is only relevant when the entry text and page number
% don't both fit on one line. In that case, bob suggests starting the
% dots pretty far over on the line. Unfortunately, a large
% indentation looks wrong when the entry text itself is broken across
% lines. So we use a small indentation and put up with long leaders.
%
% \hangafter is reset to 1 (which is the value we want) at the start
% of each paragraph, so we need not do anything with that.
\hangindent = 2em
%
% When the entry text needs to be broken, just fill out the first line
% with blank space.
\rightskip = 0pt plus1fil
%
% A bit of stretch before each entry for the benefit of balancing
% columns.
\vskip 0pt plus1pt
%
% When reading the text of entry, convert explicit line breaks
% from @* into spaces. The user might give these in long section
% titles, for instance.
\def\*{\unskip\space\ignorespaces}%
\def\entrybreak{\hfil\break}%
%
% Swallow the left brace of the text (first parameter):
\afterassignment\doentry
\let\temp =
}
\def\entrybreak{\unskip\space\ignorespaces}%
\def\doentry{%
\bgroup % Instead of the swallowed brace.
\noindent
\aftergroup\finishentry
% And now comes the text of the entry.
}
\def\finishentry#1{%
% #1 is the page number.
%
% The following is kludged to not output a line of dots in the index if
% there are no page numbers. The next person who breaks this will be
% cursed by a Unix daemon.
\setbox\boxA = \hbox{#1}%
\ifdim\wd\boxA = 0pt
\ %
\else
%
% If we must, put the page number on a line of its own, and fill out
% this line with blank space. (The \hfil is overwhelmed with the
% fill leaders glue in \indexdotfill if the page number does fit.)
\hfil\penalty50
\null\nobreak\indexdotfill % Have leaders before the page number.
%
% The `\ ' here is removed by the implicit \unskip that TeX does as
% part of (the primitive) \par. Without it, a spurious underfull
% \hbox ensues.
\ifpdf
\pdfgettoks#1.%
\ \the\toksA
\else
\ #1%
\fi
\fi
\par
\endgroup
}
% Like plain.tex's \dotfill, except uses up at least 1 em.
\def\indexdotfill{\cleaders
\hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill}
\def\primary #1{\line{#1\hfil}}
\newskip\secondaryindent \secondaryindent=0.5cm
\def\secondary#1#2{{%
\parfillskip=0in
\parskip=0in
\hangindent=1in
\hangafter=1
\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill
\ifpdf
\pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
\else
#2
\fi
\par
}}
% Define two-column mode, which we use to typeset indexes.
% Adapted from the TeXbook, page 416, which is to say,
% the manmac.tex format used to print the TeXbook itself.
\catcode`\@=11
\newbox\partialpage
\newdimen\doublecolumnhsize
\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
% Grab any single-column material above us.
\output = {%
%
% Here is a possibility not foreseen in manmac: if we accumulate a
% whole lot of material, we might end up calling this \output
% routine twice in a row (see the doublecol-lose test, which is
% essentially a couple of indexes with @setchapternewpage off). In
% that case we just ship out what is in \partialpage with the normal
% output routine. Generally, \partialpage will be empty when this
% runs and this will be a no-op. See the indexspread.tex test case.
\ifvoid\partialpage \else
\onepageout{\pagecontents\partialpage}%
\fi
%
\global\setbox\partialpage = \vbox{%
% Unvbox the main output page.
\unvbox\PAGE
\kern-\topskip \kern\baselineskip
}%
}%
\eject % run that output routine to set \partialpage
%
% Use the double-column output routine for subsequent pages.
\output = {\doublecolumnout}%
%
% Change the page size parameters. We could do this once outside this
% routine, in each of @smallbook, @afourpaper, and the default 8.5x11
% format, but then we repeat the same computation. Repeating a couple
% of assignments once per index is clearly meaningless for the
% execution time, so we may as well do it in one place.
%
% First we halve the line length, less a little for the gutter between
% the columns. We compute the gutter based on the line length, so it
% changes automatically with the paper format. The magic constant
% below is chosen so that the gutter has the same value (well, +-<1pt)
% as it did when we hard-coded it.
%
% We put the result in a separate register, \doublecolumhsize, so we
% can restore it in \pagesofar, after \hsize itself has (potentially)
% been clobbered.
%
\doublecolumnhsize = \hsize
\advance\doublecolumnhsize by -.04154\hsize
\divide\doublecolumnhsize by 2
\hsize = \doublecolumnhsize
%
% Double the \vsize as well. (We don't need a separate register here,
% since nobody clobbers \vsize.)
\vsize = 2\vsize
}
% The double-column output routine for all double-column pages except
% the last.
%
\def\doublecolumnout{%
\splittopskip=\topskip \splitmaxdepth=\maxdepth
% Get the available space for the double columns -- the normal
% (undoubled) page height minus any material left over from the
% previous page.
\dimen@ = \vsize
\divide\dimen@ by 2
\advance\dimen@ by -\ht\partialpage
%
% box0 will be the left-hand column, box2 the right.
\setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
\onepageout\pagesofar
\unvbox255
\penalty\outputpenalty
}
%
% Re-output the contents of the output page -- any previous material,
% followed by the two boxes we just split, in box0 and box2.
\def\pagesofar{%
\unvbox\partialpage
%
\hsize = \doublecolumnhsize
\wd0=\hsize \wd2=\hsize
\hbox to\pagewidth{\box0\hfil\box2}%
}
%
% All done with double columns.
\def\enddoublecolumns{%
% The following penalty ensures that the page builder is exercised
% _before_ we change the output routine. This is necessary in the
% following situation:
%
% The last section of the index consists only of a single entry.
% Before this section, \pagetotal is less than \pagegoal, so no
% break occurs before the last section starts. However, the last
% section, consisting of \initial and the single \entry, does not
% fit on the page and has to be broken off. Without the following
% penalty the page builder will not be exercised until \eject
% below, and by that time we'll already have changed the output
% routine to the \balancecolumns version, so the next-to-last
% double-column page will be processed with \balancecolumns, which
% is wrong: The two columns will go to the main vertical list, with
% the broken-off section in the recent contributions. As soon as
% the output routine finishes, TeX starts reconsidering the page
% break. The two columns and the broken-off section both fit on the
% page, because the two columns now take up only half of the page
% goal. When TeX sees \eject from below which follows the final
% section, it invokes the new output routine that we've set after
% \balancecolumns below; \onepageout will try to fit the two columns
% and the final section into the vbox of \pageheight (see
% \pagebody), causing an overfull box.
%
% Note that glue won't work here, because glue does not exercise the
% page builder, unlike penalties (see The TeXbook, pp. 280-281).
\penalty0
%
\output = {%
% Split the last of the double-column material. Leave it on the
% current page, no automatic page break.
\balancecolumns
%
% If we end up splitting too much material for the current page,
% though, there will be another page break right after this \output
% invocation ends. Having called \balancecolumns once, we do not
% want to call it again. Therefore, reset \output to its normal
% definition right away. (We hope \balancecolumns will never be
% called on to balance too much material, but if it is, this makes
% the output somewhat more palatable.)
\global\output = {\onepageout{\pagecontents\PAGE}}%
}%
\eject
\endgroup % started in \begindoublecolumns
%
% \pagegoal was set to the doubled \vsize above, since we restarted
% the current page. We're now back to normal single-column
% typesetting, so reset \pagegoal to the normal \vsize (after the
% \endgroup where \vsize got restored).
\pagegoal = \vsize
}
%
% Called at the end of the double column material.
\def\balancecolumns{%
\setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
\dimen@ = \ht0
\advance\dimen@ by \topskip
\advance\dimen@ by-\baselineskip
\divide\dimen@ by 2 % target to split to
%debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}%
\splittopskip = \topskip
% Loop until we get a decent breakpoint.
{%
\vbadness = 10000
\loop
\global\setbox3 = \copy0
\global\setbox1 = \vsplit3 to \dimen@
\ifdim\ht3>\dimen@
\global\advance\dimen@ by 1pt
\repeat
}%
%debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}%
\setbox0=\vbox to\dimen@{\unvbox1}%
\setbox2=\vbox to\dimen@{\unvbox3}%
%
\pagesofar
}
\catcode`\@ = \other
\message{sectioning,}
% Chapters, sections, etc.
% Let's start with @part.
\outer\parseargdef\part{\partzzz{#1}}
\def\partzzz#1{%
\chapoddpage
\null
\vskip.3\vsize % move it down on the page a bit
\begingroup
\noindent \titlefonts\rmisbold #1\par % the text
\let\lastnode=\empty % no node to associate with
\writetocentry{part}{#1}{}% but put it in the toc
\headingsoff % no headline or footline on the part page
\chapoddpage
\endgroup
}
% \unnumberedno is an oxymoron. But we count the unnumbered
% sections so that we can refer to them unambiguously in the pdf
% outlines by their "section number". We avoid collisions with chapter
% numbers by starting them at 10000. (If a document ever has 10000
% chapters, we're in trouble anyway, I'm sure.)
\newcount\unnumberedno \unnumberedno = 10000
\newcount\chapno
\newcount\secno \secno=0
\newcount\subsecno \subsecno=0
\newcount\subsubsecno \subsubsecno=0
% This counter is funny since it counts through charcodes of letters A, B, ...
\newcount\appendixno \appendixno = `\@
%
% \def\appendixletter{\char\the\appendixno}
% We do the following ugly conditional instead of the above simple
% construct for the sake of pdftex, which needs the actual
% letter in the expansion, not just typeset.
%
\def\appendixletter{%
\ifnum\appendixno=`A A%
\else\ifnum\appendixno=`B B%
\else\ifnum\appendixno=`C C%
\else\ifnum\appendixno=`D D%
\else\ifnum\appendixno=`E E%
\else\ifnum\appendixno=`F F%
\else\ifnum\appendixno=`G G%
\else\ifnum\appendixno=`H H%
\else\ifnum\appendixno=`I I%
\else\ifnum\appendixno=`J J%
\else\ifnum\appendixno=`K K%
\else\ifnum\appendixno=`L L%
\else\ifnum\appendixno=`M M%
\else\ifnum\appendixno=`N N%
\else\ifnum\appendixno=`O O%
\else\ifnum\appendixno=`P P%
\else\ifnum\appendixno=`Q Q%
\else\ifnum\appendixno=`R R%
\else\ifnum\appendixno=`S S%
\else\ifnum\appendixno=`T T%
\else\ifnum\appendixno=`U U%
\else\ifnum\appendixno=`V V%
\else\ifnum\appendixno=`W W%
\else\ifnum\appendixno=`X X%
\else\ifnum\appendixno=`Y Y%
\else\ifnum\appendixno=`Z Z%
% The \the is necessary, despite appearances, because \appendixletter is
% expanded while writing the .toc file. \char\appendixno is not
% expandable, thus it is written literally, thus all appendixes come out
% with the same letter (or @) in the toc without it.
\else\char\the\appendixno
\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
% Each @chapter defines these (using marks) as the number+name, number
% and name of the chapter. Page headings and footings can use
% these. @section does likewise.
\def\thischapter{}
\def\thischapternum{}
\def\thischaptername{}
\def\thissection{}
\def\thissectionnum{}
\def\thissectionname{}
\newcount\absseclevel % used to calculate proper heading level
\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count
% @raisesections: treat @section as chapter, @subsection as section, etc.
\def\raisesections{\global\advance\secbase by -1}
\let\up=\raisesections % original BFox name
% @lowersections: treat @chapter as section, @section as subsection, etc.
\def\lowersections{\global\advance\secbase by 1}
\let\down=\lowersections % original BFox name
% we only have subsub.
\chardef\maxseclevel = 3
%
% A numbered section within an unnumbered changes to unnumbered too.
% To achieve this, remember the "biggest" unnum. sec. we are currently in:
\chardef\unnlevel = \maxseclevel
%
% Trace whether the current chapter is an appendix or not:
% \chapheadtype is "N" or "A", unnumbered chapters are ignored.
\def\chapheadtype{N}
% Choose a heading macro
% #1 is heading type
% #2 is heading level
% #3 is text for heading
\def\genhead#1#2#3{%
% Compute the abs. sec. level:
\absseclevel=#2
\advance\absseclevel by \secbase
% Make sure \absseclevel doesn't fall outside the range:
\ifnum \absseclevel < 0
\absseclevel = 0
\else
\ifnum \absseclevel > 3
\absseclevel = 3
\fi
\fi
% The heading type:
\def\headtype{#1}%
\if \headtype U%
\ifnum \absseclevel < \unnlevel
\chardef\unnlevel = \absseclevel
\fi
\else
% Check for appendix sections:
\ifnum \absseclevel = 0
\edef\chapheadtype{\headtype}%
\else
\if \headtype A\if \chapheadtype N%
\errmessage{@appendix... within a non-appendix chapter}%
\fi\fi
\fi
% Check for numbered within unnumbered:
\ifnum \absseclevel > \unnlevel
\def\headtype{U}%
\else
\chardef\unnlevel = 3
\fi
\fi
% Now print the heading:
\if \headtype U%
\ifcase\absseclevel
\unnumberedzzz{#3}%
\or \unnumberedseczzz{#3}%
\or \unnumberedsubseczzz{#3}%
\or \unnumberedsubsubseczzz{#3}%
\fi
\else
\if \headtype A%
\ifcase\absseclevel
\appendixzzz{#3}%
\or \appendixsectionzzz{#3}%
\or \appendixsubseczzz{#3}%
\or \appendixsubsubseczzz{#3}%
\fi
\else
\ifcase\absseclevel
\chapterzzz{#3}%
\or \seczzz{#3}%
\or \numberedsubseczzz{#3}%
\or \numberedsubsubseczzz{#3}%
\fi
\fi
\fi
\suppressfirstparagraphindent
}
% an interface:
\def\numhead{\genhead N}
\def\apphead{\genhead A}
\def\unnmhead{\genhead U}
% @chapter, @appendix, @unnumbered. Increment top-level counter, reset
% all lower-level sectioning counters to zero.
%
% Also set \chaplevelprefix, which we prepend to @float sequence numbers
% (e.g., figures), q.v. By default (before any chapter), that is empty.
\let\chaplevelprefix = \empty
%
\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz
\def\chapterzzz#1{%
% section resetting is \global in case the chapter is in a group, such
% as an @include file.
\global\secno=0 \global\subsecno=0 \global\subsubsecno=0
\global\advance\chapno by 1
%
% Used for \float.
\gdef\chaplevelprefix{\the\chapno.}%
\resetallfloatnos
%
% \putwordChapter can contain complex things in translations.
\toks0=\expandafter{\putwordChapter}%
\message{\the\toks0 \space \the\chapno}%
%
% Write the actual heading.
\chapmacro{#1}{Ynumbered}{\the\chapno}%
%
% So @section and the like are numbered underneath this chapter.
\global\let\section = \numberedsec
\global\let\subsection = \numberedsubsec
\global\let\subsubsection = \numberedsubsubsec
}
\outer\parseargdef\appendix{\apphead0{#1}} % normally calls appendixzzz
%
\def\appendixzzz#1{%
\global\secno=0 \global\subsecno=0 \global\subsubsecno=0
\global\advance\appendixno by 1
\gdef\chaplevelprefix{\appendixletter.}%
\resetallfloatnos
%
% \putwordAppendix can contain complex things in translations.
\toks0=\expandafter{\putwordAppendix}%
\message{\the\toks0 \space \appendixletter}%
%
\chapmacro{#1}{Yappendix}{\appendixletter}%
%
\global\let\section = \appendixsec
\global\let\subsection = \appendixsubsec
\global\let\subsubsection = \appendixsubsubsec
}
% normally unnmhead0 calls unnumberedzzz:
\outer\parseargdef\unnumbered{\unnmhead0{#1}}
\def\unnumberedzzz#1{%
\global\secno=0 \global\subsecno=0 \global\subsubsecno=0
\global\advance\unnumberedno by 1
%
% Since an unnumbered has no number, no prefix for figures.
\global\let\chaplevelprefix = \empty
\resetallfloatnos
%
% This used to be simply \message{#1}, but TeX fully expands the
% argument to \message. Therefore, if #1 contained @-commands, TeX
% expanded them. For example, in `@unnumbered The @cite{Book}', TeX
% expanded @cite (which turns out to cause errors because \cite is meant
% to be executed, not expanded).
%
% Anyway, we don't want the fully-expanded definition of @cite to appear
% as a result of the \message, we just want `@cite' itself. We use
% \the to achieve this: TeX expands \the only once,
% simply yielding the contents of . (We also do this for
% the toc entries.)
\toks0 = {#1}%
\message{(\the\toks0)}%
%
\chapmacro{#1}{Ynothing}{\the\unnumberedno}%
%
\global\let\section = \unnumberedsec
\global\let\subsection = \unnumberedsubsec
\global\let\subsubsection = \unnumberedsubsubsec
}
% @centerchap is like @unnumbered, but the heading is centered.
\outer\parseargdef\centerchap{%
% Well, we could do the following in a group, but that would break
% an assumption that \chapmacro is called at the outermost level.
% Thus we are safer this way: --kasal, 24feb04
\let\centerparametersmaybe = \centerparameters
\unnmhead0{#1}%
\let\centerparametersmaybe = \relax
}
% @top is like @unnumbered.
\let\top\unnumbered
% Sections.
%
\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz
\def\seczzz#1{%
\global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
\sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%
}
% normally calls appendixsectionzzz:
\outer\parseargdef\appendixsection{\apphead1{#1}}
\def\appendixsectionzzz#1{%
\global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
\sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%
}
\let\appendixsec\appendixsection
% normally calls unnumberedseczzz:
\outer\parseargdef\unnumberedsec{\unnmhead1{#1}}
\def\unnumberedseczzz#1{%
\global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
\sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%
}
% Subsections.
%
% normally calls numberedsubseczzz:
\outer\parseargdef\numberedsubsec{\numhead2{#1}}
\def\numberedsubseczzz#1{%
\global\subsubsecno=0 \global\advance\subsecno by 1
\sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%
}
% normally calls appendixsubseczzz:
\outer\parseargdef\appendixsubsec{\apphead2{#1}}
\def\appendixsubseczzz#1{%
\global\subsubsecno=0 \global\advance\subsecno by 1
\sectionheading{#1}{subsec}{Yappendix}%
{\appendixletter.\the\secno.\the\subsecno}%
}
% normally calls unnumberedsubseczzz:
\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}}
\def\unnumberedsubseczzz#1{%
\global\subsubsecno=0 \global\advance\subsecno by 1
\sectionheading{#1}{subsec}{Ynothing}%
{\the\unnumberedno.\the\secno.\the\subsecno}%
}
% Subsubsections.
%
% normally numberedsubsubseczzz:
\outer\parseargdef\numberedsubsubsec{\numhead3{#1}}
\def\numberedsubsubseczzz#1{%
\global\advance\subsubsecno by 1
\sectionheading{#1}{subsubsec}{Ynumbered}%
{\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}%
}
% normally appendixsubsubseczzz:
\outer\parseargdef\appendixsubsubsec{\apphead3{#1}}
\def\appendixsubsubseczzz#1{%
\global\advance\subsubsecno by 1
\sectionheading{#1}{subsubsec}{Yappendix}%
{\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}%
}
% normally unnumberedsubsubseczzz:
\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}}
\def\unnumberedsubsubseczzz#1{%
\global\advance\subsubsecno by 1
\sectionheading{#1}{subsubsec}{Ynothing}%
{\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}%
}
% These macros control what the section commands do, according
% to what kind of chapter we are in (ordinary, appendix, or unnumbered).
% Define them by default for a numbered chapter.
\let\section = \numberedsec
\let\subsection = \numberedsubsec
\let\subsubsection = \numberedsubsubsec
% Define @majorheading, @heading and @subheading
\def\majorheading{%
{\advance\chapheadingskip by 10pt \chapbreak }%
\parsearg\chapheadingzzz
}
\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
\def\chapheadingzzz#1{%
\vbox{\chapfonts \raggedtitlesettings #1\par}%
\nobreak\bigskip \nobreak
\suppressfirstparagraphindent
}
% @heading, @subheading, @subsubheading.
\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{}
\suppressfirstparagraphindent}
\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{}
\suppressfirstparagraphindent}
\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{}
\suppressfirstparagraphindent}
% These macros generate a chapter, section, etc. heading only
% (including whitespace, linebreaking, etc. around it),
% given all the information in convenient, parsed form.
% Args are the skip and penalty (usually negative)
\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}
% Parameter controlling skip before chapter headings (if needed)
\newskip\chapheadingskip
% Define plain chapter starts, and page on/off switching for it.
\def\chapbreak{\dobreak \chapheadingskip {-4000}}
\def\chappager{\par\vfill\supereject}
% Because \domark is called before \chapoddpage, the filler page will
% get the headings for the next chapter, which is wrong. But we don't
% care -- we just disable all headings on the filler page.
\def\chapoddpage{%
\chappager
\ifodd\pageno \else
\begingroup
\headingsoff
\null
\chappager
\endgroup
\fi
}
\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}
\def\CHAPPAGoff{%
\global\let\contentsalignmacro = \chappager
\global\let\pchapsepmacro=\chapbreak
\global\let\pagealignmacro=\chappager}
\def\CHAPPAGon{%
\global\let\contentsalignmacro = \chappager
\global\let\pchapsepmacro=\chappager
\global\let\pagealignmacro=\chappager
\global\def\HEADINGSon{\HEADINGSsingle}}
\def\CHAPPAGodd{%
\global\let\contentsalignmacro = \chapoddpage
\global\let\pchapsepmacro=\chapoddpage
\global\let\pagealignmacro=\chapoddpage
\global\def\HEADINGSon{\HEADINGSdouble}}
\CHAPPAGon
% Chapter opening.
%
% #1 is the text, #2 is the section type (Ynumbered, Ynothing,
% Yappendix, Yomitfromtoc), #3 the chapter number.
%
% To test against our argument.
\def\Ynothingkeyword{Ynothing}
\def\Yomitfromtockeyword{Yomitfromtoc}
\def\Yappendixkeyword{Yappendix}
%
\def\chapmacro#1#2#3{%
% Insert the first mark before the heading break (see notes for \domark).
\let\prevchapterdefs=\lastchapterdefs
\let\prevsectiondefs=\lastsectiondefs
\gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}%
\gdef\thissection{}}%
%
\def\temptype{#2}%
\ifx\temptype\Ynothingkeyword
\gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
\gdef\thischapter{\thischaptername}}%
\else\ifx\temptype\Yomitfromtockeyword
\gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
\gdef\thischapter{}}%
\else\ifx\temptype\Yappendixkeyword
\toks0={#1}%
\xdef\lastchapterdefs{%
\gdef\noexpand\thischaptername{\the\toks0}%
\gdef\noexpand\thischapternum{\appendixletter}%
% \noexpand\putwordAppendix avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thischapter{\noexpand\putwordAppendix{}
\noexpand\thischapternum:
\noexpand\thischaptername}%
}%
\else
\toks0={#1}%
\xdef\lastchapterdefs{%
\gdef\noexpand\thischaptername{\the\toks0}%
\gdef\noexpand\thischapternum{\the\chapno}%
% \noexpand\putwordChapter avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thischapter{\noexpand\putwordChapter{}
\noexpand\thischapternum:
\noexpand\thischaptername}%
}%
\fi\fi\fi
%
% Output the mark. Pass it through \safewhatsit, to take care of
% the preceding space.
\safewhatsit\domark
%
% Insert the chapter heading break.
\pchapsepmacro
%
% Now the second mark, after the heading break. No break points
% between here and the heading.
\let\prevchapterdefs=\lastchapterdefs
\let\prevsectiondefs=\lastsectiondefs
\domark
%
{%
\chapfonts \rmisbold
%
% Have to define \lastsection before calling \donoderef, because the
% xref code eventually uses it. On the other hand, it has to be called
% after \pchapsepmacro, or the headline will change too soon.
\gdef\lastsection{#1}%
%
% Only insert the separating space if we have a chapter/appendix
% number, and don't print the unnumbered ``number''.
\ifx\temptype\Ynothingkeyword
\setbox0 = \hbox{}%
\def\toctype{unnchap}%
\else\ifx\temptype\Yomitfromtockeyword
\setbox0 = \hbox{}% contents like unnumbered, but no toc entry
\def\toctype{omit}%
\else\ifx\temptype\Yappendixkeyword
\setbox0 = \hbox{\putwordAppendix{} #3\enspace}%
\def\toctype{app}%
\else
\setbox0 = \hbox{#3\enspace}%
\def\toctype{numchap}%
\fi\fi\fi
%
% Write the toc entry for this chapter. Must come before the
% \donoderef, because we include the current node name in the toc
% entry, and \donoderef resets it to empty.
\writetocentry{\toctype}{#1}{#3}%
%
% For pdftex, we have to write out the node definition (aka, make
% the pdfdest) after any page break, but before the actual text has
% been typeset. If the destination for the pdf outline is after the
% text, then jumping from the outline may wind up with the text not
% being visible, for instance under high magnification.
\donoderef{#2}%
%
% Typeset the actual heading.
\nobreak % Avoid page breaks at the interline glue.
\vbox{\raggedtitlesettings \hangindent=\wd0 \centerparametersmaybe
\unhbox0 #1\par}%
}%
\nobreak\bigskip % no page break after a chapter title
\nobreak
}
% @centerchap -- centered and unnumbered.
\let\centerparametersmaybe = \relax
\def\centerparameters{%
\advance\rightskip by 3\rightskip
\leftskip = \rightskip
\parfillskip = 0pt
}
% I don't think this chapter style is supported any more, so I'm not
% updating it with the new noderef stuff. We'll see. --karl, 11aug03.
%
\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
%
\def\unnchfopen #1{%
\chapoddpage
\vbox{\chapfonts \raggedtitlesettings #1\par}%
\nobreak\bigskip\nobreak
}
\def\chfopen #1#2{\chapoddpage {\chapfonts
\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
\par\penalty 5000 %
}
\def\centerchfopen #1{%
\chapoddpage
\vbox{\chapfonts \raggedtitlesettings \hfill #1\hfill}%
\nobreak\bigskip \nobreak
}
\def\CHAPFopen{%
\global\let\chapmacro=\chfopen
\global\let\centerchapmacro=\centerchfopen}
% Section titles. These macros combine the section number parts and
% call the generic \sectionheading to do the printing.
%
\newskip\secheadingskip
\def\secheadingbreak{\dobreak \secheadingskip{-1000}}
% Subsection titles.
\newskip\subsecheadingskip
\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}}
% Subsubsection titles.
\def\subsubsecheadingskip{\subsecheadingskip}
\def\subsubsecheadingbreak{\subsecheadingbreak}
% Print any size, any type, section title.
%
% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is
% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the
% section number.
%
\def\seckeyword{sec}
%
\def\sectionheading#1#2#3#4{%
{%
\checkenv{}% should not be in an environment.
%
% Switch to the right set of fonts.
\csname #2fonts\endcsname \rmisbold
%
\def\sectionlevel{#2}%
\def\temptype{#3}%
%
% Insert first mark before the heading break (see notes for \domark).
\let\prevsectiondefs=\lastsectiondefs
\ifx\temptype\Ynothingkeyword
\ifx\sectionlevel\seckeyword
\gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}%
\gdef\thissection{\thissectionname}}%
\fi
\else\ifx\temptype\Yomitfromtockeyword
% Don't redefine \thissection.
\else\ifx\temptype\Yappendixkeyword
\ifx\sectionlevel\seckeyword
\toks0={#1}%
\xdef\lastsectiondefs{%
\gdef\noexpand\thissectionname{\the\toks0}%
\gdef\noexpand\thissectionnum{#4}%
% \noexpand\putwordSection avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thissection{\noexpand\putwordSection{}
\noexpand\thissectionnum:
\noexpand\thissectionname}%
}%
\fi
\else
\ifx\sectionlevel\seckeyword
\toks0={#1}%
\xdef\lastsectiondefs{%
\gdef\noexpand\thissectionname{\the\toks0}%
\gdef\noexpand\thissectionnum{#4}%
% \noexpand\putwordSection avoids expanding indigestible
% commands in some of the translations.
\gdef\noexpand\thissection{\noexpand\putwordSection{}
\noexpand\thissectionnum:
\noexpand\thissectionname}%
}%
\fi
\fi\fi\fi
%
% Go into vertical mode. Usually we'll already be there, but we
% don't want the following whatsit to end up in a preceding paragraph
% if the document didn't happen to have a blank line.
\par
%
% Output the mark. Pass it through \safewhatsit, to take care of
% the preceding space.
\safewhatsit\domark
%
% Insert space above the heading.
\csname #2headingbreak\endcsname
%
% Now the second mark, after the heading break. No break points
% between here and the heading.
\global\let\prevsectiondefs=\lastsectiondefs
\domark
%
% Only insert the space after the number if we have a section number.
\ifx\temptype\Ynothingkeyword
\setbox0 = \hbox{}%
\def\toctype{unn}%
\gdef\lastsection{#1}%
\else\ifx\temptype\Yomitfromtockeyword
% for @headings -- no section number, don't include in toc,
% and don't redefine \lastsection.
\setbox0 = \hbox{}%
\def\toctype{omit}%
\let\sectionlevel=\empty
\else\ifx\temptype\Yappendixkeyword
\setbox0 = \hbox{#4\enspace}%
\def\toctype{app}%
\gdef\lastsection{#1}%
\else
\setbox0 = \hbox{#4\enspace}%
\def\toctype{num}%
\gdef\lastsection{#1}%
\fi\fi\fi
%
% Write the toc entry (before \donoderef). See comments in \chapmacro.
\writetocentry{\toctype\sectionlevel}{#1}{#4}%
%
% Write the node reference (= pdf destination for pdftex).
% Again, see comments in \chapmacro.
\donoderef{#3}%
%
% Interline glue will be inserted when the vbox is completed.
% That glue will be a valid breakpoint for the page, since it'll be
% preceded by a whatsit (usually from the \donoderef, or from the
% \writetocentry if there was no node). We don't want to allow that
% break, since then the whatsits could end up on page n while the
% section is on page n+1, thus toc/etc. are wrong. Debian bug 276000.
\nobreak
%
% Output the actual section heading.
\vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
\hangindent=\wd0 % zero if no section number
\unhbox0 #1}%
}%
% Add extra space after the heading -- half of whatever came above it.
% Don't allow stretch, though.
\kern .5 \csname #2headingskip\endcsname
%
% Do not let the kern be a potential breakpoint, as it would be if it
% was followed by glue.
\nobreak
%
% We'll almost certainly start a paragraph next, so don't let that
% glue accumulate. (Not a breakpoint because it's preceded by a
% discardable item.) However, when a paragraph is not started next
% (\startdefun, \cartouche, \center, etc.), this needs to be wiped out
% or the negative glue will cause weirdly wrong output, typically
% obscuring the section heading with something else.
\vskip-\parskip
%
% This is so the last item on the main vertical list is a known
% \penalty > 10000, so \startdefun, etc., can recognize the situation
% and do the needful.
\penalty 10001
}
\message{toc,}
% Table of contents.
\newwrite\tocfile
% Write an entry to the toc file, opening it if necessary.
% Called from @chapter, etc.
%
% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno}
% We append the current node name (if any) and page number as additional
% arguments for the \{chap,sec,...}entry macros which will eventually
% read this. The node name is used in the pdf outlines as the
% destination to jump to.
%
% We open the .toc file for writing here instead of at @setfilename (or
% any other fixed time) so that @contents can be anywhere in the document.
% But if #1 is `omit', then we don't do anything. This is used for the
% table of contents chapter openings themselves.
%
\newif\iftocfileopened
\def\omitkeyword{omit}%
%
\def\writetocentry#1#2#3{%
\edef\writetoctype{#1}%
\ifx\writetoctype\omitkeyword \else
\iftocfileopened\else
\immediate\openout\tocfile = \jobname.toc
\global\tocfileopenedtrue
\fi
%
\iflinks
{\atdummies
\edef\temp{%
\write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}%
\temp
}%
\fi
\fi
%
% Tell \shipout to create a pdf destination on each page, if we're
% writing pdf. These are used in the table of contents. We can't
% just write one on every page because the title pages are numbered
% 1 and 2 (the page numbers aren't printed), and so are the first
% two pages of the document. Thus, we'd have two destinations named
% `1', and two named `2'.
\ifpdf \global\pdfmakepagedesttrue \fi
}
% These characters do not print properly in the Computer Modern roman
% fonts, so we must take special care. This is more or less redundant
% with the Texinfo input format setup at the end of this file.
%
\def\activecatcodes{%
\catcode`\"=\active
\catcode`\$=\active
\catcode`\<=\active
\catcode`\>=\active
\catcode`\\=\active
\catcode`\^=\active
\catcode`\_=\active
\catcode`\|=\active
\catcode`\~=\active
}
% Read the toc file, which is essentially Texinfo input.
\def\readtocfile{%
\setupdatafile
\activecatcodes
\input \tocreadfilename
}
\newskip\contentsrightmargin \contentsrightmargin=1in
\newcount\savepageno
\newcount\lastnegativepageno \lastnegativepageno = -1
% Prepare to read what we've written to \tocfile.
%
\def\startcontents#1{%
% If @setchapternewpage on, and @headings double, the contents should
% start on an odd page, unlike chapters. Thus, we maintain
% \contentsalignmacro in parallel with \pagealignmacro.
% From: Torbjorn Granlund
\contentsalignmacro
\immediate\closeout\tocfile
%
% Don't need to put `Contents' or `Short Contents' in the headline.
% It is abundantly clear what they are.
\chapmacro{#1}{Yomitfromtoc}{}%
%
\savepageno = \pageno
\begingroup % Set up to handle contents files properly.
\raggedbottom % Worry more about breakpoints than the bottom.
\advance\hsize by -\contentsrightmargin % Don't use the full line length.
%
% Roman numerals for page numbers.
\ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi
}
% redefined for the two-volume lispref. We always output on
% \jobname.toc even if this is redefined.
%
\def\tocreadfilename{\jobname.toc}
% Normal (long) toc.
%
\def\contents{%
\startcontents{\putwordTOC}%
\openin 1 \tocreadfilename\space
\ifeof 1 \else
\readtocfile
\fi
\vfill \eject
\contentsalignmacro % in case @setchapternewpage odd is in effect
\ifeof 1 \else
\pdfmakeoutlines
\fi
\closein 1
\endgroup
\lastnegativepageno = \pageno
\global\pageno = \savepageno
}
% And just the chapters.
\def\summarycontents{%
\startcontents{\putwordShortTOC}%
%
\let\partentry = \shortpartentry
\let\numchapentry = \shortchapentry
\let\appentry = \shortchapentry
\let\unnchapentry = \shortunnchapentry
% We want a true roman here for the page numbers.
\secfonts
\let\rm=\shortcontrm \let\bf=\shortcontbf
\let\sl=\shortcontsl \let\tt=\shortconttt
\rm
\hyphenpenalty = 10000
\advance\baselineskip by 1pt % Open it up a little.
\def\numsecentry##1##2##3##4{}
\let\appsecentry = \numsecentry
\let\unnsecentry = \numsecentry
\let\numsubsecentry = \numsecentry
\let\appsubsecentry = \numsecentry
\let\unnsubsecentry = \numsecentry
\let\numsubsubsecentry = \numsecentry
\let\appsubsubsecentry = \numsecentry
\let\unnsubsubsecentry = \numsecentry
\openin 1 \tocreadfilename\space
\ifeof 1 \else
\readtocfile
\fi
\closein 1
\vfill \eject
\contentsalignmacro % in case @setchapternewpage odd is in effect
\endgroup
\lastnegativepageno = \pageno
\global\pageno = \savepageno
}
\let\shortcontents = \summarycontents
% Typeset the label for a chapter or appendix for the short contents.
% The arg is, e.g., `A' for an appendix, or `3' for a chapter.
%
\def\shortchaplabel#1{%
% This space should be enough, since a single number is .5em, and the
% widest letter (M) is 1em, at least in the Computer Modern fonts.
% But use \hss just in case.
% (This space doesn't include the extra space that gets added after
% the label; that gets put in by \shortchapentry above.)
%
% We'd like to right-justify chapter numbers, but that looks strange
% with appendix letters. And right-justifying numbers and
% left-justifying letters looks strange when there is less than 10
% chapters. Have to read the whole toc once to know how many chapters
% there are before deciding ...
\hbox to 1em{#1\hss}%
}
% These macros generate individual entries in the table of contents.
% The first argument is the chapter or section name.
% The last argument is the page number.
% The arguments in between are the chapter number, section number, ...
% Parts, in the main contents. Replace the part number, which doesn't
% exist, with an empty box. Let's hope all the numbers have the same width.
% Also ignore the page number, which is conventionally not printed.
\def\numeralbox{\setbox0=\hbox{8}\hbox to \wd0{\hfil}}
\def\partentry#1#2#3#4{\dochapentry{\numeralbox\labelspace#1}{}}
%
% Parts, in the short toc.
\def\shortpartentry#1#2#3#4{%
\penalty-300
\vskip.5\baselineskip plus.15\baselineskip minus.1\baselineskip
\shortchapentry{{\bf #1}}{\numeralbox}{}{}%
}
% Chapters, in the main contents.
\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}}
%
% Chapters, in the short toc.
% See comments in \dochapentry re vbox and related settings.
\def\shortchapentry#1#2#3#4{%
\tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}%
}
% Appendices, in the main contents.
% Need the word Appendix, and a fixed-size box.
%
\def\appendixbox#1{%
% We use M since it's probably the widest letter.
\setbox0 = \hbox{\putwordAppendix{} M}%
\hbox to \wd0{\putwordAppendix{} #1\hss}}
%
\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}}
% Unnumbered chapters.
\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}}
\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}}
% Sections.
\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}}
\let\appsecentry=\numsecentry
\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}}
% Subsections.
\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}}
\let\appsubsecentry=\numsubsecentry
\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}}
% And subsubsections.
\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}}
\let\appsubsubsecentry=\numsubsubsecentry
\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}}
% This parameter controls the indentation of the various levels.
% Same as \defaultparindent.
\newdimen\tocindent \tocindent = 15pt
% Now for the actual typesetting. In all these, #1 is the text and #2 is the
% page number.
%
% If the toc has to be broken over pages, we want it to be at chapters
% if at all possible; hence the \penalty.
\def\dochapentry#1#2{%
\penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip
\begingroup
\chapentryfonts
\tocentry{#1}{\dopageno\bgroup#2\egroup}%
\endgroup
\nobreak\vskip .25\baselineskip plus.1\baselineskip
}
\def\dosecentry#1#2{\begingroup
\secentryfonts \leftskip=\tocindent
\tocentry{#1}{\dopageno\bgroup#2\egroup}%
\endgroup}
\def\dosubsecentry#1#2{\begingroup
\subsecentryfonts \leftskip=2\tocindent
\tocentry{#1}{\dopageno\bgroup#2\egroup}%
\endgroup}
\def\dosubsubsecentry#1#2{\begingroup
\subsubsecentryfonts \leftskip=3\tocindent
\tocentry{#1}{\dopageno\bgroup#2\egroup}%
\endgroup}
% We use the same \entry macro as for the index entries.
\let\tocentry = \entry
% Space between chapter (or whatever) number and the title.
\def\labelspace{\hskip1em \relax}
\def\dopageno#1{{\rm #1}}
\def\doshortpageno#1{{\rm #1}}
\def\chapentryfonts{\secfonts \rm}
\def\secentryfonts{\textfonts}
\def\subsecentryfonts{\textfonts}
\def\subsubsecentryfonts{\textfonts}
\message{environments,}
% @foo ... @end foo.
% @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 @ character.
\envdef\tex{%
\setupmarkupstyle{tex}%
\catcode `\\=0 \catcode `\{=1 \catcode `\}=2
\catcode `\$=3 \catcode `\&=4 \catcode `\#=6
\catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie
\catcode `\%=14
\catcode `\+=\other
\catcode `\"=\other
\catcode `\|=\other
\catcode `\<=\other
\catcode `\>=\other
\catcode `\`=\other
\catcode `\'=\other
\escapechar=`\\
%
% ' is active in math mode (mathcode"8000). So reset it, and all our
% other math active characters (just in case), to plain's definitions.
\mathactive
%
\let\b=\ptexb
\let\bullet=\ptexbullet
\let\c=\ptexc
\let\,=\ptexcomma
\let\.=\ptexdot
\let\dots=\ptexdots
\let\equiv=\ptexequiv
\let\!=\ptexexclam
\let\i=\ptexi
\let\indent=\ptexindent
\let\noindent=\ptexnoindent
\let\{=\ptexlbrace
\let\+=\tabalign
\let\}=\ptexrbrace
\let\/=\ptexslash
\let\*=\ptexstar
\let\t=\ptext
\expandafter \let\csname top\endcsname=\ptextop % we've made it outer
\let\frenchspacing=\plainfrenchspacing
%
\def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
\def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
\def\@{@}%
}
% There is no need to define \Etex.
% Define @lisp ... @end lisp.
% @lisp environment forms a group so it can rebind things,
% including the definition of @end lisp (which normally is erroneous).
% Amount to narrow the margins by for @lisp.
\newskip\lispnarrowing \lispnarrowing=0.4in
% This is the definition that ^^M gets inside @lisp, @example, and other
% such environments. \null is better than a space, since it doesn't
% have any width.
\def\lisppar{\null\endgraf}
% This space is always present above and below environments.
\newskip\envskipamount \envskipamount = 0pt
% Make spacing and below environment symmetrical. We use \parskip here
% to help in doing that, since in @example-like environments \parskip
% is reset to zero; thus the \afterenvbreak inserts no space -- but the
% start of the next paragraph will insert \parskip.
%
\def\aboveenvbreak{{%
% =10000 instead of <10000 because of a special case in \itemzzz and
% \sectionheading, q.v.
\ifnum \lastpenalty=10000 \else
\advance\envskipamount by \parskip
\endgraf
\ifdim\lastskip<\envskipamount
\removelastskip
% it's not a good place to break if the last penalty was \nobreak
% or better ...
\ifnum\lastpenalty<10000 \penalty-50 \fi
\vskip\envskipamount
\fi
\fi
}}
\let\afterenvbreak = \aboveenvbreak
% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will
% also clear it, so that its embedded environments do the narrowing again.
\let\nonarrowing=\relax
% @cartouche ... @end cartouche: draw rectangle w/rounded corners around
% environment contents.
\font\circle=lcircle10
\newdimen\circthick
\newdimen\cartouter\newdimen\cartinner
\newskip\normbskip\newskip\normpskip\newskip\normlskip
\circthick=\fontdimen8\circle
%
\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth
\def\ctr{{\hskip 6pt\circle\char'010}}
\def\cbl{{\circle\char'012\hskip -6pt}}
\def\cbr{{\hskip 6pt\circle\char'011}}
\def\carttop{\hbox to \cartouter{\hskip\lskip
\ctl\leaders\hrule height\circthick\hfil\ctr
\hskip\rskip}}
\def\cartbot{\hbox to \cartouter{\hskip\lskip
\cbl\leaders\hrule height\circthick\hfil\cbr
\hskip\rskip}}
%
\newskip\lskip\newskip\rskip
\envdef\cartouche{%
\ifhmode\par\fi % can't be in the midst of a paragraph.
\startsavinginserts
\lskip=\leftskip \rskip=\rightskip
\leftskip=0pt\rightskip=0pt % we want these *outside*.
\cartinner=\hsize \advance\cartinner by-\lskip
\advance\cartinner by-\rskip
\cartouter=\hsize
\advance\cartouter by 18.4pt % allow for 3pt kerns on either
% side, and for 6pt waste from
% each corner char, and rule thickness
\normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip
% Flag to tell @lisp, etc., not to narrow margin.
\let\nonarrowing = t%
%
% If this cartouche directly follows a sectioning command, we need the
% \parskip glue (backspaced over by default) or the cartouche can
% collide with the section heading.
\ifnum\lastpenalty>10000 \vskip\parskip \penalty\lastpenalty \fi
%
\vbox\bgroup
\baselineskip=0pt\parskip=0pt\lineskip=0pt
\carttop
\hbox\bgroup
\hskip\lskip
\vrule\kern3pt
\vbox\bgroup
\kern3pt
\hsize=\cartinner
\baselineskip=\normbskip
\lineskip=\normlskip
\parskip=\normpskip
\vskip -\parskip
\comment % For explanation, see the end of def\group.
}
\def\Ecartouche{%
\ifhmode\par\fi
\kern3pt
\egroup
\kern3pt\vrule
\hskip\rskip
\egroup
\cartbot
\egroup
\checkinserts
}
% This macro is called at the beginning of all the @example variants,
% inside a group.
\newdimen\nonfillparindent
\def\nonfillstart{%
\aboveenvbreak
\ifdim\hfuzz < 12pt \hfuzz = 12pt \fi % Don't be fussy
\sepspaces % Make spaces be word-separators rather than space tokens.
\let\par = \lisppar % don't ignore blank lines
\obeylines % each line of input is a line of output
\parskip = 0pt
% Turn off paragraph indentation but redefine \indent to emulate
% the normal \indent.
\nonfillparindent=\parindent
\parindent = 0pt
\let\indent\nonfillindent
%
\emergencystretch = 0pt % don't try to avoid overfull boxes
\ifx\nonarrowing\relax
\advance \leftskip by \lispnarrowing
\exdentamount=\lispnarrowing
\else
\let\nonarrowing = \relax
\fi
\let\exdent=\nofillexdent
}
\begingroup
\obeyspaces
% We want to swallow spaces (but not other tokens) after the fake
% @indent in our nonfill-environments, where spaces are normally
% active and set to @tie, resulting in them not being ignored after
% @indent.
\gdef\nonfillindent{\futurelet\temp\nonfillindentcheck}%
\gdef\nonfillindentcheck{%
\ifx\temp %
\expandafter\nonfillindentgobble%
\else%
\leavevmode\nonfillindentbox%
\fi%
}%
\endgroup
\def\nonfillindentgobble#1{\nonfillindent}
\def\nonfillindentbox{\hbox to \nonfillparindent{\hss}}
% If you want all examples etc. small: @set dispenvsize small.
% If you want even small examples the full size: @set dispenvsize nosmall.
% This affects the following displayed environments:
% @example, @display, @format, @lisp
%
\def\smallword{small}
\def\nosmallword{nosmall}
\let\SETdispenvsize\relax
\def\setnormaldispenv{%
\ifx\SETdispenvsize\smallword
% end paragraph for sake of leading, in case document has no blank
% line. This is redundant with what happens in \aboveenvbreak, but
% we need to do it before changing the fonts, and it's inconvenient
% to change the fonts afterward.
\ifnum \lastpenalty=10000 \else \endgraf \fi
\smallexamplefonts \rm
\fi
}
\def\setsmalldispenv{%
\ifx\SETdispenvsize\nosmallword
\else
\ifnum \lastpenalty=10000 \else \endgraf \fi
\smallexamplefonts \rm
\fi
}
% We often define two environments, @foo and @smallfoo.
% Let's do it in one command. #1 is the env name, #2 the definition.
\def\makedispenvdef#1#2{%
\expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}%
\expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}%
\expandafter\let\csname E#1\endcsname \afterenvbreak
\expandafter\let\csname Esmall#1\endcsname \afterenvbreak
}
% Define two environment synonyms (#1 and #2) for an environment.
\def\maketwodispenvdef#1#2#3{%
\makedispenvdef{#1}{#3}%
\makedispenvdef{#2}{#3}%
}
%
% @lisp: indented, narrowed, typewriter font;
% @example: same as @lisp.
%
% @smallexample and @smalllisp: use smaller fonts.
% Originally contributed by Pavel@xerox.
%
\maketwodispenvdef{lisp}{example}{%
\nonfillstart
\tt\setupmarkupstyle{example}%
\let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
\gobble % eat return
}
% @display/@smalldisplay: same as @lisp except keep current font.
%
\makedispenvdef{display}{%
\nonfillstart
\gobble
}
% @format/@smallformat: same as @display except don't narrow margins.
%
\makedispenvdef{format}{%
\let\nonarrowing = t%
\nonfillstart
\gobble
}
% @flushleft: same as @format, but doesn't obey \SETdispenvsize.
\envdef\flushleft{%
\let\nonarrowing = t%
\nonfillstart
\gobble
}
\let\Eflushleft = \afterenvbreak
% @flushright.
%
\envdef\flushright{%
\let\nonarrowing = t%
\nonfillstart
\advance\leftskip by 0pt plus 1fill\relax
\gobble
}
\let\Eflushright = \afterenvbreak
% @raggedright does more-or-less normal line breaking but no right
% justification. From plain.tex.
\envdef\raggedright{%
\rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax
}
\let\Eraggedright\par
\envdef\raggedleft{%
\parindent=0pt \leftskip0pt plus2em
\spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
\hbadness=10000 % Last line will usually be underfull, so turn off
% badness reporting.
}
\let\Eraggedleft\par
\envdef\raggedcenter{%
\parindent=0pt \rightskip0pt plus1em \leftskip0pt plus1em
\spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
\hbadness=10000 % Last line will usually be underfull, so turn off
% badness reporting.
}
\let\Eraggedcenter\par
% @quotation does normal linebreaking (hence we can't use \nonfillstart)
% and narrows the margins. We keep \parskip nonzero in general, since
% we're doing normal filling. So, when using \aboveenvbreak and
% \afterenvbreak, temporarily make \parskip 0.
%
\makedispenvdef{quotation}{\quotationstart}
%
\def\quotationstart{%
\indentedblockstart % same as \indentedblock, but increase right margin too.
\ifx\nonarrowing\relax
\advance\rightskip by \lispnarrowing
\fi
\parsearg\quotationlabel
}
% We have retained a nonzero parskip for the environment, since we're
% doing normal filling.
%
\def\Equotation{%
\par
\ifx\quotationauthor\thisisundefined\else
% indent a bit.
\leftline{\kern 2\leftskip \sl ---\quotationauthor}%
\fi
{\parskip=0pt \afterenvbreak}%
}
\def\Esmallquotation{\Equotation}
% If we're given an argument, typeset it in bold with a colon after.
\def\quotationlabel#1{%
\def\temp{#1}%
\ifx\temp\empty \else
{\bf #1: }%
\fi
}
% @indentedblock is like @quotation, but indents only on the left and
% has no optional argument.
%
\makedispenvdef{indentedblock}{\indentedblockstart}
%
\def\indentedblockstart{%
{\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
\parindent=0pt
%
% @cartouche defines \nonarrowing to inhibit narrowing at next level down.
\ifx\nonarrowing\relax
\advance\leftskip by \lispnarrowing
\exdentamount = \lispnarrowing
\else
\let\nonarrowing = \relax
\fi
}
% Keep a nonzero parskip for the environment, since we're doing normal filling.
%
\def\Eindentedblock{%
\par
{\parskip=0pt \afterenvbreak}%
}
\def\Esmallindentedblock{\Eindentedblock}
% LaTeX-like @verbatim...@end verbatim and @verb{...}
% If we want to allow any as delimiter,
% we need the curly braces so that makeinfo sees the @verb command, eg:
% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org
%
% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook.
%
% [Knuth] p.344; only we need to do the other characters Texinfo sets
% active too. Otherwise, they get lost as the first character on a
% verbatim line.
\def\dospecials{%
\do\ \do\\\do\{\do\}\do\$\do\&%
\do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~%
\do\<\do\>\do\|\do\@\do+\do\"%
% Don't do the quotes -- if we do, @set txicodequoteundirected and
% @set txicodequotebacktick will not have effect on @verb and
% @verbatim, and ?` and !` ligatures won't get disabled.
%\do\`\do\'%
}
%
% [Knuth] p. 380
\def\uncatcodespecials{%
\def\do##1{\catcode`##1=\other}\dospecials}
%
% Setup for the @verb command.
%
% Eight spaces for a tab
\begingroup
\catcode`\^^I=\active
\gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }}
\endgroup
%
\def\setupverb{%
\tt % easiest (and conventionally used) font for verbatim
\def\par{\leavevmode\endgraf}%
\setupmarkupstyle{verb}%
\tabeightspaces
% Respect line breaks,
% print special symbols as themselves, and
% make each space count
% must do in this order:
\obeylines \uncatcodespecials \sepspaces
}
% Setup for the @verbatim environment
%
% Real tab expansion.
\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
%
% We typeset each line of the verbatim in an \hbox, so we can handle
% tabs. The \global is in case the verbatim line starts with an accent,
% or some other command that starts with a begin-group. Otherwise, the
% entire \verbbox would disappear at the corresponding end-group, before
% it is typeset. Meanwhile, we can't have nested verbatim commands
% (can we?), so the \global won't be overwriting itself.
\newbox\verbbox
\def\starttabbox{\global\setbox\verbbox=\hbox\bgroup}
%
\begingroup
\catcode`\^^I=\active
\gdef\tabexpand{%
\catcode`\^^I=\active
\def^^I{\leavevmode\egroup
\dimen\verbbox=\wd\verbbox % the width so far, or since the previous tab
\divide\dimen\verbbox by\tabw
\multiply\dimen\verbbox by\tabw % compute previous multiple of \tabw
\advance\dimen\verbbox by\tabw % advance to next multiple of \tabw
\wd\verbbox=\dimen\verbbox \box\verbbox \starttabbox
}%
}
\endgroup
% start the verbatim environment.
\def\setupverbatim{%
\let\nonarrowing = t%
\nonfillstart
\tt % easiest (and conventionally used) font for verbatim
% The \leavevmode here is for blank lines. Otherwise, we would
% never \starttabox and the \egroup would end verbatim mode.
\def\par{\leavevmode\egroup\box\verbbox\endgraf}%
\tabexpand
\setupmarkupstyle{verbatim}%
% Respect line breaks,
% print special symbols as themselves, and
% make each space count.
% Must do in this order:
\obeylines \uncatcodespecials \sepspaces
\everypar{\starttabbox}%
}
% Do the @verb magic: verbatim text is quoted by unique
% delimiter characters. Before first delimiter expect a
% right brace, after last delimiter expect closing brace:
%
% \def\doverb'{'#1'}'{#1}
%
% [Knuth] p. 382; only eat outer {}
\begingroup
\catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other
\gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next]
\endgroup
%
\def\verb{\begingroup\setupverb\doverb}
%
%
% Do the @verbatim magic: define the macro \doverbatim so that
% the (first) argument ends when '@end verbatim' is reached, ie:
%
% \def\doverbatim#1@end verbatim{#1}
%
% For Texinfo it's a lot easier than for LaTeX,
% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
% we need not redefine '\', '{' and '}'.
%
% Inspired by LaTeX's verbatim command set [latex.ltx]
%
\begingroup
\catcode`\ =\active
\obeylines %
% ignore everything up to the first ^^M, that's the newline at the end
% of the @verbatim input line itself. Otherwise we get an extra blank
% line in the output.
\xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}%
% We really want {...\end verbatim} in the body of the macro, but
% without the active space; thus we have to use \xdef and \gobble.
\endgroup
%
\envdef\verbatim{%
\setupverbatim\doverbatim
}
\let\Everbatim = \afterenvbreak
% @verbatiminclude FILE - insert text of file in verbatim environment.
%
\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude}
%
\def\doverbatiminclude#1{%
{%
\makevalueexpandable
\setupverbatim
\indexnofonts % Allow `@@' and other weird things in file names.
\wlog{texinfo.tex: doing @verbatiminclude of #1^^J}%
\input #1
\afterenvbreak
}%
}
% @copying ... @end copying.
% Save the text away for @insertcopying later.
%
% We save the uninterpreted tokens, rather than creating a box.
% Saving the text in a box would be much easier, but then all the
% typesetting commands (@smallbook, font changes, etc.) have to be done
% beforehand -- and a) we want @copying to be done first in the source
% file; b) letting users define the frontmatter in as flexible order as
% possible is very desirable.
%
\def\copying{\checkenv{}\begingroup\scanargctxt\docopying}
\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}}
%
\def\insertcopying{%
\begingroup
\parindent = 0pt % paragraph indentation looks wrong on title page
\scanexp\copyingtext
\endgroup
}
\message{defuns,}
% @defun etc.
\newskip\defbodyindent \defbodyindent=.4in
\newskip\defargsindent \defargsindent=50pt
\newskip\deflastargmargin \deflastargmargin=18pt
\newcount\defunpenalty
% Start the processing of @deffn:
\def\startdefun{%
\ifnum\lastpenalty<10000
\medbreak
\defunpenalty=10003 % Will keep this @deffn together with the
% following @def command, see below.
\else
% If there are two @def commands in a row, we'll have a \nobreak,
% which is there to keep the function description together with its
% header. But if there's nothing but headers, we need to allow a
% break somewhere. Check specifically for penalty 10002, inserted
% by \printdefunline, instead of 10000, since the sectioning
% commands also insert a nobreak penalty, and we don't want to allow
% a break between a section heading and a defun.
%
% As a further refinement, we avoid "club" headers by signalling
% with penalty of 10003 after the very first @deffn in the
% sequence (see above), and penalty of 10002 after any following
% @def command.
\ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi
%
% Similarly, after a section heading, do not allow a break.
% But do insert the glue.
\medskip % preceded by discardable penalty, so not a breakpoint
\fi
%
\parindent=0in
\advance\leftskip by \defbodyindent
\exdentamount=\defbodyindent
}
\def\dodefunx#1{%
% First, check whether we are in the right environment:
\checkenv#1%
%
% As above, allow line break if we have multiple x headers in a row.
% It's not a great place, though.
\ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi
%
% And now, it's time to reuse the body of the original defun:
\expandafter\gobbledefun#1%
}
\def\gobbledefun#1\startdefun{}
% \printdefunline \deffnheader{text}
%
\def\printdefunline#1#2{%
\begingroup
% call \deffnheader:
#1#2 \endheader
% common ending:
\interlinepenalty = 10000
\advance\rightskip by 0pt plus 1fil\relax
\endgraf
\nobreak\vskip -\parskip
\penalty\defunpenalty % signal to \startdefun and \dodefunx
% Some of the @defun-type tags do not enable magic parentheses,
% rendering the following check redundant. But we don't optimize.
\checkparencounts
\endgroup
}
\def\Edefun{\endgraf\medbreak}
% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn;
% the only thing remaining is to define \deffnheader.
%
\def\makedefun#1{%
\expandafter\let\csname E#1\endcsname = \Edefun
\edef\temp{\noexpand\domakedefun
\makecsname{#1}\makecsname{#1x}\makecsname{#1header}}%
\temp
}
% \domakedefun \deffn \deffnx \deffnheader
%
% Define \deffn and \deffnx, without parameters.
% \deffnheader has to be defined explicitly.
%
\def\domakedefun#1#2#3{%
\envdef#1{%
\startdefun
\doingtypefnfalse % distinguish typed functions from all else
\parseargusing\activeparens{\printdefunline#3}%
}%
\def#2{\dodefunx#1}%
\def#3%
}
\newif\ifdoingtypefn % doing typed function?
\newif\ifrettypeownline % typeset return type on its own line?
% @deftypefnnewline on|off says whether the return type of typed functions
% are printed on their own line. This affects @deftypefn, @deftypefun,
% @deftypeop, and @deftypemethod.
%
\parseargdef\deftypefnnewline{%
\def\temp{#1}%
\ifx\temp\onword
\expandafter\let\csname SETtxideftypefnnl\endcsname
= \empty
\else\ifx\temp\offword
\expandafter\let\csname SETtxideftypefnnl\endcsname
= \relax
\else
\errhelp = \EMsimple
\errmessage{Unknown @txideftypefnnl value `\temp',
must be on|off}%
\fi\fi
}
% Untyped functions:
% @deffn category name args
\makedefun{deffn}{\deffngeneral{}}
% @deffn category class name args
\makedefun{defop}#1 {\defopon{#1\ \putwordon}}
% \defopon {category on}class name args
\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
% \deffngeneral {subind}category name args
%
\def\deffngeneral#1#2 #3 #4\endheader{%
% Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}.
\dosubind{fn}{\code{#3}}{#1}%
\defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}%
}
% Typed functions:
% @deftypefn category type name args
\makedefun{deftypefn}{\deftypefngeneral{}}
% @deftypeop category class type name args
\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}}
% \deftypeopon {category on}class type name args
\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
% \deftypefngeneral {subind}category type name args
%
\def\deftypefngeneral#1#2 #3 #4 #5\endheader{%
\dosubind{fn}{\code{#4}}{#1}%
\doingtypefntrue
\defname{#2}{#3}{#4}\defunargs{#5\unskip}%
}
% Typed variables:
% @deftypevr category type var args
\makedefun{deftypevr}{\deftypecvgeneral{}}
% @deftypecv category class type var args
\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}}
% \deftypecvof {category of}class type var args
\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} }
% \deftypecvgeneral {subind}category type var args
%
\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{%
\dosubind{vr}{\code{#4}}{#1}%
\defname{#2}{#3}{#4}\defunargs{#5\unskip}%
}
% Untyped variables:
% @defvr category var args
\makedefun{defvr}#1 {\deftypevrheader{#1} {} }
% @defcv category class var args
\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}}
% \defcvof {category of}class var args
\def\defcvof#1#2 {\deftypecvof{#1}#2 {} }
% Types:
% @deftp category name args
\makedefun{deftp}#1 #2 #3\endheader{%
\doind{tp}{\code{#2}}%
\defname{#1}{}{#2}\defunargs{#3\unskip}%
}
% Remaining @defun-like shortcuts:
\makedefun{defun}{\deffnheader{\putwordDeffunc} }
\makedefun{defmac}{\deffnheader{\putwordDefmac} }
\makedefun{defspec}{\deffnheader{\putwordDefspec} }
\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} }
\makedefun{defvar}{\defvrheader{\putwordDefvar} }
\makedefun{defopt}{\defvrheader{\putwordDefopt} }
\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} }
\makedefun{defmethod}{\defopon\putwordMethodon}
\makedefun{deftypemethod}{\deftypeopon\putwordMethodon}
\makedefun{defivar}{\defcvof\putwordInstanceVariableof}
\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof}
% \defname, which formats the name of the @def (not the args).
% #1 is the category, such as "Function".
% #2 is the return type, if any.
% #3 is the function name.
%
% We are followed by (but not passed) the arguments, if any.
%
\def\defname#1#2#3{%
\par
% Get the values of \leftskip and \rightskip as they were outside the @def...
\advance\leftskip by -\defbodyindent
%
% Determine if we are typesetting the return type of a typed function
% on a line by itself.
\rettypeownlinefalse
\ifdoingtypefn % doing a typed function specifically?
% then check user option for putting return type on its own line:
\expandafter\ifx\csname SETtxideftypefnnl\endcsname\relax \else
\rettypeownlinetrue
\fi
\fi
%
% How we'll format the category name. Putting it in brackets helps
% distinguish it from the body text that may end up on the next line
% just below it.
\def\temp{#1}%
\setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi}
%
% Figure out line sizes for the paragraph shape. We'll always have at
% least two.
\tempnum = 2
%
% The first line needs space for \box0; but if \rightskip is nonzero,
% we need only space for the part of \box0 which exceeds it:
\dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip
%
% If doing a return type on its own line, we'll have another line.
\ifrettypeownline
\advance\tempnum by 1
\def\maybeshapeline{0in \hsize}%
\else
\def\maybeshapeline{}%
\fi
%
% The continuations:
\dimen2=\hsize \advance\dimen2 by -\defargsindent
%
% The final paragraph shape:
\parshape \tempnum 0in \dimen0 \maybeshapeline \defargsindent \dimen2
%
% Put the category name at the right margin.
\noindent
\hbox to 0pt{%
\hfil\box0 \kern-\hsize
% \hsize has to be shortened this way:
\kern\leftskip
% Intentionally do not respect \rightskip, since we need the space.
}%
%
% Allow all lines to be underfull without complaint:
\tolerance=10000 \hbadness=10000
\exdentamount=\defbodyindent
{%
% defun fonts. We use typewriter by default (used to be bold) because:
% . we're printing identifiers, they should be in tt in principle.
% . in languages with many accents, such as Czech or French, it's
% common to leave accents off identifiers. The result looks ok in
% tt, but exceedingly strange in rm.
% . we don't want -- and --- to be treated as ligatures.
% . this still does not fix the ?` and !` ligatures, but so far no
% one has made identifiers using them :).
\df \tt
\def\temp{#2}% text of the return type
\ifx\temp\empty\else
\tclose{\temp}% typeset the return type
\ifrettypeownline
% put return type on its own line; prohibit line break following:
\hfil\vadjust{\nobreak}\break
\else
\space % type on same line, so just followed by a space
\fi
\fi % no return type
#3% output function name
}%
{\rm\enskip}% hskip 0.5 em of \tenrm
%
\boldbrax
% arguments will be output next, if any.
}
% Print arguments in slanted roman (not ttsl), inconsistently with using
% tt for the name. This is because literal text is sometimes needed in
% the argument list (groff manual), and ttsl and tt are not very
% distinguishable. Prevent hyphenation at `-' chars.
%
\def\defunargs#1{%
% use sl by default (not ttsl),
% tt for the names.
\df \sl \hyphenchar\font=0
%
% On the other hand, if an argument has two dashes (for instance), we
% want a way to get ttsl. We used to recommend @var for that, so
% leave the code in, but it's strange for @var to lead to typewriter.
% Nowadays we recommend @code, since the difference between a ttsl hyphen
% and a tt hyphen is pretty tiny. @code also disables ?` !`.
\def\var##1{{\setupmarkupstyle{var}\ttslanted{##1}}}%
#1%
\sl\hyphenchar\font=45
}
% We want ()&[] to print specially on the defun line.
%
\def\activeparens{%
\catcode`\(=\active \catcode`\)=\active
\catcode`\[=\active \catcode`\]=\active
\catcode`\&=\active
}
% Make control sequences which act like normal parenthesis chars.
\let\lparen = ( \let\rparen = )
% Be sure that we always have a definition for `(', etc. For example,
% if the fn name has parens in it, \boldbrax will not be in effect yet,
% so TeX would otherwise complain about undefined control sequence.
{
\activeparens
\global\let(=\lparen \global\let)=\rparen
\global\let[=\lbrack \global\let]=\rbrack
\global\let& = \&
\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}
\gdef\magicamp{\let&=\amprm}
}
\newcount\parencount
% If we encounter &foo, then turn on ()-hacking afterwards
\newif\ifampseen
\def\amprm#1 {\ampseentrue{\bf\ }}
\def\parenfont{%
\ifampseen
% At the first level, print parens in roman,
% otherwise use the default font.
\ifnum \parencount=1 \rm \fi
\else
% The \sf parens (in \boldbrax) actually are a little bolder than
% the contained text. This is especially needed for [ and ] .
\sf
\fi
}
\def\infirstlevel#1{%
\ifampseen
\ifnum\parencount=1
#1%
\fi
\fi
}
\def\bfafterword#1 {#1 \bf}
\def\opnr{%
\global\advance\parencount by 1
{\parenfont(}%
\infirstlevel \bfafterword
}
\def\clnr{%
{\parenfont)}%
\infirstlevel \sl
\global\advance\parencount by -1
}
\newcount\brackcount
\def\lbrb{%
\global\advance\brackcount by 1
{\bf[}%
}
\def\rbrb{%
{\bf]}%
\global\advance\brackcount by -1
}
\def\checkparencounts{%
\ifnum\parencount=0 \else \badparencount \fi
\ifnum\brackcount=0 \else \badbrackcount \fi
}
% these should not use \errmessage; the glibc manual, at least, actually
% has such constructs (when documenting function pointers).
\def\badparencount{%
\message{Warning: unbalanced parentheses in @def...}%
\global\parencount=0
}
\def\badbrackcount{%
\message{Warning: unbalanced square brackets in @def...}%
\global\brackcount=0
}
\message{macros,}
% @macro.
% To do this right we need a feature of e-TeX, \scantokens,
% which we arrange to emulate with a temporary file in ordinary TeX.
\ifx\eTeXversion\thisisundefined
\newwrite\macscribble
\def\scantokens#1{%
\toks0={#1}%
\immediate\openout\macscribble=\jobname.tmp
\immediate\write\macscribble{\the\toks0}%
\immediate\closeout\macscribble
\input \jobname.tmp
}
\fi
\def\scanmacro#1{\begingroup
\newlinechar`\^^M
\let\xeatspaces\eatspaces
%
% Undo catcode changes of \startcontents and \doprintindex
% When called from @insertcopying or (short)caption, we need active
% backslash to get it printed correctly. Previously, we had
% \catcode`\\=\other instead. We'll see whether a problem appears
% with macro expansion. --kasal, 19aug04
\catcode`\@=0 \catcode`\\=\active \escapechar=`\@
%
% ... and for \example:
\spaceisspace
%
% The \empty here causes a following catcode 5 newline to be eaten as
% part of reading whitespace after a control sequence. It does not
% eat a catcode 13 newline. There's no good way to handle the two
% cases (untried: maybe e-TeX's \everyeof could help, though plain TeX
% would then have different behavior). See the Macro Details node in
% the manual for the workaround we recommend for macros and
% line-oriented commands.
%
\scantokens{#1\empty}%
\endgroup}
\def\scanexp#1{%
\edef\temp{\noexpand\scanmacro{#1}}%
\temp
}
\newcount\paramno % Count of parameters
\newtoks\macname % Macro name
\newif\ifrecursive % Is it recursive?
% List of all defined macros in the form
% \definedummyword\macro1\definedummyword\macro2...
% Currently is also contains all @aliases; the list can be split
% if there is a need.
\def\macrolist{}
% Add the macro to \macrolist
\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname}
\def\addtomacrolistxxx#1{%
\toks0 = \expandafter{\macrolist\definedummyword#1}%
\xdef\macrolist{\the\toks0}%
}
% Utility routines.
% This does \let #1 = #2, with \csnames; that is,
% \let \csname#1\endcsname = \csname#2\endcsname
% (except of course we have to play expansion games).
%
\def\cslet#1#2{%
\expandafter\let
\csname#1\expandafter\endcsname
\csname#2\endcsname
}
% Trim leading and trailing spaces off a string.
% Concepts from aro-bend problem 15 (see CTAN).
{\catcode`\@=11
\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}
\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}
\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}
\def\unbrace#1{#1}
\unbrace{\gdef\trim@@@ #1 } #2@{#1}
}
% Trim a single trailing ^^M off a string.
{\catcode`\^^M=\other \catcode`\Q=3%
\gdef\eatcr #1{\eatcra #1Q^^MQ}%
\gdef\eatcra#1^^MQ{\eatcrb#1Q}%
\gdef\eatcrb#1Q#2Q{#1}%
}
% Macro bodies are absorbed as an argument in a context where
% all characters are catcode 10, 11 or 12, except \ which is active
% (as in normal texinfo). It is necessary to change the definition of \
% to recognize macro arguments; this is the job of \mbodybackslash.
%
% Non-ASCII encodings make 8-bit characters active, so un-activate
% them to avoid their expansion. Must do this non-globally, to
% confine the change to the current group.
%
% It's necessary to have hard CRs when the macro is executed. This is
% done by making ^^M (\endlinechar) catcode 12 when reading the macro
% body, and then making it the \newlinechar in \scanmacro.
%
\def\scanctxt{% used as subroutine
\catcode`\"=\other
\catcode`\+=\other
\catcode`\<=\other
\catcode`\>=\other
\catcode`\@=\other
\catcode`\^=\other
\catcode`\_=\other
\catcode`\|=\other
\catcode`\~=\other
\ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi
}
\def\scanargctxt{% used for copying and captions, not macros.
\scanctxt
\catcode`\\=\other
\catcode`\^^M=\other
}
\def\macrobodyctxt{% used for @macro definitions
\scanctxt
\catcode`\{=\other
\catcode`\}=\other
\catcode`\^^M=\other
\usembodybackslash
}
\def\macroargctxt{% used when scanning invocations
\scanctxt
\catcode`\\=0
}
% why catcode 0 for \ in the above? To recognize \\ \{ \} as "escapes"
% for the single characters \ { }. Thus, we end up with the "commands"
% that would be written @\ @{ @} in a Texinfo document.
%
% We already have @{ and @}. For @\, we define it here, and only for
% this purpose, to produce a typewriter backslash (so, the @\ that we
% define for @math can't be used with @macro calls):
%
\def\\{\normalbackslash}%
%
% We would like to do this for \, too, since that is what makeinfo does.
% But it is not possible, because Texinfo already has a command @, for a
% cedilla accent. Documents must use @comma{} instead.
%
% \anythingelse will almost certainly be an error of some kind.
% \mbodybackslash is the definition of \ in @macro bodies.
% It maps \foo\ => \csname macarg.foo\endcsname => #N
% where N is the macro parameter number.
% We define \csname macarg.\endcsname to be \realbackslash, so
% \\ in macro replacement text gets you a backslash.
%
{\catcode`@=0 @catcode`@\=@active
@gdef@usembodybackslash{@let\=@mbodybackslash}
@gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}
}
\expandafter\def\csname macarg.\endcsname{\realbackslash}
\def\margbackslash#1{\char`\#1 }
\def\macro{\recursivefalse\parsearg\macroxxx}
\def\rmacro{\recursivetrue\parsearg\macroxxx}
\def\macroxxx#1{%
\getargs{#1}% now \macname is the macname and \argl the arglist
\ifx\argl\empty % no arguments
\paramno=0\relax
\else
\expandafter\parsemargdef \argl;%
\if\paramno>256\relax
\ifx\eTeXversion\thisisundefined
\errhelp = \EMsimple
\errmessage{You need eTeX to compile a file with macros with more than 256 arguments}
\fi
\fi
\fi
\if1\csname ismacro.\the\macname\endcsname
\message{Warning: redefining \the\macname}%
\else
\expandafter\ifx\csname \the\macname\endcsname \relax
\else \errmessage{Macro name \the\macname\space already defined}\fi
\global\cslet{macsave.\the\macname}{\the\macname}%
\global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
\addtomacrolist{\the\macname}%
\fi
\begingroup \macrobodyctxt
\ifrecursive \expandafter\parsermacbody
\else \expandafter\parsemacbody
\fi}
\parseargdef\unmacro{%
\if1\csname ismacro.#1\endcsname
\global\cslet{#1}{macsave.#1}%
\global\expandafter\let \csname ismacro.#1\endcsname=0%
% Remove the macro name from \macrolist:
\begingroup
\expandafter\let\csname#1\endcsname \relax
\let\definedummyword\unmacrodo
\xdef\macrolist{\macrolist}%
\endgroup
\else
\errmessage{Macro #1 not defined}%
\fi
}
% Called by \do from \dounmacro on each macro. The idea is to omit any
% macro definitions that have been changed to \relax.
%
\def\unmacrodo#1{%
\ifx #1\relax
% remove this
\else
\noexpand\definedummyword \noexpand#1%
\fi
}
% This makes use of the obscure feature that if the last token of a
% is #, then the preceding argument is delimited by
% an opening brace, and that opening brace is not consumed.
\def\getargs#1{\getargsxxx#1{}}
\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
\def\getmacname#1 #2\relax{\macname={#1}}
\def\getmacargs#1{\def\argl{#1}}
% For macro processing make @ a letter so that we can make Texinfo private macro names.
\edef\texiatcatcode{\the\catcode`\@}
\catcode `@=11\relax
% Parse the optional {params} list. Set up \paramno and \paramlist
% so \defmacro knows what to do. Define \macarg.BLAH for each BLAH
% in the params list to some hook where the argument si to be expanded. If
% there are less than 10 arguments that hook is to be replaced by ##N where N
% is the position in that list, that is to say the macro arguments are to be
% defined `a la TeX in the macro body.
%
% That gets used by \mbodybackslash (above).
%
% We need to get `macro parameter char #' into several definitions.
% The technique used is stolen from LaTeX: let \hash be something
% unexpandable, insert that wherever you need a #, and then redefine
% it to # just before using the token list produced.
%
% The same technique is used to protect \eatspaces till just before
% the macro is used.
%
% If there are 10 or more arguments, a different technique is used, where the
% hook remains in the body, and when macro is to be expanded the body is
% processed again to replace the arguments.
%
% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the
% argument N value and then \edef the body (nothing else will expand because of
% the catcode regime underwhich the body was input).
%
% If you compile with TeX (not eTeX), and you have macros with 10 or more
% arguments, you need that no macro has more than 256 arguments, otherwise an
% error is produced.
\def\parsemargdef#1;{%
\paramno=0\def\paramlist{}%
\let\hash\relax
\let\xeatspaces\relax
\parsemargdefxxx#1,;,%
% In case that there are 10 or more arguments we parse again the arguments
% list to set new definitions for the \macarg.BLAH macros corresponding to
% each BLAH argument. It was anyhow needed to parse already once this list
% in order to count the arguments, and as macros with at most 9 arguments
% are by far more frequent than macro with 10 or more arguments, defining
% twice the \macarg.BLAH macros does not cost too much processing power.
\ifnum\paramno<10\relax\else
\paramno0\relax
\parsemmanyargdef@@#1,;,% 10 or more arguments
\fi
}
\def\parsemargdefxxx#1,{%
\if#1;\let\next=\relax
\else \let\next=\parsemargdefxxx
\advance\paramno by 1
\expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
{\xeatspaces{\hash\the\paramno}}%
\edef\paramlist{\paramlist\hash\the\paramno,}%
\fi\next}
\def\parsemmanyargdef@@#1,{%
\if#1;\let\next=\relax
\else
\let\next=\parsemmanyargdef@@
\edef\tempb{\eatspaces{#1}}%
\expandafter\def\expandafter\tempa
\expandafter{\csname macarg.\tempb\endcsname}%
% Note that we need some extra \noexpand\noexpand, this is because we
% don't want \the to be expanded in the \parsermacbody as it uses an
% \xdef .
\expandafter\edef\tempa
{\noexpand\noexpand\noexpand\the\toks\the\paramno}%
\advance\paramno by 1\relax
\fi\next}
% These two commands read recursive and nonrecursive macro bodies.
% (They're different since rec and nonrec macros end differently.)
%
\catcode `\@\texiatcatcode
\long\def\parsemacbody#1@end macro%
{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
\long\def\parsermacbody#1@end rmacro%
{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
\catcode `\@=11\relax
\let\endargs@\relax
\let\nil@\relax
\def\nilm@{\nil@}%
\long\def\nillm@{\nil@}%
% This macro is expanded during the Texinfo macro expansion, not during its
% definition. It gets all the arguments values and assigns them to macros
% macarg.ARGNAME
%
% #1 is the macro name
% #2 is the list of argument names
% #3 is the list of argument values
\def\getargvals@#1#2#3{%
\def\macargdeflist@{}%
\def\saveparamlist@{#2}% Need to keep a copy for parameter expansion.
\def\paramlist{#2,\nil@}%
\def\macroname{#1}%
\begingroup
\macroargctxt
\def\argvaluelist{#3,\nil@}%
\def\@tempa{#3}%
\ifx\@tempa\empty
\setemptyargvalues@
\else
\getargvals@@
\fi
}
%
\def\getargvals@@{%
\ifx\paramlist\nilm@
% Some sanity check needed here that \argvaluelist is also empty.
\ifx\argvaluelist\nillm@
\else
\errhelp = \EMsimple
\errmessage{Too many arguments in macro `\macroname'!}%
\fi
\let\next\macargexpandinbody@
\else
\ifx\argvaluelist\nillm@
% No more arguments values passed to macro. Set remaining named-arg
% macros to empty.
\let\next\setemptyargvalues@
\else
% pop current arg name into \@tempb
\def\@tempa##1{\pop@{\@tempb}{\paramlist}##1\endargs@}%
\expandafter\@tempa\expandafter{\paramlist}%
% pop current argument value into \@tempc
\def\@tempa##1{\longpop@{\@tempc}{\argvaluelist}##1\endargs@}%
\expandafter\@tempa\expandafter{\argvaluelist}%
% Here \@tempb is the current arg name and \@tempc is the current arg value.
% First place the new argument macro definition into \@tempd
\expandafter\macname\expandafter{\@tempc}%
\expandafter\let\csname macarg.\@tempb\endcsname\relax
\expandafter\def\expandafter\@tempe\expandafter{%
\csname macarg.\@tempb\endcsname}%
\edef\@tempd{\long\def\@tempe{\the\macname}}%
\push@\@tempd\macargdeflist@
\let\next\getargvals@@
\fi
\fi
\next
}
\def\push@#1#2{%
\expandafter\expandafter\expandafter\def
\expandafter\expandafter\expandafter#2%
\expandafter\expandafter\expandafter{%
\expandafter#1#2}%
}
% Replace arguments by their values in the macro body, and place the result
% in macro \@tempa
\def\macvalstoargs@{%
% To do this we use the property that token registers that are \the'ed
% within an \edef expand only once. So we are going to place all argument
% values into respective token registers.
%
% First we save the token context, and initialize argument numbering.
\begingroup
\paramno0\relax
% Then, for each argument number #N, we place the corresponding argument
% value into a new token list register \toks#N
\expandafter\putargsintokens@\saveparamlist@,;,%
% Then, we expand the body so that argument are replaced by their
% values. The trick for values not to be expanded themselves is that they
% are within tokens and that tokens expand only once in an \edef .
\edef\@tempc{\csname mac.\macroname .body\endcsname}%
% Now we restore the token stack pointer to free the token list registers
% which we have used, but we make sure that expanded body is saved after
% group.
\expandafter
\endgroup
\expandafter\def\expandafter\@tempa\expandafter{\@tempc}%
}
\def\macargexpandinbody@{%
%% Define the named-macro outside of this group and then close this group.
\expandafter
\endgroup
\macargdeflist@
% First the replace in body the macro arguments by their values, the result
% is in \@tempa .
\macvalstoargs@
% Then we point at the \norecurse or \gobble (for recursive) macro value
% with \@tempb .
\expandafter\let\expandafter\@tempb\csname mac.\macroname .recurse\endcsname
% Depending on whether it is recursive or not, we need some tailing
% \egroup .
\ifx\@tempb\gobble
\let\@tempc\relax
\else
\let\@tempc\egroup
\fi
% And now we do the real job:
\edef\@tempd{\noexpand\@tempb{\macroname}\noexpand\scanmacro{\@tempa}\@tempc}%
\@tempd
}
\def\putargsintokens@#1,{%
\if#1;\let\next\relax
\else
\let\next\putargsintokens@
% First we allocate the new token list register, and give it a temporary
% alias \@tempb .
\toksdef\@tempb\the\paramno
% Then we place the argument value into that token list register.
\expandafter\let\expandafter\@tempa\csname macarg.#1\endcsname
\expandafter\@tempb\expandafter{\@tempa}%
\advance\paramno by 1\relax
\fi
\next
}
% Save the token stack pointer into macro #1
\def\texisavetoksstackpoint#1{\edef#1{\the\@cclvi}}
% Restore the token stack pointer from number in macro #1
\def\texirestoretoksstackpoint#1{\expandafter\mathchardef\expandafter\@cclvi#1\relax}
% newtoks that can be used non \outer .
\def\texinonouternewtoks{\alloc@ 5\toks \toksdef \@cclvi}
% Tailing missing arguments are set to empty
\def\setemptyargvalues@{%
\ifx\paramlist\nilm@
\let\next\macargexpandinbody@
\else
\expandafter\setemptyargvaluesparser@\paramlist\endargs@
\let\next\setemptyargvalues@
\fi
\next
}
\def\setemptyargvaluesparser@#1,#2\endargs@{%
\expandafter\def\expandafter\@tempa\expandafter{%
\expandafter\def\csname macarg.#1\endcsname{}}%
\push@\@tempa\macargdeflist@
\def\paramlist{#2}%
}
% #1 is the element target macro
% #2 is the list macro
% #3,#4\endargs@ is the list value
\def\pop@#1#2#3,#4\endargs@{%
\def#1{#3}%
\def#2{#4}%
}
\long\def\longpop@#1#2#3,#4\endargs@{%
\long\def#1{#3}%
\long\def#2{#4}%
}
% This defines a Texinfo @macro. There are eight cases: recursive and
% nonrecursive macros of zero, one, up to nine, and many arguments.
% Much magic with \expandafter here.
% \xdef is used so that macro definitions will survive the file
% they're defined in; @include reads the file inside a group.
%
\def\defmacro{%
\let\hash=##% convert placeholders to macro parameter chars
\ifrecursive
\ifcase\paramno
% 0
\expandafter\xdef\csname\the\macname\endcsname{%
\noexpand\scanmacro{\temp}}%
\or % 1
\expandafter\xdef\csname\the\macname\endcsname{%
\bgroup\noexpand\macroargctxt
\noexpand\braceorline
\expandafter\noexpand\csname\the\macname xxx\endcsname}%
\expandafter\xdef\csname\the\macname xxx\endcsname##1{%
\egroup\noexpand\scanmacro{\temp}}%
\else
\ifnum\paramno<10\relax % at most 9
\expandafter\xdef\csname\the\macname\endcsname{%
\bgroup\noexpand\macroargctxt
\noexpand\csname\the\macname xx\endcsname}%
\expandafter\xdef\csname\the\macname xx\endcsname##1{%
\expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
\expandafter\expandafter
\expandafter\xdef
\expandafter\expandafter
\csname\the\macname xxx\endcsname
\paramlist{\egroup\noexpand\scanmacro{\temp}}%
\else % 10 or more
\expandafter\xdef\csname\the\macname\endcsname{%
\noexpand\getargvals@{\the\macname}{\argl}%
}%
\global\expandafter\let\csname mac.\the\macname .body\endcsname\temp
\global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble
\fi
\fi
\else
\ifcase\paramno
% 0
\expandafter\xdef\csname\the\macname\endcsname{%
\noexpand\norecurse{\the\macname}%
\noexpand\scanmacro{\temp}\egroup}%
\or % 1
\expandafter\xdef\csname\the\macname\endcsname{%
\bgroup\noexpand\macroargctxt
\noexpand\braceorline
\expandafter\noexpand\csname\the\macname xxx\endcsname}%
\expandafter\xdef\csname\the\macname xxx\endcsname##1{%
\egroup
\noexpand\norecurse{\the\macname}%
\noexpand\scanmacro{\temp}\egroup}%
\else % at most 9
\ifnum\paramno<10\relax
\expandafter\xdef\csname\the\macname\endcsname{%
\bgroup\noexpand\macroargctxt
\expandafter\noexpand\csname\the\macname xx\endcsname}%
\expandafter\xdef\csname\the\macname xx\endcsname##1{%
\expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
\expandafter\expandafter
\expandafter\xdef
\expandafter\expandafter
\csname\the\macname xxx\endcsname
\paramlist{%
\egroup
\noexpand\norecurse{\the\macname}%
\noexpand\scanmacro{\temp}\egroup}%
\else % 10 or more:
\expandafter\xdef\csname\the\macname\endcsname{%
\noexpand\getargvals@{\the\macname}{\argl}%
}%
\global\expandafter\let\csname mac.\the\macname .body\endcsname\temp
\global\expandafter\let\csname mac.\the\macname .recurse\endcsname\norecurse
\fi
\fi
\fi}
\catcode `\@\texiatcatcode\relax
\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
% \braceorline decides whether the next nonwhitespace character is a
% {. If so it reads up to the closing }, if not, it reads the whole
% line. Whatever was read is then fed to the next control sequence
% as an argument (by \parsebrace or \parsearg).
%
\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx}
\def\braceorlinexxx{%
\ifx\nchar\bgroup\else
\expandafter\parsearg
\fi \macnamexxx}
% @alias.
% We need some trickery to remove the optional spaces around the equal
% sign. Make them active and then expand them all to nothing.
%
\def\alias{\parseargusing\obeyspaces\aliasxxx}
\def\aliasxxx #1{\aliasyyy#1\relax}
\def\aliasyyy #1=#2\relax{%
{%
\expandafter\let\obeyedspace=\empty
\addtomacrolist{#1}%
\xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}%
}%
\next
}
\message{cross references,}
\newwrite\auxfile
\newif\ifhavexrefs % True if xref values are known.
\newif\ifwarnedxrefs % True if we warned once that they aren't known.
% @inforef is relatively simple.
\def\inforef #1{\inforefzzz #1,,,,**}
\def\inforefzzz #1,#2,#3,#4**{%
\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},
node \samp{\ignorespaces#1{}}}
% @node's only job in TeX is to define \lastnode, which is used in
% cross-references. The @node line might or might not have commas, and
% might or might not have spaces before the first comma, like:
% @node foo , bar , ...
% We don't want such trailing spaces in the node name.
%
\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse}
%
% also remove a trailing comma, in case of something like this:
% @node Help-Cross, , , Cross-refs
\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse}
\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}}
\let\nwnode=\node
\let\lastnode=\empty
% Write a cross-reference definition for the current node. #1 is the
% type (Ynumbered, Yappendix, Ynothing).
%
\def\donoderef#1{%
\ifx\lastnode\empty\else
\setref{\lastnode}{#1}%
\global\let\lastnode=\empty
\fi
}
% @anchor{NAME} -- define xref target at arbitrary point.
%
\newcount\savesfregister
%
\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}
\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}
\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}
% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an
% anchor), which consists of three parts:
% 1) NAME-title - the current sectioning name taken from \lastsection,
% or the anchor name.
% 2) NAME-snt - section number and type, passed as the SNT arg, or
% empty for anchors.
% 3) NAME-pg - the page number.
%
% This is called from \donoderef, \anchor, and \dofloat. In the case of
% floats, there is an additional part, which is not written here:
% 4) NAME-lof - the text as it should appear in a @listoffloats.
%
\def\setref#1#2{%
\pdfmkdest{#1}%
\iflinks
{%
\atdummies % preserve commands, but don't expand them
\edef\writexrdef##1##2{%
\write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef
##1}{##2}}% these are parameters of \writexrdef
}%
\toks0 = \expandafter{\lastsection}%
\immediate \writexrdef{title}{\the\toks0 }%
\immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc.
\safewhatsit{\writexrdef{pg}{\folio}}% will be written later, at \shipout
}%
\fi
}
% @xrefautosectiontitle on|off says whether @section(ing) names are used
% automatically in xrefs, if the third arg is not explicitly specified.
% This was provided as a "secret" @set xref-automatic-section-title
% variable, now it's official.
%
\parseargdef\xrefautomaticsectiontitle{%
\def\temp{#1}%
\ifx\temp\onword
\expandafter\let\csname SETxref-automatic-section-title\endcsname
= \empty
\else\ifx\temp\offword
\expandafter\let\csname SETxref-automatic-section-title\endcsname
= \relax
\else
\errhelp = \EMsimple
\errmessage{Unknown @xrefautomaticsectiontitle value `\temp',
must be on|off}%
\fi\fi
}
%
% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is
% the node name, #2 the name of the Info cross-reference, #3 the printed
% node name, #4 the name of the Info file, #5 the name of the printed
% manual. All but the node name can be omitted.
%
\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]}
\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}
\def\ref#1{\xrefX[#1,,,,,,,]}
%
\newbox\toprefbox
\newbox\printedrefnamebox
\newbox\infofilenamebox
\newbox\printedmanualbox
%
\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
\unsepspaces
%
% Get args without leading/trailing spaces.
\def\printedrefname{\ignorespaces #3}%
\setbox\printedrefnamebox = \hbox{\printedrefname\unskip}%
%
\def\infofilename{\ignorespaces #4}%
\setbox\infofilenamebox = \hbox{\infofilename\unskip}%
%
\def\printedmanual{\ignorespaces #5}%
\setbox\printedmanualbox = \hbox{\printedmanual\unskip}%
%
% If the printed reference name (arg #3) was not explicitly given in
% the @xref, figure out what we want to use.
\ifdim \wd\printedrefnamebox = 0pt
% No printed node name was explicitly given.
\expandafter\ifx\csname SETxref-automatic-section-title\endcsname \relax
% Not auto section-title: use node name inside the square brackets.
\def\printedrefname{\ignorespaces #1}%
\else
% Auto section-title: use chapter/section title inside
% the square brackets if we have it.
\ifdim \wd\printedmanualbox > 0pt
% It is in another manual, so we don't have it; use node name.
\def\printedrefname{\ignorespaces #1}%
\else
\ifhavexrefs
% We (should) know the real title if we have the xref values.
\def\printedrefname{\refx{#1-title}{}}%
\else
% Otherwise just copy the Info node name.
\def\printedrefname{\ignorespaces #1}%
\fi%
\fi
\fi
\fi
%
% Make link in pdf output.
\ifpdf
{\indexnofonts
\turnoffactive
\makevalueexpandable
% This expands tokens, so do it after making catcode changes, so _
% etc. don't get their TeX definitions. This ignores all spaces in
% #4, including (wrongly) those in the middle of the filename.
\getfilename{#4}%
%
% This (wrongly) does not take account of leading or trailing
% spaces in #1, which should be ignored.
\edef\pdfxrefdest{#1}%
\ifx\pdfxrefdest\empty
\def\pdfxrefdest{Top}% no empty targets
\else
\txiescapepdf\pdfxrefdest % escape PDF special chars
\fi
%
\leavevmode
\startlink attr{/Border [0 0 0]}%
\ifnum\filenamelength>0
goto file{\the\filename.pdf} name{\pdfxrefdest}%
\else
goto name{\pdfmkpgn{\pdfxrefdest}}%
\fi
}%
\setcolor{\linkcolor}%
\fi
%
% Float references are printed completely differently: "Figure 1.2"
% instead of "[somenode], p.3". We distinguish them by the
% LABEL-title being set to a magic string.
{%
% Have to otherify everything special to allow the \csname to
% include an _ in the xref name, etc.
\indexnofonts
\turnoffactive
\expandafter\global\expandafter\let\expandafter\Xthisreftitle
\csname XR#1-title\endcsname
}%
\iffloat\Xthisreftitle
% If the user specified the print name (third arg) to the ref,
% print it instead of our usual "Figure 1.2".
\ifdim\wd\printedrefnamebox = 0pt
\refx{#1-snt}{}%
\else
\printedrefname
\fi
%
% If the user also gave the printed manual name (fifth arg), append
% "in MANUALNAME".
\ifdim \wd\printedmanualbox > 0pt
\space \putwordin{} \cite{\printedmanual}%
\fi
\else
% node/anchor (non-float) references.
%
% If we use \unhbox 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 \wd\printedmanualbox > 0pt
% Cross-manual reference with a printed manual name.
%
\crossmanualxref{\cite{\printedmanual\unskip}}%
%
\else\ifdim \wd\infofilenamebox > 0pt
% Cross-manual reference with only an info filename (arg 4), no
% printed manual name (arg 5). This is essentially the same as
% the case above; we output the filename, since we have nothing else.
%
\crossmanualxref{\code{\infofilename\unskip}}%
%
\else
% Reference within this manual.
%
% _ (for example) has to be the character _ for the purposes of the
% control sequence corresponding to the node, but it has to expand
% into the usual \leavevmode...\vrule stuff for purposes of
% printing. So we \turnoffactive for the \refx-snt, back on for the
% printing, back off for the \refx-pg.
{\turnoffactive
% Only output a following space if the -snt ref is nonempty; for
% @unnumbered and @anchor, it won't be.
\setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
\ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
}%
% output the `[mynode]' via the macro below so it can be overridden.
\xrefprintnodename\printedrefname
%
% But we always want a comma and a space:
,\space
%
% output the `page 3'.
\turnoffactive \putwordpage\tie\refx{#1-pg}{}%
\fi\fi
\fi
\endlink
\endgroup}
% Output a cross-manual xref to #1. Used just above (twice).
%
% Only include the text "Section ``foo'' in" if the foo is neither
% missing or Top. Thus, @xref{,,,foo,The Foo Manual} outputs simply
% "see The Foo Manual", the idea being to refer to the whole manual.
%
% But, this being TeX, we can't easily compare our node name against the
% string "Top" while ignoring the possible spaces before and after in
% the input. By adding the arbitrary 7sp below, we make it much less
% likely that a real node name would have the same width as "Top" (e.g.,
% in a monospaced font). Hopefully it will never happen in practice.
%
% For the same basic reason, we retypeset the "Top" at every
% reference, since the current font is indeterminate.
%
\def\crossmanualxref#1{%
\setbox\toprefbox = \hbox{Top\kern7sp}%
\setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}%
\ifdim \wd2 > 7sp % nonempty?
\ifdim \wd2 = \wd\toprefbox \else % same as Top?
\putwordSection{} ``\printedrefname'' \putwordin{}\space
\fi
\fi
#1%
}
% This macro is called from \xrefX for the `[nodename]' part of xref
% output. It's a separate macro only so it can be changed more easily,
% since square brackets don't work well in some documents. Particularly
% one that Bob is working on :).
%
\def\xrefprintnodename#1{[#1]}
% Things referred to by \setref.
%
\def\Ynothing{}
\def\Yomitfromtoc{}
\def\Ynumbered{%
\ifnum\secno=0
\putwordChapter@tie \the\chapno
\else \ifnum\subsecno=0
\putwordSection@tie \the\chapno.\the\secno
\else \ifnum\subsubsecno=0
\putwordSection@tie \the\chapno.\the\secno.\the\subsecno
\else
\putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno
\fi\fi\fi
}
\def\Yappendix{%
\ifnum\secno=0
\putwordAppendix@tie @char\the\appendixno{}%
\else \ifnum\subsecno=0
\putwordSection@tie @char\the\appendixno.\the\secno
\else \ifnum\subsubsecno=0
\putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno
\else
\putwordSection@tie
@char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno
\fi\fi\fi
}
% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.
% If its value is nonempty, SUFFIX is output afterward.
%
\def\refx#1#2{%
{%
\indexnofonts
\otherbackslash
\expandafter\global\expandafter\let\expandafter\thisrefX
\csname XR#1\endcsname
}%
\ifx\thisrefX\relax
% If not defined, say something at least.
\angleleft un\-de\-fined\angleright
\iflinks
\ifhavexrefs
{\toks0 = {#1}% avoid expansion of possibly-complex value
\message{\linenumber Undefined cross reference `\the\toks0'.}}%
\else
\ifwarnedxrefs\else
\global\warnedxrefstrue
\message{Cross reference values unknown; you must run TeX again.}%
\fi
\fi
\fi
\else
% It's defined, so just use it.
\thisrefX
\fi
#2% Output the suffix in any case.
}
% This is the macro invoked by entries in the aux file. Usually it's
% just a \def (we prepend XR to the control sequence name to avoid
% collisions). But if this is a float type, we have more work to do.
%
\def\xrdef#1#2{%
{% The node name might contain 8-bit characters, which in our current
% implementation are changed to commands like @'e. Don't let these
% mess up the control sequence name.
\indexnofonts
\turnoffactive
\xdef\safexrefname{#1}%
}%
%
\expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref
%
% Was that xref control sequence that we just defined for a float?
\expandafter\iffloat\csname XR\safexrefname\endcsname
% it was a float, and we have the (safe) float type in \iffloattype.
\expandafter\let\expandafter\floatlist
\csname floatlist\iffloattype\endcsname
%
% Is this the first time we've seen this float type?
\expandafter\ifx\floatlist\relax
\toks0 = {\do}% yes, so just \do
\else
% had it before, so preserve previous elements in list.
\toks0 = \expandafter{\floatlist\do}%
\fi
%
% Remember this xref in the control sequence \floatlistFLOATTYPE,
% for later use in \listoffloats.
\expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0
{\safexrefname}}%
\fi
}
% Read the last existing aux file, if any. No error if none exists.
%
\def\tryauxfile{%
\openin 1 \jobname.aux
\ifeof 1 \else
\readdatafile{aux}%
\global\havexrefstrue
\fi
\closein 1
}
\def\setupdatafile{%
\catcode`\^^@=\other
\catcode`\^^A=\other
\catcode`\^^B=\other
\catcode`\^^C=\other
\catcode`\^^D=\other
\catcode`\^^E=\other
\catcode`\^^F=\other
\catcode`\^^G=\other
\catcode`\^^H=\other
\catcode`\^^K=\other
\catcode`\^^L=\other
\catcode`\^^N=\other
\catcode`\^^P=\other
\catcode`\^^Q=\other
\catcode`\^^R=\other
\catcode`\^^S=\other
\catcode`\^^T=\other
\catcode`\^^U=\other
\catcode`\^^V=\other
\catcode`\^^W=\other
\catcode`\^^X=\other
\catcode`\^^Z=\other
\catcode`\^^[=\other
\catcode`\^^\=\other
\catcode`\^^]=\other
\catcode`\^^^=\other
\catcode`\^^_=\other
% It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc.
% in xref tags, i.e., node names. But since ^^e4 notation isn't
% supported in the main text, it doesn't seem desirable. Furthermore,
% that is not enough: for node names that actually contain a ^
% character, we would end up writing a line like this: 'xrdef {'hat
% b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first
% argument, and \hat is not an expandable control sequence. It could
% all be worked out, but why? Either we support ^^ or we don't.
%
% The other change necessary for this was to define \auxhat:
% \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter
% and then to call \auxhat in \setq.
%
\catcode`\^=\other
%
% Special characters. Should be turned off anyway, but...
\catcode`\~=\other
\catcode`\[=\other
\catcode`\]=\other
\catcode`\"=\other
\catcode`\_=\other
\catcode`\|=\other
\catcode`\<=\other
\catcode`\>=\other
\catcode`\$=\other
\catcode`\#=\other
\catcode`\&=\other
\catcode`\%=\other
\catcode`+=\other % avoid \+ for paranoia even though we've turned it off
%
% This is to support \ in node names and titles, since the \
% characters end up in a \csname. It's easier than
% leaving it active and making its active definition an actual \
% character. What I don't understand is why it works in the *value*
% of the xrdef. Seems like it should be a catcode12 \, and that
% should not typeset properly. But it works, so I'm moving on for
% now. --karl, 15jan04.
\catcode`\\=\other
%
% Make the characters 128-255 be printing characters.
{%
\count1=128
\def\loop{%
\catcode\count1=\other
\advance\count1 by 1
\ifnum \count1<256 \loop \fi
}%
}%
%
% @ is our escape character in .aux files, and we need braces.
\catcode`\{=1
\catcode`\}=2
\catcode`\@=0
}
\def\readdatafile#1{%
\begingroup
\setupdatafile
\input\jobname.#1
\endgroup}
\message{insertions,}
% including footnotes.
\newcount \footnoteno
% The trailing space in the following definition for supereject is
% vital for proper filling; pages come out unaligned when you do a
% pagealignmacro call if that space before the closing brace is
% removed. (Generally, numeric constants should always be followed by a
% space to prevent strange expansion errors.)
\def\supereject{\par\penalty -20000\footnoteno =0 }
% @footnotestyle is meaningful for Info output only.
\let\footnotestyle=\comment
{\catcode `\@=11
%
% Auto-number footnotes. Otherwise like plain.
\gdef\footnote{%
\let\indent=\ptexindent
\let\noindent=\ptexnoindent
\global\advance\footnoteno by \@ne
\edef\thisfootno{$^{\the\footnoteno}$}%
%
% In case the footnote comes at the end of a sentence, preserve the
% extra spacing after we do the footnote number.
\let\@sf\empty
\ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi
%
% Remove inadvertent blank space before typesetting the footnote number.
\unskip
\thisfootno\@sf
\dofootnote
}%
% Don't bother with the trickery in plain.tex to not require the
% footnote text as a parameter. Our footnotes don't need to be so general.
%
% Oh yes, they do; otherwise, @ifset (and anything else that uses
% \parseargline) fails inside footnotes because the tokens are fixed when
% the footnote is read. --karl, 16nov96.
%
\gdef\dofootnote{%
\insert\footins\bgroup
% We want to typeset this text as a normal paragraph, even if the
% footnote reference occurs in (for example) a display environment.
% So reset some parameters.
\hsize=\pagewidth
\interlinepenalty\interfootnotelinepenalty
\splittopskip\ht\strutbox % top baseline for broken footnotes
\splitmaxdepth\dp\strutbox
\floatingpenalty\@MM
\leftskip\z@skip
\rightskip\z@skip
\spaceskip\z@skip
\xspaceskip\z@skip
\parindent\defaultparindent
%
\smallfonts \rm
%
% Because we use hanging indentation in footnotes, a @noindent appears
% to exdent this text, so make it be a no-op. makeinfo does not use
% hanging indentation so @noindent can still be needed within footnote
% text after an @example or the like (not that this is good style).
\let\noindent = \relax
%
% Hang the footnote text off the number. Use \everypar in case the
% footnote extends for more than one paragraph.
\everypar = {\hang}%
\textindent{\thisfootno}%
%
% Don't crash into the line above the footnote text. Since this
% expands into a box, it must come within the paragraph, lest it
% provide a place where TeX can split the footnote.
\footstrut
%
% Invoke rest of plain TeX footnote routine.
\futurelet\next\fo@t
}
}%end \catcode `\@=11
% In case a @footnote appears in a vbox, save the footnote text and create
% the real \insert just after the vbox finished. Otherwise, the insertion
% would be lost.
% Similarly, if a @footnote appears inside an alignment, save the footnote
% text to a box and make the \insert when a row of the table is finished.
% And the same can be done for other insert classes. --kasal, 16nov03.
% Replace the \insert primitive by a cheating macro.
% Deeper inside, just make sure that the saved insertions are not spilled
% out prematurely.
%
\def\startsavinginserts{%
\ifx \insert\ptexinsert
\let\insert\saveinsert
\else
\let\checkinserts\relax
\fi
}
% This \insert replacement works for both \insert\footins{foo} and
% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}.
%
\def\saveinsert#1{%
\edef\next{\noexpand\savetobox \makeSAVEname#1}%
\afterassignment\next
% swallow the left brace
\let\temp =
}
\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}}
\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1}
\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi}
\def\placesaveins#1{%
\ptexinsert \csname\expandafter\gobblesave\string#1\endcsname
{\box#1}%
}
% eat @SAVE -- beware, all of them have catcode \other:
{
\def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-)
\gdef\gobblesave @SAVE{}
}
% initialization:
\def\newsaveins #1{%
\edef\next{\noexpand\newsaveinsX \makeSAVEname#1}%
\next
}
\def\newsaveinsX #1{%
\csname newbox\endcsname #1%
\expandafter\def\expandafter\checkinserts\expandafter{\checkinserts
\checksaveins #1}%
}
% initialize:
\let\checkinserts\empty
\newsaveins\footins
\newsaveins\margin
% @image. We use the macros from epsf.tex to support this.
% If epsf.tex is not installed and @image is used, we complain.
%
% Check for and read epsf.tex up front. If we read it only at @image
% time, we might be inside a group, and then its definitions would get
% undone and the next image would fail.
\openin 1 = epsf.tex
\ifeof 1 \else
% Do not bother showing banner with epsf.tex v2.7k (available in
% doc/epsf.tex and on ctan).
\def\epsfannounce{\toks0 = }%
\input epsf.tex
\fi
\closein 1
%
% We will only complain once about lack of epsf.tex.
\newif\ifwarnednoepsf
\newhelp\noepsfhelp{epsf.tex must be installed for images to
work. It is also included in the Texinfo distribution, or you can get
it from ftp://tug.org/tex/epsf.tex.}
%
\def\image#1{%
\ifx\epsfbox\thisisundefined
\ifwarnednoepsf \else
\errhelp = \noepsfhelp
\errmessage{epsf.tex not found, images will be ignored}%
\global\warnednoepsftrue
\fi
\else
\imagexxx #1,,,,,\finish
\fi
}
%
% Arguments to @image:
% #1 is (mandatory) image filename; we tack on .eps extension.
% #2 is (optional) width, #3 is (optional) height.
% #4 is (ignored optional) html alt text.
% #5 is (ignored optional) extension.
% #6 is just the usual extra ignored arg for parsing stuff.
\newif\ifimagevmode
\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup
\catcode`\^^M = 5 % in case we're inside an example
\normalturnoffactive % allow _ et al. in names
% If the image is by itself, center it.
\ifvmode
\imagevmodetrue
\else \ifx\centersub\centerV
% for @center @image, we need a vbox so we can have our vertical space
\imagevmodetrue
\vbox\bgroup % vbox has better behavior than vtop herev
\fi\fi
%
\ifimagevmode
\nobreak\medskip
% Usually we'll have text after the image which will insert
% \parskip glue, so insert it here too to equalize the space
% above and below.
\nobreak\vskip\parskip
\nobreak
\fi
%
% Leave vertical mode so that indentation from an enclosing
% environment such as @quotation is respected.
% However, if we're at the top level, we don't want the
% normal paragraph indentation.
% On the other hand, if we are in the case of @center @image, we don't
% want to start a paragraph, which will create a hsize-width box and
% eradicate the centering.
\ifx\centersub\centerV\else \noindent \fi
%
% Output the image.
\ifpdf
\dopdfimage{#1}{#2}{#3}%
\else
% \epsfbox itself resets \epsf?size at each figure.
\setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
\setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
\epsfbox{#1.eps}%
\fi
%
\ifimagevmode
\medskip % space after a standalone image
\fi
\ifx\centersub\centerV \egroup \fi
\endgroup}
% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables,
% etc. We don't actually implement floating yet, we always include the
% float "here". But it seemed the best name for the future.
%
\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish}
% There may be a space before second and/or third parameter; delete it.
\def\eatcommaspace#1, {#1,}
% #1 is the optional FLOATTYPE, the text label for this float, typically
% "Figure", "Table", "Example", etc. Can't contain commas. If omitted,
% this float will not be numbered and cannot be referred to.
%
% #2 is the optional xref label. Also must be present for the float to
% be referable.
%
% #3 is the optional positioning argument; for now, it is ignored. It
% will somehow specify the positions allowed to float to (here, top, bottom).
%
% We keep a separate counter for each FLOATTYPE, which we reset at each
% chapter-level command.
\let\resetallfloatnos=\empty
%
\def\dofloat#1,#2,#3,#4\finish{%
\let\thiscaption=\empty
\let\thisshortcaption=\empty
%
% don't lose footnotes inside @float.
%
% BEWARE: when the floats start float, we have to issue warning whenever an
% insert appears inside a float which could possibly float. --kasal, 26may04
%
\startsavinginserts
%
% We can't be used inside a paragraph.
\par
%
\vtop\bgroup
\def\floattype{#1}%
\def\floatlabel{#2}%
\def\floatloc{#3}% we do nothing with this yet.
%
\ifx\floattype\empty
\let\safefloattype=\empty
\else
{%
% the floattype might have accents or other special characters,
% but we need to use it in a control sequence name.
\indexnofonts
\turnoffactive
\xdef\safefloattype{\floattype}%
}%
\fi
%
% If label is given but no type, we handle that as the empty type.
\ifx\floatlabel\empty \else
% We want each FLOATTYPE to be numbered separately (Figure 1,
% Table 1, Figure 2, ...). (And if no label, no number.)
%
\expandafter\getfloatno\csname\safefloattype floatno\endcsname
\global\advance\floatno by 1
%
{%
% This magic value for \lastsection is output by \setref as the
% XREFLABEL-title value. \xrefX uses it to distinguish float
% labels (which have a completely different output format) from
% node and anchor labels. And \xrdef uses it to construct the
% lists of floats.
%
\edef\lastsection{\floatmagic=\safefloattype}%
\setref{\floatlabel}{Yfloat}%
}%
\fi
%
% start with \parskip glue, I guess.
\vskip\parskip
%
% Don't suppress indentation if a float happens to start a section.
\restorefirstparagraphindent
}
% we have these possibilities:
% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap
% @float Foo,lbl & no caption: Foo 1.1
% @float Foo & @caption{Cap}: Foo: Cap
% @float Foo & no caption: Foo
% @float ,lbl & Caption{Cap}: 1.1: Cap
% @float ,lbl & no caption: 1.1
% @float & @caption{Cap}: Cap
% @float & no caption:
%
\def\Efloat{%
\let\floatident = \empty
%
% In all cases, if we have a float type, it comes first.
\ifx\floattype\empty \else \def\floatident{\floattype}\fi
%
% If we have an xref label, the number comes next.
\ifx\floatlabel\empty \else
\ifx\floattype\empty \else % if also had float type, need tie first.
\appendtomacro\floatident{\tie}%
\fi
% the number.
\appendtomacro\floatident{\chaplevelprefix\the\floatno}%
\fi
%
% Start the printed caption with what we've constructed in
% \floatident, but keep it separate; we need \floatident again.
\let\captionline = \floatident
%
\ifx\thiscaption\empty \else
\ifx\floatident\empty \else
\appendtomacro\captionline{: }% had ident, so need a colon between
\fi
%
% caption text.
\appendtomacro\captionline{\scanexp\thiscaption}%
\fi
%
% If we have anything to print, print it, with space before.
% Eventually this needs to become an \insert.
\ifx\captionline\empty \else
\vskip.5\parskip
\captionline
%
% Space below caption.
\vskip\parskip
\fi
%
% If have an xref label, write the list of floats info. Do this
% after the caption, to avoid chance of it being a breakpoint.
\ifx\floatlabel\empty \else
% Write the text that goes in the lof to the aux file as
% \floatlabel-lof. Besides \floatident, we include the short
% caption if specified, else the full caption if specified, else nothing.
{%
\atdummies
%
% since we read the caption text in the macro world, where ^^M
% is turned into a normal character, we have to scan it back, so
% we don't write the literal three characters "^^M" into the aux file.
\scanexp{%
\xdef\noexpand\gtemp{%
\ifx\thisshortcaption\empty
\thiscaption
\else
\thisshortcaption
\fi
}%
}%
\immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident
\ifx\gtemp\empty \else : \gtemp \fi}}%
}%
\fi
\egroup % end of \vtop
%
% place the captured inserts
%
% BEWARE: when the floats start floating, we have to issue warning
% whenever an insert appears inside a float which could possibly
% float. --kasal, 26may04
%
\checkinserts
}
% Append the tokens #2 to the definition of macro #1, not expanding either.
%
\def\appendtomacro#1#2{%
\expandafter\def\expandafter#1\expandafter{#1#2}%
}
% @caption, @shortcaption
%
\def\caption{\docaption\thiscaption}
\def\shortcaption{\docaption\thisshortcaption}
\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption}
\def\defcaption#1#2{\egroup \def#1{#2}}
% The parameter is the control sequence identifying the counter we are
% going to use. Create it if it doesn't exist and assign it to \floatno.
\def\getfloatno#1{%
\ifx#1\relax
% Haven't seen this figure type before.
\csname newcount\endcsname #1%
%
% Remember to reset this floatno at the next chap.
\expandafter\gdef\expandafter\resetallfloatnos
\expandafter{\resetallfloatnos #1=0 }%
\fi
\let\floatno#1%
}
% \setref calls this to get the XREFLABEL-snt value. We want an @xref
% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we
% first read the @float command.
%
\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}%
% Magic string used for the XREFLABEL-title value, so \xrefX can
% distinguish floats from other xref types.
\def\floatmagic{!!float!!}
% #1 is the control sequence we are passed; we expand into a conditional
% which is true if #1 represents a float ref. That is, the magic
% \lastsection value which we \setref above.
%
\def\iffloat#1{\expandafter\doiffloat#1==\finish}
%
% #1 is (maybe) the \floatmagic string. If so, #2 will be the
% (safe) float type for this float. We set \iffloattype to #2.
%
\def\doiffloat#1=#2=#3\finish{%
\def\temp{#1}%
\def\iffloattype{#2}%
\ifx\temp\floatmagic
}
% @listoffloats FLOATTYPE - print a list of floats like a table of contents.
%
\parseargdef\listoffloats{%
\def\floattype{#1}% floattype
{%
% the floattype might have accents or other special characters,
% but we need to use it in a control sequence name.
\indexnofonts
\turnoffactive
\xdef\safefloattype{\floattype}%
}%
%
% \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE.
\expandafter\ifx\csname floatlist\safefloattype\endcsname \relax
\ifhavexrefs
% if the user said @listoffloats foo but never @float foo.
\message{\linenumber No `\safefloattype' floats to list.}%
\fi
\else
\begingroup
\leftskip=\tocindent % indent these entries like a toc
\let\do=\listoffloatsdo
\csname floatlist\safefloattype\endcsname
\endgroup
\fi
}
% This is called on each entry in a list of floats. We're passed the
% xref label, in the form LABEL-title, which is how we save it in the
% aux file. We strip off the -title and look up \XRLABEL-lof, which
% has the text we're supposed to typeset here.
%
% Figures without xref labels will not be included in the list (since
% they won't appear in the aux file).
%
\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish}
\def\listoffloatsdoentry#1-title\finish{{%
% Can't fully expand XR#1-lof because it can contain anything. Just
% pass the control sequence. On the other hand, XR#1-pg is just the
% page number, and we want to fully expand that so we can get a link
% in pdf output.
\toksA = \expandafter{\csname XR#1-lof\endcsname}%
%
% use the same \entry macro we use to generate the TOC and index.
\edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}%
\writeentry
}}
\message{localization,}
% For single-language documents, @documentlanguage is usually given very
% early, just after @documentencoding. Single argument is the language
% (de) or locale (de_DE) abbreviation.
%
{
\catcode`\_ = \active
\globaldefs=1
\parseargdef\documentlanguage{\begingroup
\let_=\normalunderscore % normal _ character for filenames
\tex % read txi-??.tex file in plain TeX.
% Read the file by the name they passed if it exists.
\openin 1 txi-#1.tex
\ifeof 1
\documentlanguagetrywithoutunderscore{#1_\finish}%
\else
\globaldefs = 1 % everything in the txi-LL files needs to persist
\input txi-#1.tex
\fi
\closein 1
\endgroup % end raw TeX
\endgroup}
%
% If they passed de_DE, and txi-de_DE.tex doesn't exist,
% try txi-de.tex.
%
\gdef\documentlanguagetrywithoutunderscore#1_#2\finish{%
\openin 1 txi-#1.tex
\ifeof 1
\errhelp = \nolanghelp
\errmessage{Cannot read language file txi-#1.tex}%
\else
\globaldefs = 1 % everything in the txi-LL files needs to persist
\input txi-#1.tex
\fi
\closein 1
}
}% end of special _ catcode
%
\newhelp\nolanghelp{The given language definition file cannot be found or
is empty. Maybe you need to install it? Putting it in the current
directory should work if nowhere else does.}
% This macro is called from txi-??.tex files; the first argument is the
% \language name to set (without the "\lang@" prefix), the second and
% third args are \{left,right}hyphenmin.
%
% The language names to pass are determined when the format is built.
% See the etex.log file created at that time, e.g.,
% /usr/local/texlive/2008/texmf-var/web2c/pdftex/etex.log.
%
% With TeX Live 2008, etex now includes hyphenation patterns for all
% available languages. This means we can support hyphenation in
% Texinfo, at least to some extent. (This still doesn't solve the
% accented characters problem.)
%
\catcode`@=11
\def\txisetlanguage#1#2#3{%
% do not set the language if the name is undefined in the current TeX.
\expandafter\ifx\csname lang@#1\endcsname \relax
\message{no patterns for #1}%
\else
\global\language = \csname lang@#1\endcsname
\fi
% but there is no harm in adjusting the hyphenmin values regardless.
\global\lefthyphenmin = #2\relax
\global\righthyphenmin = #3\relax
}
% Helpers for encodings.
% Set the catcode of characters 128 through 255 to the specified number.
%
\def\setnonasciicharscatcode#1{%
\count255=128
\loop\ifnum\count255<256
\global\catcode\count255=#1\relax
\advance\count255 by 1
\repeat
}
\def\setnonasciicharscatcodenonglobal#1{%
\count255=128
\loop\ifnum\count255<256
\catcode\count255=#1\relax
\advance\count255 by 1
\repeat
}
% @documentencoding sets the definition of non-ASCII characters
% according to the specified encoding.
%
\parseargdef\documentencoding{%
% Encoding being declared for the document.
\def\declaredencoding{\csname #1.enc\endcsname}%
%
% Supported encodings: names converted to tokens in order to be able
% to compare them with \ifx.
\def\ascii{\csname US-ASCII.enc\endcsname}%
\def\latnine{\csname ISO-8859-15.enc\endcsname}%
\def\latone{\csname ISO-8859-1.enc\endcsname}%
\def\lattwo{\csname ISO-8859-2.enc\endcsname}%
\def\utfeight{\csname UTF-8.enc\endcsname}%
%
\ifx \declaredencoding \ascii
\asciichardefs
%
\else \ifx \declaredencoding \lattwo
\setnonasciicharscatcode\active
\lattwochardefs
%
\else \ifx \declaredencoding \latone
\setnonasciicharscatcode\active
\latonechardefs
%
\else \ifx \declaredencoding \latnine
\setnonasciicharscatcode\active
\latninechardefs
%
\else \ifx \declaredencoding \utfeight
\setnonasciicharscatcode\active
\utfeightchardefs
%
\else
\message{Unknown document encoding #1, ignoring.}%
%
\fi % utfeight
\fi % latnine
\fi % latone
\fi % lattwo
\fi % ascii
}
% A message to be logged when using a character that isn't available
% the default font encoding (OT1).
%
\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}}
% Take account of \c (plain) vs. \, (Texinfo) difference.
\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi}
% First, make active non-ASCII characters in order for them to be
% correctly categorized when TeX reads the replacement text of
% macros containing the character definitions.
\setnonasciicharscatcode\active
%
% Latin1 (ISO-8859-1) character definitions.
\def\latonechardefs{%
\gdef^^a0{\tie}
\gdef^^a1{\exclamdown}
\gdef^^a2{\missingcharmsg{CENT SIGN}}
\gdef^^a3{{\pounds}}
\gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
\gdef^^a5{\missingcharmsg{YEN SIGN}}
\gdef^^a6{\missingcharmsg{BROKEN BAR}}
\gdef^^a7{\S}
\gdef^^a8{\"{}}
\gdef^^a9{\copyright}
\gdef^^aa{\ordf}
\gdef^^ab{\guillemetleft}
\gdef^^ac{$\lnot$}
\gdef^^ad{\-}
\gdef^^ae{\registeredsymbol}
\gdef^^af{\={}}
%
\gdef^^b0{\textdegree}
\gdef^^b1{$\pm$}
\gdef^^b2{$^2$}
\gdef^^b3{$^3$}
\gdef^^b4{\'{}}
\gdef^^b5{$\mu$}
\gdef^^b6{\P}
%
\gdef^^b7{$^.$}
\gdef^^b8{\cedilla\ }
\gdef^^b9{$^1$}
\gdef^^ba{\ordm}
%
\gdef^^bb{\guillemetright}
\gdef^^bc{$1\over4$}
\gdef^^bd{$1\over2$}
\gdef^^be{$3\over4$}
\gdef^^bf{\questiondown}
%
\gdef^^c0{\`A}
\gdef^^c1{\'A}
\gdef^^c2{\^A}
\gdef^^c3{\~A}
\gdef^^c4{\"A}
\gdef^^c5{\ringaccent A}
\gdef^^c6{\AE}
\gdef^^c7{\cedilla C}
\gdef^^c8{\`E}
\gdef^^c9{\'E}
\gdef^^ca{\^E}
\gdef^^cb{\"E}
\gdef^^cc{\`I}
\gdef^^cd{\'I}
\gdef^^ce{\^I}
\gdef^^cf{\"I}
%
\gdef^^d0{\DH}
\gdef^^d1{\~N}
\gdef^^d2{\`O}
\gdef^^d3{\'O}
\gdef^^d4{\^O}
\gdef^^d5{\~O}
\gdef^^d6{\"O}
\gdef^^d7{$\times$}
\gdef^^d8{\O}
\gdef^^d9{\`U}
\gdef^^da{\'U}
\gdef^^db{\^U}
\gdef^^dc{\"U}
\gdef^^dd{\'Y}
\gdef^^de{\TH}
\gdef^^df{\ss}
%
\gdef^^e0{\`a}
\gdef^^e1{\'a}
\gdef^^e2{\^a}
\gdef^^e3{\~a}
\gdef^^e4{\"a}
\gdef^^e5{\ringaccent a}
\gdef^^e6{\ae}
\gdef^^e7{\cedilla c}
\gdef^^e8{\`e}
\gdef^^e9{\'e}
\gdef^^ea{\^e}
\gdef^^eb{\"e}
\gdef^^ec{\`{\dotless i}}
\gdef^^ed{\'{\dotless i}}
\gdef^^ee{\^{\dotless i}}
\gdef^^ef{\"{\dotless i}}
%
\gdef^^f0{\dh}
\gdef^^f1{\~n}
\gdef^^f2{\`o}
\gdef^^f3{\'o}
\gdef^^f4{\^o}
\gdef^^f5{\~o}
\gdef^^f6{\"o}
\gdef^^f7{$\div$}
\gdef^^f8{\o}
\gdef^^f9{\`u}
\gdef^^fa{\'u}
\gdef^^fb{\^u}
\gdef^^fc{\"u}
\gdef^^fd{\'y}
\gdef^^fe{\th}
\gdef^^ff{\"y}
}
% Latin9 (ISO-8859-15) encoding character definitions.
\def\latninechardefs{%
% Encoding is almost identical to Latin1.
\latonechardefs
%
\gdef^^a4{\euro}
\gdef^^a6{\v S}
\gdef^^a8{\v s}
\gdef^^b4{\v Z}
\gdef^^b8{\v z}
\gdef^^bc{\OE}
\gdef^^bd{\oe}
\gdef^^be{\"Y}
}
% Latin2 (ISO-8859-2) character definitions.
\def\lattwochardefs{%
\gdef^^a0{\tie}
\gdef^^a1{\ogonek{A}}
\gdef^^a2{\u{}}
\gdef^^a3{\L}
\gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
\gdef^^a5{\v L}
\gdef^^a6{\'S}
\gdef^^a7{\S}
\gdef^^a8{\"{}}
\gdef^^a9{\v S}
\gdef^^aa{\cedilla S}
\gdef^^ab{\v T}
\gdef^^ac{\'Z}
\gdef^^ad{\-}
\gdef^^ae{\v Z}
\gdef^^af{\dotaccent Z}
%
\gdef^^b0{\textdegree}
\gdef^^b1{\ogonek{a}}
\gdef^^b2{\ogonek{ }}
\gdef^^b3{\l}
\gdef^^b4{\'{}}
\gdef^^b5{\v l}
\gdef^^b6{\'s}
\gdef^^b7{\v{}}
\gdef^^b8{\cedilla\ }
\gdef^^b9{\v s}
\gdef^^ba{\cedilla s}
\gdef^^bb{\v t}
\gdef^^bc{\'z}
\gdef^^bd{\H{}}
\gdef^^be{\v z}
\gdef^^bf{\dotaccent z}
%
\gdef^^c0{\'R}
\gdef^^c1{\'A}
\gdef^^c2{\^A}
\gdef^^c3{\u A}
\gdef^^c4{\"A}
\gdef^^c5{\'L}
\gdef^^c6{\'C}
\gdef^^c7{\cedilla C}
\gdef^^c8{\v C}
\gdef^^c9{\'E}
\gdef^^ca{\ogonek{E}}
\gdef^^cb{\"E}
\gdef^^cc{\v E}
\gdef^^cd{\'I}
\gdef^^ce{\^I}
\gdef^^cf{\v D}
%
\gdef^^d0{\DH}
\gdef^^d1{\'N}
\gdef^^d2{\v N}
\gdef^^d3{\'O}
\gdef^^d4{\^O}
\gdef^^d5{\H O}
\gdef^^d6{\"O}
\gdef^^d7{$\times$}
\gdef^^d8{\v R}
\gdef^^d9{\ringaccent U}
\gdef^^da{\'U}
\gdef^^db{\H U}
\gdef^^dc{\"U}
\gdef^^dd{\'Y}
\gdef^^de{\cedilla T}
\gdef^^df{\ss}
%
\gdef^^e0{\'r}
\gdef^^e1{\'a}
\gdef^^e2{\^a}
\gdef^^e3{\u a}
\gdef^^e4{\"a}
\gdef^^e5{\'l}
\gdef^^e6{\'c}
\gdef^^e7{\cedilla c}
\gdef^^e8{\v c}
\gdef^^e9{\'e}
\gdef^^ea{\ogonek{e}}
\gdef^^eb{\"e}
\gdef^^ec{\v e}
\gdef^^ed{\'{\dotless{i}}}
\gdef^^ee{\^{\dotless{i}}}
\gdef^^ef{\v d}
%
\gdef^^f0{\dh}
\gdef^^f1{\'n}
\gdef^^f2{\v n}
\gdef^^f3{\'o}
\gdef^^f4{\^o}
\gdef^^f5{\H o}
\gdef^^f6{\"o}
\gdef^^f7{$\div$}
\gdef^^f8{\v r}
\gdef^^f9{\ringaccent u}
\gdef^^fa{\'u}
\gdef^^fb{\H u}
\gdef^^fc{\"u}
\gdef^^fd{\'y}
\gdef^^fe{\cedilla t}
\gdef^^ff{\dotaccent{}}
}
% UTF-8 character definitions.
%
% This code to support UTF-8 is based on LaTeX's utf8.def, with some
% changes for Texinfo conventions. It is included here under the GPL by
% permission from Frank Mittelbach and the LaTeX team.
%
\newcount\countUTFx
\newcount\countUTFy
\newcount\countUTFz
\gdef\UTFviiiTwoOctets#1#2{\expandafter
\UTFviiiDefined\csname u8:#1\string #2\endcsname}
%
\gdef\UTFviiiThreeOctets#1#2#3{\expandafter
\UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname}
%
\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter
\UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname}
\gdef\UTFviiiDefined#1{%
\ifx #1\relax
\message{\linenumber Unicode char \string #1 not defined for Texinfo}%
\else
\expandafter #1%
\fi
}
\begingroup
\catcode`\~13
\catcode`\"12
\def\UTFviiiLoop{%
\global\catcode\countUTFx\active
\uccode`\~\countUTFx
\uppercase\expandafter{\UTFviiiTmp}%
\advance\countUTFx by 1
\ifnum\countUTFx < \countUTFy
\expandafter\UTFviiiLoop
\fi}
\countUTFx = "C2
\countUTFy = "E0
\def\UTFviiiTmp{%
\xdef~{\noexpand\UTFviiiTwoOctets\string~}}
\UTFviiiLoop
\countUTFx = "E0
\countUTFy = "F0
\def\UTFviiiTmp{%
\xdef~{\noexpand\UTFviiiThreeOctets\string~}}
\UTFviiiLoop
\countUTFx = "F0
\countUTFy = "F4
\def\UTFviiiTmp{%
\xdef~{\noexpand\UTFviiiFourOctets\string~}}
\UTFviiiLoop
\endgroup
\begingroup
\catcode`\"=12
\catcode`\<=12
\catcode`\.=12
\catcode`\,=12
\catcode`\;=12
\catcode`\!=12
\catcode`\~=13
\gdef\DeclareUnicodeCharacter#1#2{%
\countUTFz = "#1\relax
%\wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}%
\begingroup
\parseXMLCharref
\def\UTFviiiTwoOctets##1##2{%
\csname u8:##1\string ##2\endcsname}%
\def\UTFviiiThreeOctets##1##2##3{%
\csname u8:##1\string ##2\string ##3\endcsname}%
\def\UTFviiiFourOctets##1##2##3##4{%
\csname u8:##1\string ##2\string ##3\string ##4\endcsname}%
\expandafter\expandafter\expandafter\expandafter
\expandafter\expandafter\expandafter
\gdef\UTFviiiTmp{#2}%
\endgroup}
\gdef\parseXMLCharref{%
\ifnum\countUTFz < "A0\relax
\errhelp = \EMsimple
\errmessage{Cannot define Unicode char value < 00A0}%
\else\ifnum\countUTFz < "800\relax
\parseUTFviiiA,%
\parseUTFviiiB C\UTFviiiTwoOctets.,%
\else\ifnum\countUTFz < "10000\relax
\parseUTFviiiA;%
\parseUTFviiiA,%
\parseUTFviiiB E\UTFviiiThreeOctets.{,;}%
\else
\parseUTFviiiA;%
\parseUTFviiiA,%
\parseUTFviiiA!%
\parseUTFviiiB F\UTFviiiFourOctets.{!,;}%
\fi\fi\fi
}
\gdef\parseUTFviiiA#1{%
\countUTFx = \countUTFz
\divide\countUTFz by 64
\countUTFy = \countUTFz
\multiply\countUTFz by 64
\advance\countUTFx by -\countUTFz
\advance\countUTFx by 128
\uccode `#1\countUTFx
\countUTFz = \countUTFy}
\gdef\parseUTFviiiB#1#2#3#4{%
\advance\countUTFz by "#10\relax
\uccode `#3\countUTFz
\uppercase{\gdef\UTFviiiTmp{#2#3#4}}}
\endgroup
\def\utfeightchardefs{%
\DeclareUnicodeCharacter{00A0}{\tie}
\DeclareUnicodeCharacter{00A1}{\exclamdown}
\DeclareUnicodeCharacter{00A3}{\pounds}
\DeclareUnicodeCharacter{00A8}{\"{ }}
\DeclareUnicodeCharacter{00A9}{\copyright}
\DeclareUnicodeCharacter{00AA}{\ordf}
\DeclareUnicodeCharacter{00AB}{\guillemetleft}
\DeclareUnicodeCharacter{00AD}{\-}
\DeclareUnicodeCharacter{00AE}{\registeredsymbol}
\DeclareUnicodeCharacter{00AF}{\={ }}
\DeclareUnicodeCharacter{00B0}{\ringaccent{ }}
\DeclareUnicodeCharacter{00B4}{\'{ }}
\DeclareUnicodeCharacter{00B8}{\cedilla{ }}
\DeclareUnicodeCharacter{00BA}{\ordm}
\DeclareUnicodeCharacter{00BB}{\guillemetright}
\DeclareUnicodeCharacter{00BF}{\questiondown}
\DeclareUnicodeCharacter{00C0}{\`A}
\DeclareUnicodeCharacter{00C1}{\'A}
\DeclareUnicodeCharacter{00C2}{\^A}
\DeclareUnicodeCharacter{00C3}{\~A}
\DeclareUnicodeCharacter{00C4}{\"A}
\DeclareUnicodeCharacter{00C5}{\AA}
\DeclareUnicodeCharacter{00C6}{\AE}
\DeclareUnicodeCharacter{00C7}{\cedilla{C}}
\DeclareUnicodeCharacter{00C8}{\`E}
\DeclareUnicodeCharacter{00C9}{\'E}
\DeclareUnicodeCharacter{00CA}{\^E}
\DeclareUnicodeCharacter{00CB}{\"E}
\DeclareUnicodeCharacter{00CC}{\`I}
\DeclareUnicodeCharacter{00CD}{\'I}
\DeclareUnicodeCharacter{00CE}{\^I}
\DeclareUnicodeCharacter{00CF}{\"I}
\DeclareUnicodeCharacter{00D0}{\DH}
\DeclareUnicodeCharacter{00D1}{\~N}
\DeclareUnicodeCharacter{00D2}{\`O}
\DeclareUnicodeCharacter{00D3}{\'O}
\DeclareUnicodeCharacter{00D4}{\^O}
\DeclareUnicodeCharacter{00D5}{\~O}
\DeclareUnicodeCharacter{00D6}{\"O}
\DeclareUnicodeCharacter{00D8}{\O}
\DeclareUnicodeCharacter{00D9}{\`U}
\DeclareUnicodeCharacter{00DA}{\'U}
\DeclareUnicodeCharacter{00DB}{\^U}
\DeclareUnicodeCharacter{00DC}{\"U}
\DeclareUnicodeCharacter{00DD}{\'Y}
\DeclareUnicodeCharacter{00DE}{\TH}
\DeclareUnicodeCharacter{00DF}{\ss}
\DeclareUnicodeCharacter{00E0}{\`a}
\DeclareUnicodeCharacter{00E1}{\'a}
\DeclareUnicodeCharacter{00E2}{\^a}
\DeclareUnicodeCharacter{00E3}{\~a}
\DeclareUnicodeCharacter{00E4}{\"a}
\DeclareUnicodeCharacter{00E5}{\aa}
\DeclareUnicodeCharacter{00E6}{\ae}
\DeclareUnicodeCharacter{00E7}{\cedilla{c}}
\DeclareUnicodeCharacter{00E8}{\`e}
\DeclareUnicodeCharacter{00E9}{\'e}
\DeclareUnicodeCharacter{00EA}{\^e}
\DeclareUnicodeCharacter{00EB}{\"e}
\DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}}
\DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}}
\DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}}
\DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}}
\DeclareUnicodeCharacter{00F0}{\dh}
\DeclareUnicodeCharacter{00F1}{\~n}
\DeclareUnicodeCharacter{00F2}{\`o}
\DeclareUnicodeCharacter{00F3}{\'o}
\DeclareUnicodeCharacter{00F4}{\^o}
\DeclareUnicodeCharacter{00F5}{\~o}
\DeclareUnicodeCharacter{00F6}{\"o}
\DeclareUnicodeCharacter{00F8}{\o}
\DeclareUnicodeCharacter{00F9}{\`u}
\DeclareUnicodeCharacter{00FA}{\'u}
\DeclareUnicodeCharacter{00FB}{\^u}
\DeclareUnicodeCharacter{00FC}{\"u}
\DeclareUnicodeCharacter{00FD}{\'y}
\DeclareUnicodeCharacter{00FE}{\th}
\DeclareUnicodeCharacter{00FF}{\"y}
\DeclareUnicodeCharacter{0100}{\=A}
\DeclareUnicodeCharacter{0101}{\=a}
\DeclareUnicodeCharacter{0102}{\u{A}}
\DeclareUnicodeCharacter{0103}{\u{a}}
\DeclareUnicodeCharacter{0104}{\ogonek{A}}
\DeclareUnicodeCharacter{0105}{\ogonek{a}}
\DeclareUnicodeCharacter{0106}{\'C}
\DeclareUnicodeCharacter{0107}{\'c}
\DeclareUnicodeCharacter{0108}{\^C}
\DeclareUnicodeCharacter{0109}{\^c}
\DeclareUnicodeCharacter{0118}{\ogonek{E}}
\DeclareUnicodeCharacter{0119}{\ogonek{e}}
\DeclareUnicodeCharacter{010A}{\dotaccent{C}}
\DeclareUnicodeCharacter{010B}{\dotaccent{c}}
\DeclareUnicodeCharacter{010C}{\v{C}}
\DeclareUnicodeCharacter{010D}{\v{c}}
\DeclareUnicodeCharacter{010E}{\v{D}}
\DeclareUnicodeCharacter{0112}{\=E}
\DeclareUnicodeCharacter{0113}{\=e}
\DeclareUnicodeCharacter{0114}{\u{E}}
\DeclareUnicodeCharacter{0115}{\u{e}}
\DeclareUnicodeCharacter{0116}{\dotaccent{E}}
\DeclareUnicodeCharacter{0117}{\dotaccent{e}}
\DeclareUnicodeCharacter{011A}{\v{E}}
\DeclareUnicodeCharacter{011B}{\v{e}}
\DeclareUnicodeCharacter{011C}{\^G}
\DeclareUnicodeCharacter{011D}{\^g}
\DeclareUnicodeCharacter{011E}{\u{G}}
\DeclareUnicodeCharacter{011F}{\u{g}}
\DeclareUnicodeCharacter{0120}{\dotaccent{G}}
\DeclareUnicodeCharacter{0121}{\dotaccent{g}}
\DeclareUnicodeCharacter{0124}{\^H}
\DeclareUnicodeCharacter{0125}{\^h}
\DeclareUnicodeCharacter{0128}{\~I}
\DeclareUnicodeCharacter{0129}{\~{\dotless{i}}}
\DeclareUnicodeCharacter{012A}{\=I}
\DeclareUnicodeCharacter{012B}{\={\dotless{i}}}
\DeclareUnicodeCharacter{012C}{\u{I}}
\DeclareUnicodeCharacter{012D}{\u{\dotless{i}}}
\DeclareUnicodeCharacter{0130}{\dotaccent{I}}
\DeclareUnicodeCharacter{0131}{\dotless{i}}
\DeclareUnicodeCharacter{0132}{IJ}
\DeclareUnicodeCharacter{0133}{ij}
\DeclareUnicodeCharacter{0134}{\^J}
\DeclareUnicodeCharacter{0135}{\^{\dotless{j}}}
\DeclareUnicodeCharacter{0139}{\'L}
\DeclareUnicodeCharacter{013A}{\'l}
\DeclareUnicodeCharacter{0141}{\L}
\DeclareUnicodeCharacter{0142}{\l}
\DeclareUnicodeCharacter{0143}{\'N}
\DeclareUnicodeCharacter{0144}{\'n}
\DeclareUnicodeCharacter{0147}{\v{N}}
\DeclareUnicodeCharacter{0148}{\v{n}}
\DeclareUnicodeCharacter{014C}{\=O}
\DeclareUnicodeCharacter{014D}{\=o}
\DeclareUnicodeCharacter{014E}{\u{O}}
\DeclareUnicodeCharacter{014F}{\u{o}}
\DeclareUnicodeCharacter{0150}{\H{O}}
\DeclareUnicodeCharacter{0151}{\H{o}}
\DeclareUnicodeCharacter{0152}{\OE}
\DeclareUnicodeCharacter{0153}{\oe}
\DeclareUnicodeCharacter{0154}{\'R}
\DeclareUnicodeCharacter{0155}{\'r}
\DeclareUnicodeCharacter{0158}{\v{R}}
\DeclareUnicodeCharacter{0159}{\v{r}}
\DeclareUnicodeCharacter{015A}{\'S}
\DeclareUnicodeCharacter{015B}{\'s}
\DeclareUnicodeCharacter{015C}{\^S}
\DeclareUnicodeCharacter{015D}{\^s}
\DeclareUnicodeCharacter{015E}{\cedilla{S}}
\DeclareUnicodeCharacter{015F}{\cedilla{s}}
\DeclareUnicodeCharacter{0160}{\v{S}}
\DeclareUnicodeCharacter{0161}{\v{s}}
\DeclareUnicodeCharacter{0162}{\cedilla{t}}
\DeclareUnicodeCharacter{0163}{\cedilla{T}}
\DeclareUnicodeCharacter{0164}{\v{T}}
\DeclareUnicodeCharacter{0168}{\~U}
\DeclareUnicodeCharacter{0169}{\~u}
\DeclareUnicodeCharacter{016A}{\=U}
\DeclareUnicodeCharacter{016B}{\=u}
\DeclareUnicodeCharacter{016C}{\u{U}}
\DeclareUnicodeCharacter{016D}{\u{u}}
\DeclareUnicodeCharacter{016E}{\ringaccent{U}}
\DeclareUnicodeCharacter{016F}{\ringaccent{u}}
\DeclareUnicodeCharacter{0170}{\H{U}}
\DeclareUnicodeCharacter{0171}{\H{u}}
\DeclareUnicodeCharacter{0174}{\^W}
\DeclareUnicodeCharacter{0175}{\^w}
\DeclareUnicodeCharacter{0176}{\^Y}
\DeclareUnicodeCharacter{0177}{\^y}
\DeclareUnicodeCharacter{0178}{\"Y}
\DeclareUnicodeCharacter{0179}{\'Z}
\DeclareUnicodeCharacter{017A}{\'z}
\DeclareUnicodeCharacter{017B}{\dotaccent{Z}}
\DeclareUnicodeCharacter{017C}{\dotaccent{z}}
\DeclareUnicodeCharacter{017D}{\v{Z}}
\DeclareUnicodeCharacter{017E}{\v{z}}
\DeclareUnicodeCharacter{01C4}{D\v{Z}}
\DeclareUnicodeCharacter{01C5}{D\v{z}}
\DeclareUnicodeCharacter{01C6}{d\v{z}}
\DeclareUnicodeCharacter{01C7}{LJ}
\DeclareUnicodeCharacter{01C8}{Lj}
\DeclareUnicodeCharacter{01C9}{lj}
\DeclareUnicodeCharacter{01CA}{NJ}
\DeclareUnicodeCharacter{01CB}{Nj}
\DeclareUnicodeCharacter{01CC}{nj}
\DeclareUnicodeCharacter{01CD}{\v{A}}
\DeclareUnicodeCharacter{01CE}{\v{a}}
\DeclareUnicodeCharacter{01CF}{\v{I}}
\DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}}
\DeclareUnicodeCharacter{01D1}{\v{O}}
\DeclareUnicodeCharacter{01D2}{\v{o}}
\DeclareUnicodeCharacter{01D3}{\v{U}}
\DeclareUnicodeCharacter{01D4}{\v{u}}
\DeclareUnicodeCharacter{01E2}{\={\AE}}
\DeclareUnicodeCharacter{01E3}{\={\ae}}
\DeclareUnicodeCharacter{01E6}{\v{G}}
\DeclareUnicodeCharacter{01E7}{\v{g}}
\DeclareUnicodeCharacter{01E8}{\v{K}}
\DeclareUnicodeCharacter{01E9}{\v{k}}
\DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}}
\DeclareUnicodeCharacter{01F1}{DZ}
\DeclareUnicodeCharacter{01F2}{Dz}
\DeclareUnicodeCharacter{01F3}{dz}
\DeclareUnicodeCharacter{01F4}{\'G}
\DeclareUnicodeCharacter{01F5}{\'g}
\DeclareUnicodeCharacter{01F8}{\`N}
\DeclareUnicodeCharacter{01F9}{\`n}
\DeclareUnicodeCharacter{01FC}{\'{\AE}}
\DeclareUnicodeCharacter{01FD}{\'{\ae}}
\DeclareUnicodeCharacter{01FE}{\'{\O}}
\DeclareUnicodeCharacter{01FF}{\'{\o}}
\DeclareUnicodeCharacter{021E}{\v{H}}
\DeclareUnicodeCharacter{021F}{\v{h}}
\DeclareUnicodeCharacter{0226}{\dotaccent{A}}
\DeclareUnicodeCharacter{0227}{\dotaccent{a}}
\DeclareUnicodeCharacter{0228}{\cedilla{E}}
\DeclareUnicodeCharacter{0229}{\cedilla{e}}
\DeclareUnicodeCharacter{022E}{\dotaccent{O}}
\DeclareUnicodeCharacter{022F}{\dotaccent{o}}
\DeclareUnicodeCharacter{0232}{\=Y}
\DeclareUnicodeCharacter{0233}{\=y}
\DeclareUnicodeCharacter{0237}{\dotless{j}}
\DeclareUnicodeCharacter{02DB}{\ogonek{ }}
\DeclareUnicodeCharacter{1E02}{\dotaccent{B}}
\DeclareUnicodeCharacter{1E03}{\dotaccent{b}}
\DeclareUnicodeCharacter{1E04}{\udotaccent{B}}
\DeclareUnicodeCharacter{1E05}{\udotaccent{b}}
\DeclareUnicodeCharacter{1E06}{\ubaraccent{B}}
\DeclareUnicodeCharacter{1E07}{\ubaraccent{b}}
\DeclareUnicodeCharacter{1E0A}{\dotaccent{D}}
\DeclareUnicodeCharacter{1E0B}{\dotaccent{d}}
\DeclareUnicodeCharacter{1E0C}{\udotaccent{D}}
\DeclareUnicodeCharacter{1E0D}{\udotaccent{d}}
\DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}}
\DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}}
\DeclareUnicodeCharacter{1E1E}{\dotaccent{F}}
\DeclareUnicodeCharacter{1E1F}{\dotaccent{f}}
\DeclareUnicodeCharacter{1E20}{\=G}
\DeclareUnicodeCharacter{1E21}{\=g}
\DeclareUnicodeCharacter{1E22}{\dotaccent{H}}
\DeclareUnicodeCharacter{1E23}{\dotaccent{h}}
\DeclareUnicodeCharacter{1E24}{\udotaccent{H}}
\DeclareUnicodeCharacter{1E25}{\udotaccent{h}}
\DeclareUnicodeCharacter{1E26}{\"H}
\DeclareUnicodeCharacter{1E27}{\"h}
\DeclareUnicodeCharacter{1E30}{\'K}
\DeclareUnicodeCharacter{1E31}{\'k}
\DeclareUnicodeCharacter{1E32}{\udotaccent{K}}
\DeclareUnicodeCharacter{1E33}{\udotaccent{k}}
\DeclareUnicodeCharacter{1E34}{\ubaraccent{K}}
\DeclareUnicodeCharacter{1E35}{\ubaraccent{k}}
\DeclareUnicodeCharacter{1E36}{\udotaccent{L}}
\DeclareUnicodeCharacter{1E37}{\udotaccent{l}}
\DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}}
\DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}}
\DeclareUnicodeCharacter{1E3E}{\'M}
\DeclareUnicodeCharacter{1E3F}{\'m}
\DeclareUnicodeCharacter{1E40}{\dotaccent{M}}
\DeclareUnicodeCharacter{1E41}{\dotaccent{m}}
\DeclareUnicodeCharacter{1E42}{\udotaccent{M}}
\DeclareUnicodeCharacter{1E43}{\udotaccent{m}}
\DeclareUnicodeCharacter{1E44}{\dotaccent{N}}
\DeclareUnicodeCharacter{1E45}{\dotaccent{n}}
\DeclareUnicodeCharacter{1E46}{\udotaccent{N}}
\DeclareUnicodeCharacter{1E47}{\udotaccent{n}}
\DeclareUnicodeCharacter{1E48}{\ubaraccent{N}}
\DeclareUnicodeCharacter{1E49}{\ubaraccent{n}}
\DeclareUnicodeCharacter{1E54}{\'P}
\DeclareUnicodeCharacter{1E55}{\'p}
\DeclareUnicodeCharacter{1E56}{\dotaccent{P}}
\DeclareUnicodeCharacter{1E57}{\dotaccent{p}}
\DeclareUnicodeCharacter{1E58}{\dotaccent{R}}
\DeclareUnicodeCharacter{1E59}{\dotaccent{r}}
\DeclareUnicodeCharacter{1E5A}{\udotaccent{R}}
\DeclareUnicodeCharacter{1E5B}{\udotaccent{r}}
\DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}}
\DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}}
\DeclareUnicodeCharacter{1E60}{\dotaccent{S}}
\DeclareUnicodeCharacter{1E61}{\dotaccent{s}}
\DeclareUnicodeCharacter{1E62}{\udotaccent{S}}
\DeclareUnicodeCharacter{1E63}{\udotaccent{s}}
\DeclareUnicodeCharacter{1E6A}{\dotaccent{T}}
\DeclareUnicodeCharacter{1E6B}{\dotaccent{t}}
\DeclareUnicodeCharacter{1E6C}{\udotaccent{T}}
\DeclareUnicodeCharacter{1E6D}{\udotaccent{t}}
\DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}}
\DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}}
\DeclareUnicodeCharacter{1E7C}{\~V}
\DeclareUnicodeCharacter{1E7D}{\~v}
\DeclareUnicodeCharacter{1E7E}{\udotaccent{V}}
\DeclareUnicodeCharacter{1E7F}{\udotaccent{v}}
\DeclareUnicodeCharacter{1E80}{\`W}
\DeclareUnicodeCharacter{1E81}{\`w}
\DeclareUnicodeCharacter{1E82}{\'W}
\DeclareUnicodeCharacter{1E83}{\'w}
\DeclareUnicodeCharacter{1E84}{\"W}
\DeclareUnicodeCharacter{1E85}{\"w}
\DeclareUnicodeCharacter{1E86}{\dotaccent{W}}
\DeclareUnicodeCharacter{1E87}{\dotaccent{w}}
\DeclareUnicodeCharacter{1E88}{\udotaccent{W}}
\DeclareUnicodeCharacter{1E89}{\udotaccent{w}}
\DeclareUnicodeCharacter{1E8A}{\dotaccent{X}}
\DeclareUnicodeCharacter{1E8B}{\dotaccent{x}}
\DeclareUnicodeCharacter{1E8C}{\"X}
\DeclareUnicodeCharacter{1E8D}{\"x}
\DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}}
\DeclareUnicodeCharacter{1E8F}{\dotaccent{y}}
\DeclareUnicodeCharacter{1E90}{\^Z}
\DeclareUnicodeCharacter{1E91}{\^z}
\DeclareUnicodeCharacter{1E92}{\udotaccent{Z}}
\DeclareUnicodeCharacter{1E93}{\udotaccent{z}}
\DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}}
\DeclareUnicodeCharacter{1E95}{\ubaraccent{z}}
\DeclareUnicodeCharacter{1E96}{\ubaraccent{h}}
\DeclareUnicodeCharacter{1E97}{\"t}
\DeclareUnicodeCharacter{1E98}{\ringaccent{w}}
\DeclareUnicodeCharacter{1E99}{\ringaccent{y}}
\DeclareUnicodeCharacter{1EA0}{\udotaccent{A}}
\DeclareUnicodeCharacter{1EA1}{\udotaccent{a}}
\DeclareUnicodeCharacter{1EB8}{\udotaccent{E}}
\DeclareUnicodeCharacter{1EB9}{\udotaccent{e}}
\DeclareUnicodeCharacter{1EBC}{\~E}
\DeclareUnicodeCharacter{1EBD}{\~e}
\DeclareUnicodeCharacter{1ECA}{\udotaccent{I}}
\DeclareUnicodeCharacter{1ECB}{\udotaccent{i}}
\DeclareUnicodeCharacter{1ECC}{\udotaccent{O}}
\DeclareUnicodeCharacter{1ECD}{\udotaccent{o}}
\DeclareUnicodeCharacter{1EE4}{\udotaccent{U}}
\DeclareUnicodeCharacter{1EE5}{\udotaccent{u}}
\DeclareUnicodeCharacter{1EF2}{\`Y}
\DeclareUnicodeCharacter{1EF3}{\`y}
\DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}}
\DeclareUnicodeCharacter{1EF8}{\~Y}
\DeclareUnicodeCharacter{1EF9}{\~y}
\DeclareUnicodeCharacter{2013}{--}
\DeclareUnicodeCharacter{2014}{---}
\DeclareUnicodeCharacter{2018}{\quoteleft}
\DeclareUnicodeCharacter{2019}{\quoteright}
\DeclareUnicodeCharacter{201A}{\quotesinglbase}
\DeclareUnicodeCharacter{201C}{\quotedblleft}
\DeclareUnicodeCharacter{201D}{\quotedblright}
\DeclareUnicodeCharacter{201E}{\quotedblbase}
\DeclareUnicodeCharacter{2022}{\bullet}
\DeclareUnicodeCharacter{2026}{\dots}
\DeclareUnicodeCharacter{2039}{\guilsinglleft}
\DeclareUnicodeCharacter{203A}{\guilsinglright}
\DeclareUnicodeCharacter{20AC}{\euro}
\DeclareUnicodeCharacter{2192}{\expansion}
\DeclareUnicodeCharacter{21D2}{\result}
\DeclareUnicodeCharacter{2212}{\minus}
\DeclareUnicodeCharacter{2217}{\point}
\DeclareUnicodeCharacter{2261}{\equiv}
}% end of \utfeightchardefs
% US-ASCII character definitions.
\def\asciichardefs{% nothing need be done
\relax
}
% Make non-ASCII characters printable again for compatibility with
% existing Texinfo documents that may use them, even without declaring a
% document encoding.
%
\setnonasciicharscatcode \other
\message{formatting,}
\newdimen\defaultparindent \defaultparindent = 15pt
\chapheadingskip = 15pt plus 4pt minus 2pt
\secheadingskip = 12pt plus 3pt minus 2pt
\subsecheadingskip = 9pt plus 2pt minus 2pt
% Prevent underfull vbox error messages.
\vbadness = 10000
% Don't be very finicky about underfull hboxes, either.
\hbadness = 6666
% Following George Bush, get rid of widows and orphans.
\widowpenalty=10000
\clubpenalty=10000
% Use TeX 3.0's \emergencystretch to help line breaking, but if we're
% using an old version of TeX, don't do anything. We want the amount of
% stretch added to depend on the line length, hence the dependence on
% \hsize. We call this whenever the paper size is set.
%
\def\setemergencystretch{%
\ifx\emergencystretch\thisisundefined
% Allow us to assign to \emergencystretch anyway.
\def\emergencystretch{\dimen0}%
\else
\emergencystretch = .15\hsize
\fi
}
% Parameters in order: 1) textheight; 2) textwidth;
% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip;
% 7) physical page height; 8) physical page width.
%
% We also call \setleading{\textleading}, so the caller should define
% \textleading. The caller should also set \parskip.
%
\def\internalpagesizes#1#2#3#4#5#6#7#8{%
\voffset = #3\relax
\topskip = #6\relax
\splittopskip = \topskip
%
\vsize = #1\relax
\advance\vsize by \topskip
\outervsize = \vsize
\advance\outervsize by 2\topandbottommargin
\pageheight = \vsize
%
\hsize = #2\relax
\outerhsize = \hsize
\advance\outerhsize by 0.5in
\pagewidth = \hsize
%
\normaloffset = #4\relax
\bindingoffset = #5\relax
%
\ifpdf
\pdfpageheight #7\relax
\pdfpagewidth #8\relax
% if we don't reset these, they will remain at "1 true in" of
% whatever layout pdftex was dumped with.
\pdfhorigin = 1 true in
\pdfvorigin = 1 true in
\fi
%
\setleading{\textleading}
%
\parindent = \defaultparindent
\setemergencystretch
}
% @letterpaper (the default).
\def\letterpaper{{\globaldefs = 1
\parskip = 3pt plus 2pt minus 1pt
\textleading = 13.2pt
%
% If page is nothing but text, make it come out even.
\internalpagesizes{607.2pt}{6in}% that's 46 lines
{\voffset}{.25in}%
{\bindingoffset}{36pt}%
{11in}{8.5in}%
}}
% Use @smallbook to reset parameters for 7x9.25 trim size.
\def\smallbook{{\globaldefs = 1
\parskip = 2pt plus 1pt
\textleading = 12pt
%
\internalpagesizes{7.5in}{5in}%
{-.2in}{0in}%
{\bindingoffset}{16pt}%
{9.25in}{7in}%
%
\lispnarrowing = 0.3in
\tolerance = 700
\hfuzz = 1pt
\contentsrightmargin = 0pt
\defbodyindent = .5cm
}}
% Use @smallerbook to reset parameters for 6x9 trim size.
% (Just testing, parameters still in flux.)
\def\smallerbook{{\globaldefs = 1
\parskip = 1.5pt plus 1pt
\textleading = 12pt
%
\internalpagesizes{7.4in}{4.8in}%
{-.2in}{-.4in}%
{0pt}{14pt}%
{9in}{6in}%
%
\lispnarrowing = 0.25in
\tolerance = 700
\hfuzz = 1pt
\contentsrightmargin = 0pt
\defbodyindent = .4cm
}}
% Use @afourpaper to print on European A4 paper.
\def\afourpaper{{\globaldefs = 1
\parskip = 3pt plus 2pt minus 1pt
\textleading = 13.2pt
%
% Double-side printing via postscript on Laserjet 4050
% prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm.
% To change the settings for a different printer or situation, adjust
% \normaloffset until the front-side and back-side texts align. Then
% do the same for \bindingoffset. You can set these for testing in
% your texinfo source file like this:
% @tex
% \global\normaloffset = -6mm
% \global\bindingoffset = 10mm
% @end tex
\internalpagesizes{673.2pt}{160mm}% that's 51 lines
{\voffset}{\hoffset}%
{\bindingoffset}{44pt}%
{297mm}{210mm}%
%
\tolerance = 700
\hfuzz = 1pt
\contentsrightmargin = 0pt
\defbodyindent = 5mm
}}
% Use @afivepaper to print on European A5 paper.
% From romildo@urano.iceb.ufop.br, 2 July 2000.
% He also recommends making @example and @lisp be small.
\def\afivepaper{{\globaldefs = 1
\parskip = 2pt plus 1pt minus 0.1pt
\textleading = 12.5pt
%
\internalpagesizes{160mm}{120mm}%
{\voffset}{\hoffset}%
{\bindingoffset}{8pt}%
{210mm}{148mm}%
%
\lispnarrowing = 0.2in
\tolerance = 800
\hfuzz = 1.2pt
\contentsrightmargin = 0pt
\defbodyindent = 2mm
\tableindent = 12mm
}}
% A specific text layout, 24x15cm overall, intended for A4 paper.
\def\afourlatex{{\globaldefs = 1
\afourpaper
\internalpagesizes{237mm}{150mm}%
{\voffset}{4.6mm}%
{\bindingoffset}{7mm}%
{297mm}{210mm}%
%
% Must explicitly reset to 0 because we call \afourpaper.
\globaldefs = 0
}}
% Use @afourwide to print on A4 paper in landscape format.
\def\afourwide{{\globaldefs = 1
\afourpaper
\internalpagesizes{241mm}{165mm}%
{\voffset}{-2.95mm}%
{\bindingoffset}{7mm}%
{297mm}{210mm}%
\globaldefs = 0
}}
% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
% Perhaps we should allow setting the margins, \topskip, \parskip,
% and/or leading, also. Or perhaps we should compute them somehow.
%
\parseargdef\pagesizes{\pagesizesyyy #1,,\finish}
\def\pagesizesyyy#1,#2,#3\finish{{%
\setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi
\globaldefs = 1
%
\parskip = 3pt plus 2pt minus 1pt
\setleading{\textleading}%
%
\dimen0 = #1\relax
\advance\dimen0 by \voffset
%
\dimen2 = \hsize
\advance\dimen2 by \normaloffset
%
\internalpagesizes{#1}{\hsize}%
{\voffset}{\normaloffset}%
{\bindingoffset}{44pt}%
{\dimen0}{\dimen2}%
}}
% Set default to letter.
%
\letterpaper
\message{and turning on texinfo input format.}
\def^^L{\par} % remove \outer, so ^L can appear in an @comment
% DEL is a comment character, in case @c does not suffice.
\catcode`\^^? = 14
% Define macros to output various characters with catcode for normal text.
\catcode`\"=\other \def\normaldoublequote{"}
\catcode`\$=\other \def\normaldollar{$}%$ font-lock fix
\catcode`\+=\other \def\normalplus{+}
\catcode`\<=\other \def\normalless{<}
\catcode`\>=\other \def\normalgreater{>}
\catcode`\^=\other \def\normalcaret{^}
\catcode`\_=\other \def\normalunderscore{_}
\catcode`\|=\other \def\normalverticalbar{|}
\catcode`\~=\other \def\normaltilde{~}
% This macro is used to make a character print one way in \tt
% (where it can probably be output as-is), and another way in other fonts,
% where something hairier probably needs to be done.
%
% #1 is what to print if we are indeed using \tt; #2 is what to print
% otherwise. Since all the Computer Modern typewriter fonts have zero
% interword stretch (and shrink), and it is reasonable to expect all
% typewriter fonts to have this, we can check that font parameter.
%
\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}
% Same as above, but check for italic font. Actually this also catches
% non-italic slanted fonts since it is impossible to distinguish them from
% italic fonts. But since this is only used by $ and it uses \sl anyway
% this is not a problem.
\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}
% Turn off all special characters except @
% (and those which the user can use as if they were ordinary).
% Most of these we simply print from the \tt font, but for some, we can
% use math or other variants that look better in normal text.
\catcode`\"=\active
\def\activedoublequote{{\tt\char34}}
\let"=\activedoublequote
\catcode`\~=\active \def\activetilde{{\tt\char126}} \let~ = \activetilde
\chardef\hat=`\^
\catcode`\^=\active \def\activehat{{\tt \hat}} \let^ = \activehat
\catcode`\_=\active
\def_{\ifusingtt\normalunderscore\_}
\let\realunder=_
% Subroutine for the previous macro.
\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }
\catcode`\|=\active
\def|{{\tt\char124}}
\chardef \less=`\<
\catcode`\<=\active \def\activeless{{\tt \less}}\let< = \activeless
\chardef \gtr=`\>
\catcode`\>=\active \def\activegtr{{\tt \gtr}}\let> = \activegtr
\catcode`\+=\active \def+{{\tt \char 43}}
\catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
% used for headline/footline in the output routine, in case the page
% breaks in the middle of an @tex block.
\def\texinfochars{%
\let< = \activeless
\let> = \activegtr
\let~ = \activetilde
\let^ = \activehat
\markupsetuplqdefault \markupsetuprqdefault
\let\b = \strong
\let\i = \smartitalic
% in principle, all other definitions in \tex have to be undone too.
}
% If a .fmt file is being used, characters that might appear in a file
% name cannot be active until we have parsed the command line.
% So turn them off again, and have \everyjob (or @setfilename) turn them on.
% \otherifyactive is called near the end of this file.
\def\otherifyactive{\catcode`+=\other \catcode`\_=\other}
% Used sometimes to turn off (effectively) the active characters even after
% parsing them.
\def\turnoffactive{%
\normalturnoffactive
\otherbackslash
}
\catcode`\@=0
% \backslashcurfont outputs one backslash character in current font,
% as in \char`\\.
\global\chardef\backslashcurfont=`\\
\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work
% \realbackslash is an actual character `\' with catcode other, and
% \doublebackslash is two of them (for the pdf outlines).
{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}}
% In texinfo, backslash is an active character; it prints the backslash
% in fixed width font.
\catcode`\\=\active % @ for escape char from now on.
% The story here is that in math mode, the \char of \backslashcurfont
% ends up printing the roman \ from the math symbol font (because \char
% in math mode uses the \mathcode, and plain.tex sets
% \mathcode`\\="026E). It seems better for @backslashchar{} to always
% print a typewriter backslash, hence we use an explicit \mathchar,
% which is the decimal equivalent of "715c (class 7, e.g., use \fam;
% ignored family value; char position "5C). We can't use " for the
% usual hex value because it has already been made active.
@def@normalbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}}
@let@backslashchar = @normalbackslash % @backslashchar{} is for user documents.
% On startup, @fixbackslash assigns:
% @let \ = @normalbackslash
% \rawbackslash defines an active \ to do \backslashcurfont.
% \otherbackslash defines an active \ to be a literal `\' character with
% catcode other. We switch back and forth between these.
@gdef@rawbackslash{@let\=@backslashcurfont}
@gdef@otherbackslash{@let\=@realbackslash}
% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of
% the literal character `\'. Also revert - to its normal character, in
% case the active - from code has slipped in.
%
{@catcode`- = @active
@gdef@normalturnoffactive{%
@let-=@normaldash
@let"=@normaldoublequote
@let$=@normaldollar %$ font-lock fix
@let+=@normalplus
@let<=@normalless
@let>=@normalgreater
@let\=@normalbackslash
@let^=@normalcaret
@let_=@normalunderscore
@let|=@normalverticalbar
@let~=@normaltilde
@markupsetuplqdefault
@markupsetuprqdefault
@unsepspaces
}
}
% Make _ and + \other characters, temporarily.
% This is canceled by @fixbackslash.
@otherifyactive
% If a .fmt file is being used, we don't want the `\input texinfo' to show up.
% That is what \eatinput is for; after that, the `\' should revert to printing
% a backslash.
%
@gdef@eatinput input texinfo{@fixbackslash}
@global@let\ = @eatinput
% On the other hand, perhaps the file did not have a `\input texinfo'. Then
% the first `\' in the file would cause an error. This macro tries to fix
% that, assuming it is called before the first `\' could plausibly occur.
% Also turn back on active characters that might appear in the input
% file name, in case not using a pre-dumped format.
%
@gdef@fixbackslash{%
@ifx\@eatinput @let\ = @normalbackslash @fi
@catcode`+=@active
@catcode`@_=@active
}
% Say @foo, not \foo, in error messages.
@escapechar = `@@
% These (along with & and #) are made active for url-breaking, so need
% active definitions as the normal characters.
@def@normaldot{.}
@def@normalquest{?}
@def@normalslash{/}
% These look ok in all fonts, so just make them not special.
% @hashchar{} gets its own user-level command, because of #line.
@catcode`@& = @other @def@normalamp{&}
@catcode`@# = @other @def@normalhash{#}
@catcode`@% = @other @def@normalpercent{%}
@let @hashchar = @normalhash
@c Finally, make ` and ' active, so that txicodequoteundirected and
@c txicodequotebacktick work right in, e.g., @w{@code{`foo'}}. If we
@c don't make ` and ' active, @code will not get them as active chars.
@c Do this last of all since we use ` in the previous @catcode assignments.
@catcode`@'=@active
@catcode`@`=@active
@markupsetuplqdefault
@markupsetuprqdefault
@c Local variables:
@c eval: (add-hook 'write-file-hooks 'time-stamp)
@c page-delimiter: "^\\\\message"
@c time-stamp-start: "def\\\\texinfoversion{"
@c time-stamp-format: "%:y-%02m-%02d.%02H"
@c time-stamp-end: "}"
@c End:
@c vim:sw=2:
@ignore
arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115
@end ignore
readline-6.3/doc/version.texi 0000664 0000436 0000024 00000000331 12262617635 015104 0 ustar chet staff @ignore
Copyright (C) 1988-2014 Free Software Foundation, Inc.
@end ignore
@set EDITION 6.3
@set VERSION 6.3
@set UPDATED 6 January 2014
@set UPDATED-MONTH January 2014
@set LASTCHANGE Mon Jan 6 16:26:51 EST 2014
readline-6.3/doc/fdl.texi 0000644 0000436 0000000 00000056015 11155505164 014160 0 ustar chet wheel @c The GNU Free Documentation License.
@center Version 1.3, 3 November 2008
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
@uref{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@enumerate 0
@item
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document @dfn{free} in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document'', below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you''. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
PostScript or @acronym{PDF} designed for human modification. Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
@acronym{JPG}. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
PostScript or @acronym{PDF} produced by some word processors for
output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
The ``publisher'' means any person or entity that distributes copies
of the Document to the public.
A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements'',
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
@item
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@item
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@item
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
@item
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
@item
State on the Title page the name of the publisher of the
Modified Version, as the publisher.
@item
Preserve all the copyright notices of the Document.
@item
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
@item
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
@item
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
@item
Include an unaltered copy of this License.
@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
@item
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
@item
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
@item
Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
Do not retitle any existing section to be Entitled ``Endorsements'' or
to conflict in title with any Invariant Section.
@item
Preserve any Warranty Disclaimers.
@end enumerate
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@item
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
and any sections Entitled ``Dedications''. You must delete all
sections Entitled ``Endorsements.''
@item
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@item
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
@item
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled ``Acknowledgements'',
``Dedications'', or ``History'', the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
@item
TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
@item
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
@uref{http://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
@item
RELICENSING
``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A
``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
site means any set of copyrightable works thus published on the MMC
site.
``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
``Incorporate'' means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is ``eligible for relicensing'' if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
@end enumerate
@page
@heading ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
@smallexample
@group
Copyright (C) @var{year} @var{your name}.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end group
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with@dots{}Texts.'' line with this:
@smallexample
@group
with the Invariant Sections being @var{list their titles}, with
the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
being @var{list}.
@end group
@end smallexample
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
readline-6.3/doc/rlman.texi 0000664 0000436 0000024 00000004523 12262620107 014523 0 ustar chet staff \input texinfo @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename readline.info
@settitle GNU Readline Library
@include version.texi
@comment %**end of header (This is for running Texinfo on a region.)
@synindex vr fn
@copying
This manual describes the GNU Readline Library
(version @value{VERSION}, @value{UPDATED}), a library which aids in the
consistency of user interface across discrete programs which provide
a command line interface.
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@dircategory Libraries
@direntry
* Readline: (readline). The GNU readline library API.
@end direntry
@titlepage
@title GNU Readline Library
@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}.
@subtitle @value{UPDATED-MONTH}
@author Chet Ramey, Case Western Reserve University
@author Brian Fox, Free Software Foundation
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU Readline Library
This document describes the GNU Readline Library, a utility which aids
in the consistency of user interface across discrete programs which
provide a command line interface.
The Readline home page is @url{http://www.gnu.org/software/readline/}.
@menu
* Command Line Editing:: GNU Readline User's Manual.
* Programming with GNU Readline:: GNU Readline Programmer's Manual.
* GNU Free Documentation License:: License for copying this manual.
* Concept Index:: Index of concepts described in this manual.
* Function and Variable Index:: Index of externally visible functions
and variables.
@end menu
@end ifnottex
@include rluser.texi
@include rltech.texi
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function and Variable Index
@unnumbered Function and Variable Index
@printindex fn
@bye
readline-6.3/doc/rltech.texi 0000664 0000436 0000024 00000274521 12274515703 014712 0 ustar chet staff @comment %**start of header (This is for running Texinfo on a region.)
@setfilename rltech.info
@comment %**end of header (This is for running Texinfo on a region.)
@ifinfo
This document describes the GNU Readline Library, a utility for aiding
in the consistency of user interface across discrete programs that need
to provide a command line interface.
Copyright (C) 1988--2014 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
pare 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 Foundation.
@end ifinfo
@node Programming with GNU Readline
@chapter Programming with GNU Readline
This chapter describes the interface between the @sc{gnu} Readline Library and
other programs. If you are a programmer, and you wish to include the
features found in @sc{gnu} Readline
such as completion, line editing, and interactive history manipulation
in your own programs, this section is for you.
@menu
* Basic Behavior:: Using the default behavior of Readline.
* Custom Functions:: Adding your own functions to Readline.
* Readline Variables:: Variables accessible to custom
functions.
* Readline Convenience Functions:: Functions which Readline supplies to
aid in writing your own custom
functions.
* Readline Signal Handling:: How Readline behaves when it receives signals.
* Custom Completers:: Supplanting or supplementing Readline's
completion functions.
@end menu
@node Basic Behavior
@section Basic Behavior
Many programs provide a command line interface, such as @code{mail},
@code{ftp}, and @code{sh}. For such programs, the default behaviour of
Readline is sufficient. This section describes how to use Readline in
the simplest way possible, perhaps to replace calls in your code to
@code{gets()} or @code{fgets()}.
@findex readline
@cindex readline, function
The function @code{readline()} prints a prompt @var{prompt}
and then reads and returns a single line of text from the user.
If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
The line @code{readline} returns is allocated with @code{malloc()};
the caller should @code{free()} the line when it has finished with it.
The declaration for @code{readline} in ANSI C is
@example
@code{char *readline (const char *@var{prompt});}
@end example
@noindent
So, one might say
@example
@code{char *line = readline ("Enter a line: ");}
@end example
@noindent
in order to read a line of text from the user.
The line returned has the final newline removed, so only the
text remains.
If @code{readline} encounters an @code{EOF} while reading the line, and the
line is empty at that point, then @code{(char *)NULL} is returned.
Otherwise, the line is ended just as if a newline had been typed.
If you want the user to be able to get at the line later, (with
@key{C-p} for example), you must call @code{add_history()} to save the
line away in a @dfn{history} list of such lines.
@example
@code{add_history (line)};
@end example
@noindent
For full details on the GNU History Library, see the associated manual.
It is preferable to avoid saving empty lines on the history list, since
users rarely have a burning need to reuse a blank line. Here is
a function which usefully replaces the standard @code{gets()} library
function, and has the advantage of no static buffer to overflow:
@example
/* A static variable for holding the line. */
static char *line_read = (char *)NULL;
/* Read a string, and return a pointer to it.
Returns NULL on EOF. */
char *
rl_gets ()
@{
/* If the buffer has already been allocated,
return the memory to the free pool. */
if (line_read)
@{
free (line_read);
line_read = (char *)NULL;
@}
/* Get a line from the user. */
line_read = readline ("");
/* If the line has any text in it,
save it on the history. */
if (line_read && *line_read)
add_history (line_read);
return (line_read);
@}
@end example
This function gives the user the default behaviour of @key{TAB}
completion: completion on file names. If you do not want Readline to
complete on filenames, you can change the binding of the @key{TAB} key
with @code{rl_bind_key()}.
@example
@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
@end example
@code{rl_bind_key()} takes two arguments: @var{key} is the character that
you want to bind, and @var{function} is the address of the function to
call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()}
makes @key{TAB} insert itself.
@code{rl_bind_key()} returns non-zero if @var{key} is not a valid
ASCII character code (between 0 and 255).
Thus, to disable the default @key{TAB} behavior, the following suffices:
@example
@code{rl_bind_key ('\t', rl_insert);}
@end example
This code should be executed once at the start of your program; you
might write a function called @code{initialize_readline()} which
performs this and other desired initializations, such as installing
custom completers (@pxref{Custom Completers}).
@node Custom Functions
@section Custom Functions
Readline provides many functions for manipulating the text of
the line, but it isn't possible to anticipate the needs of all
programs. This section describes the various functions and variables
defined within the Readline library which allow a user program to add
customized functionality to Readline.
Before declaring any functions that customize Readline's behavior, or
using any functionality Readline provides in other code, an
application writer should include the file @code{}
in any file that uses Readline's features. Since some of the definitions
in @code{readline.h} use the @code{stdio} library, the file
@code{} should be included before @code{readline.h}.
@code{readline.h} defines a C preprocessor variable that should
be treated as an integer, @code{RL_READLINE_VERSION}, which may
be used to conditionally compile application code depending on
the installed Readline version. The value is a hexadecimal
encoding of the major and minor version numbers of the library,
of the form 0x@var{MMmm}. @var{MM} is the two-digit major
version number; @var{mm} is the two-digit minor version number.
For Readline 4.2, for example, the value of
@code{RL_READLINE_VERSION} would be @code{0x0402}.
@menu
* Readline Typedefs:: C declarations to make code readable.
* Function Writing:: Variables and calling conventions.
@end menu
@node Readline Typedefs
@subsection Readline Typedefs
For readability, we declare a number of new object types, all pointers
to functions.
The reason for declaring these new types is to make it easier to write
code describing pointers to C functions with appropriately prototyped
arguments and return values.
For instance, say we want to declare a variable @var{func} as a pointer
to a function which takes two @code{int} arguments and returns an
@code{int} (this is the type of all of the Readline bindable functions).
Instead of the classic C declaration
@code{int (*func)();}
@noindent
or the ANSI-C style declaration
@code{int (*func)(int, int);}
@noindent
we may write
@code{rl_command_func_t *func;}
The full list of function pointer types available is
@table @code
@item typedef int rl_command_func_t (int, int);
@item typedef char *rl_compentry_func_t (const char *, int);
@item typedef char **rl_completion_func_t (const char *, int, int);
@item typedef char *rl_quote_func_t (char *, int, char *);
@item typedef char *rl_dequote_func_t (char *, int);
@item typedef int rl_compignore_func_t (char **);
@item typedef void rl_compdisp_func_t (char **, int, int);
@item typedef int rl_hook_func_t (void);
@item typedef int rl_getc_func_t (FILE *);
@item typedef int rl_linebuf_func_t (char *, int);
@item typedef int rl_intfunc_t (int);
@item #define rl_ivoidfunc_t rl_hook_func_t
@item typedef int rl_icpfunc_t (char *);
@item typedef int rl_icppfunc_t (char **);
@item typedef void rl_voidfunc_t (void);
@item typedef void rl_vintfunc_t (int);
@item typedef void rl_vcpfunc_t (char *);
@item typedef void rl_vcppfunc_t (char **);
@end table
@node Function Writing
@subsection Writing a New Function
In order to write new functions for Readline, you need to know the
calling conventions for keyboard-invoked functions, and the names of the
variables that describe the current state of the line read so far.
The calling sequence for a command @code{foo} looks like
@example
@code{int foo (int count, int key)}
@end example
@noindent
where @var{count} is the numeric argument (or 1 if defaulted) and
@var{key} is the key that invoked this function.
It is completely up to the function as to what should be done with the
numeric argument. Some functions use it as a repeat count, some
as a flag, and others to choose alternate behavior (refreshing the current
line as opposed to refreshing the screen, for example). Some choose to
ignore it. In general, if a
function uses the numeric argument as a repeat count, it should be able
to do something useful with both negative and positive arguments.
At the very least, it should be aware that it can be passed a
negative argument.
A command function should return 0 if its action completes successfully,
and a non-zero value if some error occurs.
This is the convention obeyed by all of the builtin Readline bindable
command functions.
@node Readline Variables
@section Readline Variables
These variables are available to function writers.
@deftypevar {char *} rl_line_buffer
This is the line gathered so far. You are welcome to modify the
contents of the line, but see @ref{Allowing Undoing}. The
function @code{rl_extend_line_buffer} is available to increase
the memory allocated to @code{rl_line_buffer}.
@end deftypevar
@deftypevar int rl_point
The offset of the current cursor position in @code{rl_line_buffer}
(the @emph{point}).
@end deftypevar
@deftypevar int rl_end
The number of characters present in @code{rl_line_buffer}. When
@code{rl_point} is at the end of the line, @code{rl_point} and
@code{rl_end} are equal.
@end deftypevar
@deftypevar int rl_mark
The @var{mark} (saved position) in the current line. If set, the mark
and point define a @emph{region}.
@end deftypevar
@deftypevar int rl_done
Setting this to a non-zero value causes Readline to return the current
line immediately.
@end deftypevar
@deftypevar int rl_num_chars_to_read
Setting this to a positive value before calling @code{readline()} causes
Readline to return after accepting that many characters, rather
than reading up to a character bound to @code{accept-line}.
@end deftypevar
@deftypevar int rl_pending_input
Setting this to a value makes it the next keystroke read. This is a
way to stuff a single character into the input stream.
@end deftypevar
@deftypevar int rl_dispatching
Set to a non-zero value if a function is being called from a key binding;
zero otherwise. Application functions can test this to discover whether
they were called directly or by Readline's dispatching mechanism.
@end deftypevar
@deftypevar int rl_erase_empty_line
Setting this to a non-zero value causes Readline to completely erase
the current line, including any prompt, any time a newline is typed as
the only character on an otherwise-empty line. The cursor is moved to
the beginning of the newly-blank line.
@end deftypevar
@deftypevar {char *} rl_prompt
The prompt Readline uses. This is set from the argument to
@code{readline()}, and should not be assigned to directly.
The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
be used to modify the prompt string after calling @code{readline()}.
@end deftypevar
@deftypevar {char *} rl_display_prompt
The string displayed as the prompt. This is usually identical to
@var{rl_prompt}, but may be changed temporarily by functions that
use the prompt string as a message area, such as incremental search.
@end deftypevar
@deftypevar int rl_already_prompted
If an application wishes to display the prompt itself, rather than have
Readline do it the first time @code{readline()} is called, it should set
this variable to a non-zero value after displaying the prompt.
The prompt must also be passed as the argument to @code{readline()} so
the redisplay functions can update the display properly.
The calling application is responsible for managing the value; Readline
never sets it.
@end deftypevar
@deftypevar {const char *} rl_library_version
The version number of this revision of the library.
@end deftypevar
@deftypevar int rl_readline_version
An integer encoding the current version of the library. The encoding is
of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
number, and @var{mm} is the two-digit minor version number.
For example, for Readline-4.2, @code{rl_readline_version} would have the
value 0x0402.
@end deftypevar
@deftypevar {int} rl_gnu_readline_p
Always set to 1, denoting that this is @sc{gnu} readline rather than some
emulation.
@end deftypevar
@deftypevar {const char *} rl_terminal_name
The terminal type, used for initialization. If not set by the application,
Readline sets this to the value of the @env{TERM} environment variable
the first time it is called.
@end deftypevar
@deftypevar {const char *} rl_readline_name
This variable is set to a unique name by each application using Readline.
The value allows conditional parsing of the inputrc file
(@pxref{Conditional Init Constructs}).
@end deftypevar
@deftypevar {FILE *} rl_instream
The stdio stream from which Readline reads input.
If @code{NULL}, Readline defaults to @var{stdin}.
@end deftypevar
@deftypevar {FILE *} rl_outstream
The stdio stream to which Readline performs output.
If @code{NULL}, Readline defaults to @var{stdout}.
@end deftypevar
@deftypevar int rl_prefer_env_winsize
If non-zero, Readline gives values found in the @env{LINES} and
@env{COLUMNS} environment variables greater precedence than values fetched
from the kernel when computing the screen dimensions.
@end deftypevar
@deftypevar {rl_command_func_t *} rl_last_func
The address of the last command function Readline executed. May be used to
test whether or not a function is being executed twice in succession, for
example.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_startup_hook
If non-zero, this is the address of a function to call just
before @code{readline} prints the first prompt.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_pre_input_hook
If non-zero, this is the address of a function to call after
the first prompt has been printed and just before @code{readline}
starts reading input characters.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_event_hook
If non-zero, this is the address of a function to call periodically
when Readline is waiting for terminal input.
By default, this will be called at most ten times a second if there
is no keyboard input.
@end deftypevar
@deftypevar {rl_getc_func_t *} rl_getc_function
If non-zero, Readline will call indirectly through this pointer
to get a character from the input stream. By default, it is set to
@code{rl_getc}, the default Readline character input function
(@pxref{Character Input}).
In general, an application that sets @var{rl_getc_function} should consider
setting @var{rl_input_available_hook} as well.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_signal_event_hook
If non-zero, this is the address of a function to call if a read system
call is interrupted when Readline is reading terminal input.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_input_available_hook
If non-zero, Readline will use this function's return value when it needs
to determine whether or not there is available input on the current input
source.
The default hook checks @code{rl_instream}; if an application is using a
different input source, it should set the hook appropriately.
Readline queries for available input when implementing intra-key-sequence
timeouts during input and incremental searches.
This may use an application-specific timeout before returning a value;
Readline uses the value passed to @code{rl_set_keyboard_input_timeout()}
or the value of the user-settable @var{keyseq-timeout} variable.
This is designed for use by applications using Readline's callback interface
(@pxref{Alternate Interface}), which may not use the traditional
@code{read(2)} and file descriptor interface, or other applications using
a different input mechanism.
If an application uses an input mechanism or hook that can potentially exceed
the value of @var{keyseq-timeout}, it should increase the timeout or set
this hook appropriately even when not using the callback interface.
In general, an application that sets @var{rl_getc_function} should consider
setting @var{rl_input_available_hook} as well.
@end deftypevar
@deftypevar {rl_voidfunc_t *} rl_redisplay_function
If non-zero, Readline will call indirectly through this pointer
to update the display with the current contents of the editing buffer.
By default, it is set to @code{rl_redisplay}, the default Readline
redisplay function (@pxref{Redisplay}).
@end deftypevar
@deftypevar {rl_vintfunc_t *} rl_prep_term_function
If non-zero, Readline will call indirectly through this pointer
to initialize the terminal. The function takes a single argument, an
@code{int} flag that says whether or not to use eight-bit characters.
By default, this is set to @code{rl_prep_terminal}
(@pxref{Terminal Management}).
@end deftypevar
@deftypevar {rl_voidfunc_t *} rl_deprep_term_function
If non-zero, Readline will call indirectly through this pointer
to reset the terminal. This function should undo the effects of
@code{rl_prep_term_function}.
By default, this is set to @code{rl_deprep_terminal}
(@pxref{Terminal Management}).
@end deftypevar
@deftypevar {Keymap} rl_executing_keymap
This variable is set to the keymap (@pxref{Keymaps}) in which the
currently executing readline function was found.
@end deftypevar
@deftypevar {Keymap} rl_binding_keymap
This variable is set to the keymap (@pxref{Keymaps}) in which the
last key binding occurred.
@end deftypevar
@deftypevar {char *} rl_executing_macro
This variable is set to the text of any currently-executing macro.
@end deftypevar
@deftypevar int rl_executing_key
The key that caused the dispatch to the currently-executing Readline function.
@end deftypevar
@deftypevar {char *} rl_executing_keyseq
The full key sequence that caused the dispatch to the currently-executing
Readline function.
@end deftypevar
@deftypevar int rl_key_sequence_length
The number of characters in @var{rl_executing_keyseq}.
@end deftypevar
@deftypevar {int} rl_readline_state
A variable with bit values that encapsulate the current Readline state.
A bit is set with the @code{RL_SETSTATE} macro, and unset with the
@code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test
whether a particular state bit is set. Current state bits include:
@table @code
@item RL_STATE_NONE
Readline has not yet been called, nor has it begun to initialize.
@item RL_STATE_INITIALIZING
Readline is initializing its internal data structures.
@item RL_STATE_INITIALIZED
Readline has completed its initialization.
@item RL_STATE_TERMPREPPED
Readline has modified the terminal modes to do its own input and redisplay.
@item RL_STATE_READCMD
Readline is reading a command from the keyboard.
@item RL_STATE_METANEXT
Readline is reading more input after reading the meta-prefix character.
@item RL_STATE_DISPATCHING
Readline is dispatching to a command.
@item RL_STATE_MOREINPUT
Readline is reading more input while executing an editing command.
@item RL_STATE_ISEARCH
Readline is performing an incremental history search.
@item RL_STATE_NSEARCH
Readline is performing a non-incremental history search.
@item RL_STATE_SEARCH
Readline is searching backward or forward through the history for a string.
@item RL_STATE_NUMERICARG
Readline is reading a numeric argument.
@item RL_STATE_MACROINPUT
Readline is currently getting its input from a previously-defined keyboard
macro.
@item RL_STATE_MACRODEF
Readline is currently reading characters defining a keyboard macro.
@item RL_STATE_OVERWRITE
Readline is in overwrite mode.
@item RL_STATE_COMPLETING
Readline is performing word completion.
@item RL_STATE_SIGHANDLER
Readline is currently executing the readline signal handler.
@item RL_STATE_UNDOING
Readline is performing an undo.
@item RL_STATE_INPUTPENDING
Readline has input pending due to a call to @code{rl_execute_next()}.
@item RL_STATE_TTYCSAVED
Readline has saved the values of the terminal's special characters.
@item RL_STATE_CALLBACK
Readline is currently using the alternate (callback) interface
(@pxref{Alternate Interface}).
@item RL_STATE_VIMOTION
Readline is reading the argument to a vi-mode "motion" command.
@item RL_STATE_MULTIKEY
Readline is reading a multiple-keystroke command.
@item RL_STATE_VICMDONCE
Readline has entered vi command (movement) mode at least one time during
the current call to @code{readline()}.
@item RL_STATE_DONE
Readline has read a key sequence bound to @code{accept-line}
and is about to return the line to the caller.
@end table
@end deftypevar
@deftypevar {int} rl_explicit_arg
Set to a non-zero value if an explicit numeric argument was specified by
the user. Only valid in a bindable command function.
@end deftypevar
@deftypevar {int} rl_numeric_arg
Set to the value of any numeric argument explicitly specified by the user
before executing the current Readline function. Only valid in a bindable
command function.
@end deftypevar
@deftypevar {int} rl_editing_mode
Set to a value denoting Readline's current editing mode. A value of
@var{1} means Readline is currently in emacs mode; @var{0}
means that vi mode is active.
@end deftypevar
@node Readline Convenience Functions
@section Readline Convenience Functions
@menu
* Function Naming:: How to give a function you write a name.
* Keymaps:: Making keymaps.
* Binding Keys:: Changing Keymaps.
* Associating Function Names and Bindings:: Translate function names to
key sequences.
* Allowing Undoing:: How to make your functions undoable.
* Redisplay:: Functions to control line display.
* Modifying Text:: Functions to modify @code{rl_line_buffer}.
* Character Input:: Functions to read keyboard input.
* Terminal Management:: Functions to manage terminal settings.
* Utility Functions:: Generally useful functions and hooks.
* Miscellaneous Functions:: Functions that don't fall into any category.
* Alternate Interface:: Using Readline in a `callback' fashion.
* A Readline Example:: An example Readline function.
* Alternate Interface Example:: An example program using the alternate interface.
@end menu
@node Function Naming
@subsection Naming a Function
The user can dynamically change the bindings of keys while using
Readline. This is done by representing the function with a descriptive
name. The user is able to type the descriptive name when referring to
the function. Thus, in an init file, one might find
@example
Meta-Rubout: backward-kill-word
@end example
This binds the keystroke @key{Meta-Rubout} to the function
@emph{descriptively} named @code{backward-kill-word}. You, as the
programmer, should bind the functions you write to descriptive names as
well. Readline provides a function for doing that:
@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
Add @var{name} to the list of named functions. Make @var{function} be
the function that gets called. If @var{key} is not -1, then bind it to
@var{function} using @code{rl_bind_key()}.
@end deftypefun
Using this function alone is sufficient for most applications.
It is the recommended way to add a few functions to the default
functions that Readline has built in.
If you need to do something other than adding a function to Readline,
you may need to use the underlying functions described below.
@node Keymaps
@subsection Selecting a Keymap
Key bindings take place on a @dfn{keymap}. The keymap is the
association between the keys that the user types and the functions that
get run. You can make your own keymaps, copy existing keymaps, and tell
Readline which keymap to use.
@deftypefun Keymap rl_make_bare_keymap (void)
Returns a new, empty keymap. The space for the keymap is allocated with
@code{malloc()}; the caller should free it by calling
@code{rl_free_keymap()} when done.
@end deftypefun
@deftypefun Keymap rl_copy_keymap (Keymap map)
Return a new keymap which is a copy of @var{map}.
@end deftypefun
@deftypefun Keymap rl_make_keymap (void)
Return a new keymap with the printing characters bound to rl_insert,
the lowercase Meta characters bound to run their equivalents, and
the Meta digits bound to produce numeric arguments.
@end deftypefun
@deftypefun void rl_discard_keymap (Keymap keymap)
Free the storage associated with the data in @var{keymap}.
The caller should free @var{keymap}.
@end deftypefun
@deftypefun void rl_free_keymap (Keymap keymap)
Free all storage associated with @var{keymap}. This calls
@code{rl_discard_keymap} to free subordindate keymaps and macros.
@end deftypefun
Readline has several internal keymaps. These functions allow you to
change which keymap is active.
@deftypefun Keymap rl_get_keymap (void)
Returns the currently active keymap.
@end deftypefun
@deftypefun void rl_set_keymap (Keymap keymap)
Makes @var{keymap} the currently active keymap.
@end deftypefun
@deftypefun Keymap rl_get_keymap_by_name (const char *name)
Return the keymap matching @var{name}. @var{name} is one which would
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun
@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
Return the name matching @var{keymap}. @var{name} is one which would
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun
@node Binding Keys
@subsection Binding Keys
Key sequences are associate with functions through the keymap.
Readline has several internal keymaps: @code{emacs_standard_keymap},
@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
@code{emacs_standard_keymap} is the default, and the examples in
this manual assume that.
Since @code{readline()} installs a set of default key bindings the first
time it is called, there is always the danger that a custom binding
installed before the first call to @code{readline()} will be overridden.
An alternate mechanism is to install custom key bindings in an
initialization function assigned to the @code{rl_startup_hook} variable
(@pxref{Readline Variables}).
These functions manage key bindings.
@deftypefun int rl_bind_key (int key, rl_command_func_t *function)
Binds @var{key} to @var{function} in the currently active keymap.
Returns non-zero in the case of an invalid @var{key}.
@end deftypefun
@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
Bind @var{key} to @var{function} in @var{map}.
Returns non-zero in the case of an invalid @var{key}.
@end deftypefun
@deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function)
Binds @var{key} to @var{function} if it is not already bound in the
currently active keymap.
Returns non-zero in the case of an invalid @var{key} or if @var{key} is
already bound.
@end deftypefun
@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
Binds @var{key} to @var{function} if it is not already bound in @var{map}.
Returns non-zero in the case of an invalid @var{key} or if @var{key} is
already bound.
@end deftypefun
@deftypefun int rl_unbind_key (int key)
Bind @var{key} to the null function in the currently active keymap.
Returns non-zero in case of error.
@end deftypefun
@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
Bind @var{key} to the null function in @var{map}.
Returns non-zero in case of error.
@end deftypefun
@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
Unbind all keys that execute @var{function} in @var{map}.
@end deftypefun
@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
Unbind all keys that are bound to @var{command} in @var{map}.
@end deftypefun
@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
Bind the key sequence represented by the string @var{keyseq} to the function
@var{function}, beginning in the current keymap.
This makes new keymaps as necessary.
The return value is non-zero if @var{keyseq} is invalid.
@end deftypefun
@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
Bind the key sequence represented by the string @var{keyseq} to the function
@var{function}. This makes new keymaps as necessary.
Initial bindings are performed in @var{map}.
The return value is non-zero if @var{keyseq} is invalid.
@end deftypefun
@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
Equivalent to @code{rl_bind_keyseq_in_map}.
@end deftypefun
@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
Binds @var{keyseq} to @var{function} if it is not already bound in the
currently active keymap.
Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
already bound.
@end deftypefun
@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
already bound.
@end deftypefun
@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
Bind the key sequence represented by the string @var{keyseq} to the arbitrary
pointer @var{data}. @var{type} says what kind of data is pointed to by
@var{data}; this can be a function (@code{ISFUNC}), a macro
(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
necessary. The initial keymap in which to do bindings is @var{map}.
@end deftypefun
@deftypefun int rl_parse_and_bind (char *line)
Parse @var{line} as if it had been read from the @code{inputrc} file and
perform any key bindings and variable assignments found
(@pxref{Readline Init File}).
@end deftypefun
@deftypefun int rl_read_init_file (const char *filename)
Read keybindings and variable assignments from @var{filename}
(@pxref{Readline Init File}).
@end deftypefun
@node Associating Function Names and Bindings
@subsection Associating Function Names and Bindings
These functions allow you to find out what keys invoke named functions
and the functions invoked by a particular key sequence. You may also
associate a new function name with an arbitrary function.
@deftypefun {rl_command_func_t *} rl_named_function (const char *name)
Return the function with name @var{name}.
@end deftypefun
@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
Return the function invoked by @var{keyseq} in keymap @var{map}.
If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
not @code{NULL}, the type of the object is returned in the @code{int} variable
it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
@end deftypefun
@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
Return an array of strings representing the key sequences used to
invoke @var{function} in the current keymap.
@end deftypefun
@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
Return an array of strings representing the key sequences used to
invoke @var{function} in the keymap @var{map}.
@end deftypefun
@deftypefun void rl_function_dumper (int readable)
Print the readline function names and the key sequences currently
bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
the list is formatted in such a way that it can be made part of an
@code{inputrc} file and re-read.
@end deftypefun
@deftypefun void rl_list_funmap_names (void)
Print the names of all bindable Readline functions to @code{rl_outstream}.
@end deftypefun
@deftypefun {const char **} rl_funmap_names (void)
Return a NULL terminated array of known function names. The array is
sorted. The array itself is allocated, but not the strings inside. You
should free the array, but not the pointers, using @code{free} or
@code{rl_free} when you are done.
@end deftypefun
@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
Add @var{name} to the list of bindable Readline command names, and make
@var{function} the function to be called when @var{name} is invoked.
@end deftypefun
@node Allowing Undoing
@subsection Allowing Undoing
Supporting the undo command is a painless thing, and makes your
functions much more useful. It is certainly easy to try
something if you know you can undo it.
If your function simply inserts text once, or deletes text once, and
uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
undoing is already done for you automatically.
If you do multiple insertions or multiple deletions, or any combination
of these operations, you should group them together into one operation.
This is done with @code{rl_begin_undo_group()} and
@code{rl_end_undo_group()}.
The types of events that can be undone are:
@smallexample
enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
@end smallexample
Notice that @code{UNDO_DELETE} means to insert some text, and
@code{UNDO_INSERT} means to delete some text. That is, the undo code
tells what to undo, not how to undo it. @code{UNDO_BEGIN} and
@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
@code{rl_end_undo_group()}.
@deftypefun int rl_begin_undo_group (void)
Begins saving undo information in a group construct. The undo
information usually comes from calls to @code{rl_insert_text()} and
@code{rl_delete_text()}, but could be the result of calls to
@code{rl_add_undo()}.
@end deftypefun
@deftypefun int rl_end_undo_group (void)
Closes the current undo group started with @code{rl_begin_undo_group
()}. There should be one call to @code{rl_end_undo_group()}
for each call to @code{rl_begin_undo_group()}.
@end deftypefun
@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
Remember how to undo an event (according to @var{what}). The affected
text runs from @var{start} to @var{end}, and encompasses @var{text}.
@end deftypefun
@deftypefun void rl_free_undo_list (void)
Free the existing undo list.
@end deftypefun
@deftypefun int rl_do_undo (void)
Undo the first thing on the undo list. Returns @code{0} if there was
nothing to undo, non-zero if something was undone.
@end deftypefun
Finally, if you neither insert nor delete text, but directly modify the
existing text (e.g., change its case), call @code{rl_modifying()}
once, just before you modify the text. You must supply the indices of
the text range that you are going to modify.
@deftypefun int rl_modifying (int start, int end)
Tell Readline to save the text between @var{start} and @var{end} as a
single undo unit. It is assumed that you will subsequently modify
that text.
@end deftypefun
@node Redisplay
@subsection Redisplay
@deftypefun void rl_redisplay (void)
Change what's displayed on the screen to reflect the current contents
of @code{rl_line_buffer}.
@end deftypefun
@deftypefun int rl_forced_update_display (void)
Force the line to be updated and redisplayed, whether or not
Readline thinks the screen display is correct.
@end deftypefun
@deftypefun int rl_on_new_line (void)
Tell the update functions that we have moved onto a new (empty) line,
usually after outputting a newline.
@end deftypefun
@deftypefun int rl_on_new_line_with_prompt (void)
Tell the update functions that we have moved onto a new line, with
@var{rl_prompt} already displayed.
This could be used by applications that want to output the prompt string
themselves, but still need Readline to know the prompt string length for
redisplay.
It should be used after setting @var{rl_already_prompted}.
@end deftypefun
@deftypefun int rl_reset_line_state (void)
Reset the display state to a clean state and redisplay the current line
starting on a new line.
@end deftypefun
@deftypefun int rl_crlf (void)
Move the cursor to the start of the next screen line.
@end deftypefun
@deftypefun int rl_show_char (int c)
Display character @var{c} on @code{rl_outstream}.
If Readline has not been set to display meta characters directly, this
will convert meta characters to a meta-prefixed key sequence.
This is intended for use by applications which wish to do their own
redisplay.
@end deftypefun
@deftypefun int rl_message (const char *, @dots{})
The arguments are a format string as would be supplied to @code{printf},
possibly containing conversion specifications such as @samp{%d}, and
any additional arguments necessary to satisfy the conversion specifications.
The resulting string is displayed in the @dfn{echo area}. The echo area
is also used to display numeric arguments and search strings.
You should call @code{rl_save_prompt} to save the prompt information
before calling this function.
@end deftypefun
@deftypefun int rl_clear_message (void)
Clear the message in the echo area. If the prompt was saved with a call to
@code{rl_save_prompt} before the last call to @code{rl_message},
call @code{rl_restore_prompt} before calling this function.
@end deftypefun
@deftypefun void rl_save_prompt (void)
Save the local Readline prompt display state in preparation for
displaying a new message in the message area with @code{rl_message()}.
@end deftypefun
@deftypefun void rl_restore_prompt (void)
Restore the local Readline prompt display state saved by the most
recent call to @code{rl_save_prompt}.
if @code{rl_save_prompt} was called to save the prompt before a call
to @code{rl_message}, this function should be called before the
corresponding call to @code{rl_clear_message}.
@end deftypefun
@deftypefun int rl_expand_prompt (char *prompt)
Expand any special character sequences in @var{prompt} and set up the
local Readline prompt redisplay variables.
This function is called by @code{readline()}. It may also be called to
expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
function or @code{rl_already_prompted} variable is used.
It returns the number of visible characters on the last line of the
(possibly multi-line) prompt.
Applications may indicate that the prompt contains characters that take
up no physical screen space when displayed by bracketing a sequence of
such characters with the special markers @code{RL_PROMPT_START_IGNORE}
and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}. This may
be used to embed terminal-specific escape sequences in prompts.
@end deftypefun
@deftypefun int rl_set_prompt (const char *prompt)
Make Readline use @var{prompt} for subsequent redisplay. This calls
@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
to the result.
@end deftypefun
@node Modifying Text
@subsection Modifying Text
@deftypefun int rl_insert_text (const char *text)
Insert @var{text} into the line at the current cursor position.
Returns the number of characters inserted.
@end deftypefun
@deftypefun int rl_delete_text (int start, int end)
Delete the text between @var{start} and @var{end} in the current line.
Returns the number of characters deleted.
@end deftypefun
@deftypefun {char *} rl_copy_text (int start, int end)
Return a copy of the text between @var{start} and @var{end} in
the current line.
@end deftypefun
@deftypefun int rl_kill_text (int start, int end)
Copy the text between @var{start} and @var{end} in the current line
to the kill ring, appending or prepending to the last kill if the
last command was a kill command. The text is deleted.
If @var{start} is less than @var{end},
the text is appended, otherwise prepended. If the last command was
not a kill, a new kill ring slot is used.
@end deftypefun
@deftypefun int rl_push_macro_input (char *macro)
Cause @var{macro} to be inserted into the line, as if it had been invoked
by a key bound to a macro. Not especially useful; use
@code{rl_insert_text()} instead.
@end deftypefun
@node Character Input
@subsection Character Input
@deftypefun int rl_read_key (void)
Return the next character available from Readline's current input stream.
This handles input inserted into
the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
While waiting for input, this function will call any function assigned to
the @code{rl_event_hook} variable.
@end deftypefun
@deftypefun int rl_getc (FILE *stream)
Return the next character available from @var{stream}, which is assumed to
be the keyboard.
@end deftypefun
@deftypefun int rl_stuff_char (int c)
Insert @var{c} into the Readline input stream. It will be "read"
before Readline attempts to read characters from the terminal with
@code{rl_read_key()}. Up to 512 characters may be pushed back.
@code{rl_stuff_char} returns 1 if the character was successfully inserted;
0 otherwise.
@end deftypefun
@deftypefun int rl_execute_next (int c)
Make @var{c} be the next command to be executed when @code{rl_read_key()}
is called. This sets @var{rl_pending_input}.
@end deftypefun
@deftypefun int rl_clear_pending_input (void)
Unset @var{rl_pending_input}, effectively negating the effect of any
previous call to @code{rl_execute_next()}. This works only if the
pending input has not already been read with @code{rl_read_key()}.
@end deftypefun
@deftypefun int rl_set_keyboard_input_timeout (int u)
While waiting for keyboard input in @code{rl_read_key()}, Readline will
wait for @var{u} microseconds for input before calling any function
assigned to @code{rl_event_hook}. @var{u} must be greater than or equal
to zero (a zero-length timeout is equivalent to a poll).
The default waiting period is one-tenth of a second.
Returns the old timeout value.
@end deftypefun
@node Terminal Management
@subsection Terminal Management
@deftypefun void rl_prep_terminal (int meta_flag)
Modify the terminal settings for Readline's use, so @code{readline()}
can read a single character at a time from the keyboard.
The @var{meta_flag} argument should be non-zero if Readline should
read eight-bit input.
@end deftypefun
@deftypefun void rl_deprep_terminal (void)
Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
the state in which it was before the most recent call to
@code{rl_prep_terminal()}.
@end deftypefun
@deftypefun void rl_tty_set_default_bindings (Keymap kmap)
Read the operating system's terminal editing characters (as would be
displayed by @code{stty}) to their Readline equivalents.
The bindings are performed in @var{kmap}.
@end deftypefun
@deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
that the terminal editing characters are bound to @code{rl_insert}.
The bindings are performed in @var{kmap}.
@end deftypefun
@deftypefun int rl_reset_terminal (const char *terminal_name)
Reinitialize Readline's idea of the terminal settings using
@var{terminal_name} as the terminal type (e.g., @code{vt100}).
If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
environment variable is used.
@end deftypefun
@node Utility Functions
@subsection Utility Functions
@deftypefun int rl_save_state (struct readline_state *sp)
Save a snapshot of Readline's internal state to @var{sp}.
The contents of the @var{readline_state} structure are documented
in @file{readline.h}.
The caller is responsible for allocating the structure.
@end deftypefun
@deftypefun int rl_restore_state (struct readline_state *sp)
Restore Readline's internal state to that stored in @var{sp}, which must
have been saved by a call to @code{rl_save_state}.
The contents of the @var{readline_state} structure are documented
in @file{readline.h}.
The caller is responsible for freeing the structure.
@end deftypefun
@deftypefun void rl_free (void *mem)
Deallocate the memory pointed to by @var{mem}. @var{mem} must have been
allocated by @code{malloc}.
@end deftypefun
@deftypefun void rl_replace_line (const char *text, int clear_undo)
Replace the contents of @code{rl_line_buffer} with @var{text}.
The point and mark are preserved, if possible.
If @var{clear_undo} is non-zero, the undo list associated with the
current line is cleared.
@end deftypefun
@deftypefun void rl_extend_line_buffer (int len)
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
characters, possibly reallocating it if necessary.
@end deftypefun
@deftypefun int rl_initialize (void)
Initialize or re-initialize Readline's internal state.
It's not strictly necessary to call this; @code{readline()} calls it before
reading any input.
@end deftypefun
@deftypefun int rl_ding (void)
Ring the terminal bell, obeying the setting of @code{bell-style}.
@end deftypefun
@deftypefun int rl_alphabetic (int c)
Return 1 if @var{c} is an alphabetic character.
@end deftypefun
@deftypefun void rl_display_match_list (char **matches, int len, int max)
A convenience function for displaying a list of strings in
columnar format on Readline's output stream. @code{matches} is the list
of strings, in argv format, such as a list of completion matches.
@code{len} is the number of strings in @code{matches}, and @code{max}
is the length of the longest string in @code{matches}. This function uses
the setting of @code{print-completions-horizontally} to select how the
matches are displayed (@pxref{Readline Init File Syntax}).
When displaying completions, this function sets the number of columns used
for display to the value of @code{completion-display-width}, the value of
the environment variable @env{COLUMNS}, or the screen width, in that order.
@end deftypefun
The following are implemented as macros, defined in @code{chardefs.h}.
Applications should refrain from using them.
@deftypefun int _rl_uppercase_p (int c)
Return 1 if @var{c} is an uppercase alphabetic character.
@end deftypefun
@deftypefun int _rl_lowercase_p (int c)
Return 1 if @var{c} is a lowercase alphabetic character.
@end deftypefun
@deftypefun int _rl_digit_p (int c)
Return 1 if @var{c} is a numeric character.
@end deftypefun
@deftypefun int _rl_to_upper (int c)
If @var{c} is a lowercase alphabetic character, return the corresponding
uppercase character.
@end deftypefun
@deftypefun int _rl_to_lower (int c)
If @var{c} is an uppercase alphabetic character, return the corresponding
lowercase character.
@end deftypefun
@deftypefun int _rl_digit_value (int c)
If @var{c} is a number, return the value it represents.
@end deftypefun
@node Miscellaneous Functions
@subsection Miscellaneous Functions
@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
The binding is performed in @var{map}. When @var{keyseq} is invoked, the
@var{macro} will be inserted into the line. This function is deprecated;
use @code{rl_generic_bind()} instead.
@end deftypefun
@deftypefun void rl_macro_dumper (int readable)
Print the key sequences bound to macros and their values, using
the current keymap, to @code{rl_outstream}.
If @var{readable} is non-zero, the list is formatted in such a way
that it can be made part of an @code{inputrc} file and re-read.
@end deftypefun
@deftypefun int rl_variable_bind (const char *variable, const char *value)
Make the Readline variable @var{variable} have @var{value}.
This behaves as if the readline command
@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
file (@pxref{Readline Init File Syntax}).
@end deftypefun
@deftypefun {char *} rl_variable_value (const char *variable)
Return a string representing the value of the Readline variable @var{variable}.
For boolean variables, this string is either @samp{on} or @samp{off}.
@end deftypefun
@deftypefun void rl_variable_dumper (int readable)
Print the readline variable names and their current values
to @code{rl_outstream}.
If @var{readable} is non-zero, the list is formatted in such a way
that it can be made part of an @code{inputrc} file and re-read.
@end deftypefun
@deftypefun int rl_set_paren_blink_timeout (int u)
Set the time interval (in microseconds) that Readline waits when showing
a balancing character when @code{blink-matching-paren} has been enabled.
@end deftypefun
@deftypefun {char *} rl_get_termcap (const char *cap)
Retrieve the string value of the termcap capability @var{cap}.
Readline fetches the termcap entry for the current terminal name and
uses those capabilities to move around the screen line and perform other
terminal-specific operations, like erasing a line. Readline does not
use all of a terminal's capabilities, and this function will return
values for only those capabilities Readline uses.
@end deftypefun
@deftypefun {void} rl_clear_history (void)
Clear the history list by deleting all of the entries, in the same manner
as the History library's @code{clear_history()} function.
This differs from @code{clear_history} because it frees private data
Readline saves in the history list.
@end deftypefun
@node Alternate Interface
@subsection Alternate Interface
An alternate interface is available to plain @code{readline()}. Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to @code{select()}
on various file descriptors. To accommodate this need, readline can
also be invoked as a `callback' function from an event loop. There
are functions available to make this easy.
@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
Set up the terminal for readline I/O and display the initial
expanded value of @var{prompt}. Save the value of @var{lhandler} to
use as a handler function to call when a complete line of input has been
entered.
The handler function receives the text of the line as an argument.
@end deftypefun
@deftypefun void rl_callback_read_char (void)
Whenever an application determines that keyboard input is available, it
should call @code{rl_callback_read_char()}, which will read the next
character from the current input source.
If that character completes the line, @code{rl_callback_read_char} will
invoke the @var{lhandler} function installed by
@code{rl_callback_handler_install} to process the line.
Before calling the @var{lhandler} function, the terminal settings are
reset to the values they had before calling
@code{rl_callback_handler_install}.
If the @var{lhandler} function returns,
and the line handler remains installed,
the terminal settings are modified for Readline's use again.
@code{EOF} is indicated by calling @var{lhandler} with a
@code{NULL} line.
@end deftypefun
@deftypefun void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line handler.
This may be called from within a callback as well as independently.
If the @var{lhandler} installed by @code{rl_callback_handler_install}
does not exit the program, either this function or the function referred
to by the value of @code{rl_deprep_term_function} should be called before
the program exits to reset the terminal settings.
@end deftypefun
@node A Readline Example
@subsection A Readline Example
Here is a function which changes lowercase characters to their uppercase
equivalents, and uppercase characters to lowercase. If
this function was bound to @samp{M-c}, then typing @samp{M-c} would
change the case of the character under point. Typing @samp{M-1 0 M-c}
would change the case of the following 10 characters, leaving the cursor on
the last character changed.
@example
/* Invert the case of the COUNT following characters. */
int
invert_case_line (count, key)
int count, key;
@{
register int start, end, i;
start = rl_point;
if (rl_point >= rl_end)
return (0);
if (count < 0)
@{
direction = -1;
count = -count;
@}
else
direction = 1;
/* Find the end of the range to modify. */
end = start + (count * direction);
/* Force it to be within range. */
if (end > rl_end)
end = rl_end;
else if (end < 0)
end = 0;
if (start == end)
return (0);
if (start > end)
@{
int temp = start;
start = end;
end = temp;
@}
/* Tell readline that we are modifying the line,
so it will save the undo information. */
rl_modifying (start, end);
for (i = start; i != end; i++)
@{
if (_rl_uppercase_p (rl_line_buffer[i]))
rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
else if (_rl_lowercase_p (rl_line_buffer[i]))
rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
@}
/* Move point to on top of the last character changed. */
rl_point = (direction == 1) ? end - 1 : start;
return (0);
@}
@end example
@node Alternate Interface Example
@subsection Alternate Interface Example
Here is a complete program that illustrates Readline's alternate interface.
It reads lines from the terminal and displays them, providing the
standard history and TAB completion functions.
It understands the EOF character or "exit" to exit the program.
@example
/* Standard include files. stdio.h is required. */
#include
#include
/* Used for select(2) */
#include
#include
#include
/* Standard readline include files. */
#include
#include
static void cb_linehandler (char *);
int running;
const char *prompt = "rltest$ ";
/* Callback function called for each line when accept-line executed, EOF
seen, or EOF character read. This sets a flag and returns; it could
also call exit(3). */
static void
cb_linehandler (char *line)
@{
/* Can use ^D (stty eof) or `exit' to exit. */
if (line == NULL || strcmp (line, "exit") == 0)
@{
if (line == 0)
printf ("\n");
printf ("exit\n");
/* This function needs to be called to reset the terminal settings,
and calling it from the line handler keeps one extra prompt from
being displayed. */
rl_callback_handler_remove ();
running = 0;
@}
else
@{
if (*line)
add_history (line);
printf ("input line: %s\n", line);
free (line);
@}
@}
int
main (int c, char **v)
@{
fd_set fds;
int r;
/* Install the line handler. */
rl_callback_handler_install (prompt, cb_linehandler);
/* Enter a simple event loop. This waits until something is available
to read on readline's input stream (defaults to standard input) and
calls the builtin character read callback to read it. It does not
have to modify the user's terminal settings. */
running = 1;
while (running)
@{
FD_ZERO (&fds);
FD_SET (fileno (rl_instream), &fds);
r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
if (r < 0)
@{
perror ("rltest: select");
rl_callback_handler_remove ();
break;
@}
if (FD_ISSET (fileno (rl_instream), &fds))
rl_callback_read_char ();
@}
printf ("rltest: Event loop has exited\n");
return 0;
@}
@end example
@node Readline Signal Handling
@section Readline Signal Handling
Signals are asynchronous events sent to a process by the Unix kernel,
sometimes on behalf of another process. They are intended to indicate
exceptional events, like a user pressing the interrupt key on his terminal,
or a network connection being broken. There is a class of signals that can
be sent to the process currently reading input from the keyboard. Since
Readline changes the terminal attributes when it is called, it needs to
perform special processing when such a signal is received in order to
restore the terminal to a sane state, or provide application writers with
functions to do so manually.
Readline contains an internal signal handler that is installed for a
number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
@code{SIGHUP},
@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
When one of these signals is received, the signal handler
will reset the terminal attributes to those that were in effect before
@code{readline()} was called, reset the signal handling to what it was
before @code{readline()} was called, and resend the signal to the calling
application.
If and when the calling application's signal handler returns, Readline
will reinitialize the terminal and continue to accept input.
When a @code{SIGINT} is received, the Readline signal handler performs
some additional work, which will cause any partially-entered line to be
aborted (see the description of @code{rl_free_line_state()} below).
There is an additional Readline signal handler, for @code{SIGWINCH}, which
the kernel sends to a process whenever the terminal's size changes (for
example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
handler updates Readline's internal screen size information, and then calls
any @code{SIGWINCH} signal handler the calling application has installed.
Readline calls the application's @code{SIGWINCH} signal handler without
resetting the terminal to its original state. If the application's signal
handler does more than update its idea of the terminal size and return (for
example, a @code{longjmp} back to a main processing loop), it @emph{must}
call @code{rl_cleanup_after_signal()} (described below), to restore the
terminal state.
Readline provides two variables that allow application writers to
control whether or not it will catch certain signals and act on them
when they are received. It is important that applications change the
values of these variables only when calling @code{readline()}, not in
a signal handler, so Readline's internal signal state is not corrupted.
@deftypevar int rl_catch_signals
If this variable is non-zero, Readline will install signal handlers for
@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
The default value of @code{rl_catch_signals} is 1.
@end deftypevar
@deftypevar int rl_catch_sigwinch
If this variable is set to a non-zero value,
Readline will install a signal handler for @code{SIGWINCH}.
The default value of @code{rl_catch_sigwinch} is 1.
@end deftypevar
@deftypevar int rl_change_environment
If this variable is set to a non-zero value,
and Readline is handling @code{SIGWINCH}, Readline will modify the
@var{LINES} and @var{COLUMNS} environment variables upon receipt of a
@code{SIGWINCH}
The default value of @code{rl_change_environment} is 1.
@end deftypevar
If an application does not wish to have Readline catch any signals, or
to handle signals other than those Readline catches (@code{SIGHUP},
for example),
Readline provides convenience functions to do the necessary terminal
and internal state cleanup upon receipt of a signal.
@deftypefun void rl_cleanup_after_signal (void)
This function will reset the state of the terminal to what it was before
@code{readline()} was called, and remove the Readline signal handlers for
all signals, depending on the values of @code{rl_catch_signals} and
@code{rl_catch_sigwinch}.
@end deftypefun
@deftypefun void rl_free_line_state (void)
This will free any partial state associated with the current input line
(undo information, any partial history entry, any partially-entered
keyboard macro, and any partially-entered numeric argument). This
should be called before @code{rl_cleanup_after_signal()}. The
Readline signal handler for @code{SIGINT} calls this to abort the
current input line.
@end deftypefun
@deftypefun void rl_reset_after_signal (void)
This will reinitialize the terminal and reinstall any Readline signal
handlers, depending on the values of @code{rl_catch_signals} and
@code{rl_catch_sigwinch}.
@end deftypefun
If an application does not wish Readline to catch @code{SIGWINCH}, it may
call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
Readline to update its idea of the terminal size when a @code{SIGWINCH}
is received.
@deftypefun void rl_echo_signal_char (int sig)
If an application wishes to install its own signal handlers, but still
have readline display characters that generate signals, calling this
function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or
@code{SIGTSTP} will display the character generating that signal.
@end deftypefun
@deftypefun void rl_resize_terminal (void)
Update Readline's internal screen size by reading values from the kernel.
@end deftypefun
@deftypefun void rl_set_screen_size (int rows, int cols)
Set Readline's idea of the terminal size to @var{rows} rows and
@var{cols} columns. If either @var{rows} or @var{columns} is less than
or equal to 0, Readline's idea of that terminal dimension is unchanged.
@end deftypefun
If an application does not want to install a @code{SIGWINCH} handler, but
is still interested in the screen dimensions, Readline's idea of the screen
size may be queried.
@deftypefun void rl_get_screen_size (int *rows, int *cols)
Return Readline's idea of the terminal's size in the
variables pointed to by the arguments.
@end deftypefun
@deftypefun void rl_reset_screen_size (void)
Cause Readline to reobtain the screen size and recalculate its dimensions.
@end deftypefun
The following functions install and remove Readline's signal handlers.
@deftypefun int rl_set_signals (void)
Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
@end deftypefun
@deftypefun int rl_clear_signals (void)
Remove all of the Readline signal handlers installed by
@code{rl_set_signals()}.
@end deftypefun
@node Custom Completers
@section Custom Completers
@cindex application-specific completion functions
Typically, a program that reads commands from the user has a way of
disambiguating commands and data. If your program is one of these, then
it can provide completion for commands, data, or both.
The following sections describe how your program and Readline
cooperate to provide this service.
@menu
* How Completing Works:: The logic used to do completion.
* Completion Functions:: Functions provided by Readline.
* Completion Variables:: Variables which control completion.
* A Short Completion Example:: An example of writing completer subroutines.
@end menu
@node How Completing Works
@subsection How Completing Works
In order to complete some text, the full list of possible completions
must be available. That is, it is not possible to accurately
expand a partial word without knowing all of the possible words
which make sense in that context. The Readline library provides
the user interface to completion, and two of the most common
completion functions: filename and username. For completing other types
of text, you must write your own completion function. This section
describes exactly what such functions must do, and provides an example.
There are three major functions used to perform completion:
@enumerate
@item
The user-interface function @code{rl_complete()}. This function is
called with the same arguments as other bindable Readline functions:
@var{count} and @var{invoking_key}.
It isolates the word to be completed and calls
@code{rl_completion_matches()} to generate a list of possible completions.
It then either lists the possible completions, inserts the possible
completions, or actually performs the
completion, depending on which behavior is desired.
@item
The internal function @code{rl_completion_matches()} uses an
application-supplied @dfn{generator} function to generate the list of
possible matches, and then returns the array of these matches.
The caller should place the address of its generator function in
@code{rl_completion_entry_function}.
@item
The generator function is called repeatedly from
@code{rl_completion_matches()}, returning a string each time. The
arguments to the generator function are @var{text} and @var{state}.
@var{text} is the partial word to be completed. @var{state} is zero the
first time the function is called, allowing the generator to perform
any necessary initialization, and a positive non-zero integer for
each subsequent call. The generator function returns
@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
no more possibilities left. Usually the generator function computes the
list of possible completions when @var{state} is zero, and returns them
one at a time on subsequent calls. Each string the generator function
returns as a match must be allocated with @code{malloc()}; Readline
frees the strings when it has finished with them.
Such a generator function is referred to as an
@dfn{application-specific completion function}.
@end enumerate
@deftypefun int rl_complete (int ignore, int invoking_key)
Complete the word at or before point. You have supplied the function
that does the initial simple matching selection algorithm (see
@code{rl_completion_matches()}). The default is to do filename completion.
@end deftypefun
@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
This is a pointer to the generator function for
@code{rl_completion_matches()}.
If the value of @code{rl_completion_entry_function} is
@code{NULL} then the default filename generator
function, @code{rl_filename_completion_function()}, is used.
An @dfn{application-specific completion function} is a function whose
address is assigned to @code{rl_completion_entry_function} and whose
return values are used to generate possible completions.
@end deftypevar
@node Completion Functions
@subsection Completion Functions
Here is the complete list of callable completion functions present in
Readline.
@deftypefun int rl_complete_internal (int what_to_do)
Complete the word at or before point. @var{what_to_do} says what to do
with the completion. A value of @samp{?} means list the possible
completions. @samp{TAB} means do standard completion. @samp{*} means
insert all of the possible completions. @samp{!} means to display
all of the possible completions, if there is more than one, as well as
performing partial completion. @samp{@@} is similar to @samp{!}, but
possible completions are not listed if the possible completions share
a common prefix.
@end deftypefun
@deftypefun int rl_complete (int ignore, int invoking_key)
Complete the word at or before point. You have supplied the function
that does the initial simple matching selection algorithm (see
@code{rl_completion_matches()} and @code{rl_completion_entry_function}).
The default is to do filename
completion. This calls @code{rl_complete_internal()} with an
argument depending on @var{invoking_key}.
@end deftypefun
@deftypefun int rl_possible_completions (int count, int invoking_key)
List the possible completions. See description of @code{rl_complete
()}. This calls @code{rl_complete_internal()} with an argument of
@samp{?}.
@end deftypefun
@deftypefun int rl_insert_completions (int count, int invoking_key)
Insert the list of possible completions into the line, deleting the
partially-completed word. See description of @code{rl_complete()}.
This calls @code{rl_complete_internal()} with an argument of @samp{*}.
@end deftypefun
@deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
Returns the appropriate value to pass to @code{rl_complete_internal()}
depending on whether @var{cfunc} was called twice in succession and
the values of the @code{show-all-if-ambiguous} and
@code{show-all-if-unmodified} variables.
Application-specific completion functions may use this function to present
the same interface as @code{rl_complete()}.
@end deftypefun
@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
Returns an array of strings which is a list of completions for
@var{text}. If there are no completions, returns @code{NULL}.
The first entry in the returned array is the substitution for @var{text}.
The remaining entries are the possible completions. The array is
terminated with a @code{NULL} pointer.
@var{entry_func} is a function of two args, and returns a
@code{char *}. The first argument is @var{text}. The second is a
state argument; it is zero on the first call, and non-zero on subsequent
calls. @var{entry_func} returns a @code{NULL} pointer to the caller
when there are no more matches.
@end deftypefun
@deftypefun {char *} rl_filename_completion_function (const char *text, int state)
A generator function for filename completion in the general case.
@var{text} is a partial filename.
The Bash source is a useful reference for writing application-specific
completion functions (the Bash completion functions call this and other
Readline functions).
@end deftypefun
@deftypefun {char *} rl_username_completion_function (const char *text, int state)
A completion generator for usernames. @var{text} contains a partial
username preceded by a random character (usually @samp{~}). As with all
completion generators, @var{state} is zero on the first call and non-zero
for subsequent calls.
@end deftypefun
@node Completion Variables
@subsection Completion Variables
@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
A pointer to the generator function for @code{rl_completion_matches()}.
@code{NULL} means to use @code{rl_filename_completion_function()},
the default filename completer.
@end deftypevar
@deftypevar {rl_completion_func_t *} rl_attempted_completion_function
A pointer to an alternative function to create matches.
The function is called with @var{text}, @var{start}, and @var{end}.
@var{start} and @var{end} are indices in @code{rl_line_buffer} defining
the boundaries of @var{text}, which is a character string.
If this function exists and returns @code{NULL}, or if this variable is
set to @code{NULL}, then @code{rl_complete()} will call the value of
@code{rl_completion_entry_function} to generate matches, otherwise the
array of strings returned will be used.
If this function sets the @code{rl_attempted_completion_over}
variable to a non-zero value, Readline will not perform its default
completion even if this function returns no matches.
@end deftypevar
@deftypevar {rl_quote_func_t *} rl_filename_quoting_function
A pointer to a function that will quote a filename in an
application-specific fashion. This is called if filename completion is being
attempted and one of the characters in @code{rl_filename_quote_characters}
appears in a completed filename. The function is called with
@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
is the filename to be quoted. The @var{match_type} is either
@code{SINGLE_MATCH}, if there is only one completion match, or
@code{MULT_MATCH}. Some functions use this to decide whether or not to
insert a closing quote character. The @var{quote_pointer} is a pointer
to any opening quote character the user typed. Some functions choose
to reset this character.
@end deftypevar
@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
A pointer to a function that will remove application-specific quoting
characters from a filename before completion is attempted, so those
characters do not interfere with matching the text against names in
the filesystem. It is called with @var{text}, the text of the word
to be dequoted, and @var{quote_char}, which is the quoting character
that delimits the filename (usually @samp{'} or @samp{"}). If
@var{quote_char} is zero, the filename was not in an embedded string.
@end deftypevar
@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
A pointer to a function to call that determines whether or not a specific
character in the line buffer is quoted, according to whatever quoting
mechanism the program calling Readline uses. The function is called with
two arguments: @var{text}, the text of the line, and @var{index}, the
index of the character in the line. It is used to decide whether a
character found in @code{rl_completer_word_break_characters} should be
used to break words for the completer.
@end deftypevar
@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
This function, if defined, is called by the completer when real filename
completion is done, after all the matching names have been generated.
It is passed a @code{NULL} terminated array of matches.
The first element (@code{matches[0]}) is the
maximal substring common to all matches. This function can
re-arrange the list of matches as required, but each element deleted
from the array must be freed.
@end deftypevar
@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
This function, if defined, is allowed to modify the directory portion
of filenames Readline completes.
It could be used to expand symbolic links or shell variables in pathnames.
It is called with the address of a string (the current directory name) as an
argument, and may modify that string.
If the string is replaced with a new string, the old value should be freed.
Any modified directory name should have a trailing slash.
The modified value will be used as part of the completion, replacing
the directory portion of the pathname the user typed.
At the least, even if no other expansion is performed, this function should
remove any quote characters from the directory name, because its result will
be passed directly to @code{opendir()}.
The directory completion hook returns an integer that should be non-zero if
the function modifies its directory argument.
The function should not modify the directory argument if it returns 0.
@end deftypevar
@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook;
If non-zero, this is the address of a function to call when completing
a directory name. This function takes the address of the directory name
to be modified as an argument. Unlike @code{rl_directory_completion_hook},
it only modifies the directory name used in @code{opendir}, not what is
displayed when the possible completions are printed or inserted. It is
called before rl_directory_completion_hook.
At the least, even if no other expansion is performed, this function should
remove any quote characters from the directory name, because its result will
be passed directly to @code{opendir()}.
The directory rewrite hook returns an integer that should be non-zero if
the function modfies its directory argument.
The function should not modify the directory argument if it returns 0.
@end deftypevar
@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook
If non-zero, this is the address of a function for the completer to
call before deciding which character to append to a completed name.
This function modifies its filename name argument, and the modified value
is passed to @code{stat()} to determine the file's type and characteristics.
This function does not need to remove quote characters from the filename.
The stat hook returns an integer that should be non-zero if
the function modfies its directory argument.
The function should not modify the directory argument if it returns 0.
@end deftypevar
@deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook
If non-zero, this is the address of a function called when reading
directory entries from the filesystem for completion and comparing
them to the partial word to be completed. The function should
perform any necessary application or system-specific conversion on
the filename, such as converting between character sets or converting
from a filesystem format to a character input format.
The function takes two arguments: @var{fname}, the filename to be converted,
and @var{fnlen}, its length in bytes.
It must either return its first argument (if no conversion takes place)
or the converted filename in newly-allocated memory. The converted
form is used to compare against the word to be completed, and, if it
matches, is added to the list of matches. Readline will free the
allocated string.
@end deftypevar
@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
If non-zero, then this is the address of a function to call when
completing a word would normally display the list of possible matches.
This function is called in lieu of Readline displaying the list.
It takes three arguments:
(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
where @var{matches} is the array of matching strings,
@var{num_matches} is the number of strings in that array, and
@var{max_length} is the length of the longest string in that array.
Readline provides a convenience function, @code{rl_display_match_list},
that takes care of doing the display to Readline's output stream. That
function may be called from this hook.
@end deftypevar
@deftypevar {const char *} rl_basic_word_break_characters
The basic list of characters that signal a break between words for the
completer routine. The default value of this variable is the characters
which break words for completion in Bash:
@code{" \t\n\"\\'`@@$><=;|&@{("}.
@end deftypevar
@deftypevar {const char *} rl_basic_quote_characters
A list of quote characters which can cause a word break.
@end deftypevar
@deftypevar {const char *} rl_completer_word_break_characters
The list of characters that signal a break between words for
@code{rl_complete_internal()}. The default list is the value of
@code{rl_basic_word_break_characters}.
@end deftypevar
@deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook
If non-zero, this is the address of a function to call when Readline is
deciding where to separate words for word completion. It should return
a character string like @code{rl_completer_word_break_characters} to be
used to perform the current completion. The function may choose to set
@code{rl_completer_word_break_characters} itself. If the function
returns @code{NULL}, @code{rl_completer_word_break_characters} is used.
@end deftypevar
@deftypevar {const char *} rl_completer_quote_characters
A list of characters which can be used to quote a substring of the line.
Completion occurs on the entire substring, and within the substring
@code{rl_completer_word_break_characters} are treated as any other character,
unless they also appear within this list.
@end deftypevar
@deftypevar {const char *} rl_filename_quote_characters
A list of characters that cause a filename to be quoted by the completer
when they appear in a completed filename. The default is the null string.
@end deftypevar
@deftypevar {const char *} rl_special_prefixes
The list of characters that are word break characters, but should be
left in @var{text} when it is passed to the completion function.
Programs can use this to help determine what kind of completing to do.
For instance, Bash sets this variable to "$@@" so that it can complete
shell variables and hostnames.
@end deftypevar
@deftypevar int rl_completion_query_items
Up to this many items will be displayed in response to a
possible-completions call. After that, readline asks the user if she is sure
she wants to see them all. The default value is 100. A negative value
indicates that Readline should never ask the user.
@end deftypevar
@deftypevar {int} rl_completion_append_character
When a single completion alternative matches at the end of the command
line, this character is appended to the inserted completion text. The
default is a space character (@samp{ }). Setting this to the null
character (@samp{\0}) prevents anything being appended automatically.
This can be changed in application-specific completion functions to
provide the ``most sensible word separator character'' according to
an application-specific command line syntax specification.
@end deftypevar
@deftypevar int rl_completion_suppress_append
If non-zero, @var{rl_completion_append_character} is not appended to
matches at the end of the command line, as described above.
It is set to 0 before any application-specific completion function
is called, and may only be changed within such a function.
@end deftypevar
@deftypevar int rl_completion_quote_character
When Readline is completing quoted text, as delimited by one of the
characters in @var{rl_completer_quote_characters}, it sets this variable
to the quoting character found.
This is set before any application-specific completion function is called.
@end deftypevar
@deftypevar int rl_completion_suppress_quote
If non-zero, Readline does not append a matching quote character when
performing completion on a quoted string.
It is set to 0 before any application-specific completion function
is called, and may only be changed within such a function.
@end deftypevar
@deftypevar int rl_completion_found_quote
When Readline is completing quoted text, it sets this variable
to a non-zero value if the word being completed contains or is delimited
by any quoting characters, including backslashes.
This is set before any application-specific completion function is called.
@end deftypevar
@deftypevar int rl_completion_mark_symlink_dirs
If non-zero, a slash will be appended to completed filenames that are
symbolic links to directory names, subject to the value of the
user-settable @var{mark-directories} variable.
This variable exists so that application-specific completion functions
can override the user's global preference (set via the
@var{mark-symlinked-directories} Readline variable) if appropriate.
This variable is set to the user's preference before any
application-specific completion function is called, so unless that
function modifies the value, the user's preferences are honored.
@end deftypevar
@deftypevar int rl_ignore_completion_duplicates
If non-zero, then duplicates in the matches are removed.
The default is 1.
@end deftypevar
@deftypevar int rl_filename_completion_desired
Non-zero means that the results of the matches are to be treated as
filenames. This is @emph{always} zero when completion is attempted,
and can only be changed
within an application-specific completion function. If it is set to a
non-zero value by such a function, directory names have a slash appended
and Readline attempts to quote completed filenames if they contain any
characters in @code{rl_filename_quote_characters} and
@code{rl_filename_quoting_desired} is set to a non-zero value.
@end deftypevar
@deftypevar int rl_filename_quoting_desired
Non-zero means that the results of the matches are to be quoted using
double quotes (or an application-specific quoting mechanism) if the
completed filename contains any characters in
@code{rl_filename_quote_chars}. This is @emph{always} non-zero
when completion is attempted, and can only be changed within an
application-specific completion function.
The quoting is effected via a call to the function pointed to
by @code{rl_filename_quoting_function}.
@end deftypevar
@deftypevar int rl_attempted_completion_over
If an application-specific completion function assigned to
@code{rl_attempted_completion_function} sets this variable to a non-zero
value, Readline will not perform its default filename completion even
if the application's completion function returns no matches.
It should be set only by an application's completion function.
@end deftypevar
@deftypevar int rl_sort_completion_matches
If an application sets this variable to 0, Readline will not sort the
list of completions (which implies that it cannot remove any duplicate
completions). The default value is 1, which means that Readline will
sort the completions and, depending on the value of
@code{rl_ignore_completion_duplicates}, will attempt to remove duplicate
matches.
@end deftypevar
@deftypevar int rl_completion_type
Set to a character describing the type of completion Readline is currently
attempting; see the description of @code{rl_complete_internal()}
(@pxref{Completion Functions}) for the list of characters.
This is set to the appropriate value before any application-specific
completion function is called, allowing such functions to present
the same interface as @code{rl_complete()}.
@end deftypevar
@deftypevar int rl_completion_invoking_key
Set to the final character in the key sequence that invoked one of the
completion functions that call @code{rl_complete_internal()}. This is
set to the appropriate value before any application-specific completion
function is called.
@end deftypevar
@deftypevar int rl_inhibit_completion
If this variable is non-zero, completion is inhibited. The completion
character will be inserted as any other bound to @code{self-insert}.
@end deftypevar
@node A Short Completion Example
@subsection A Short Completion Example
Here is a small application demonstrating the use of the GNU Readline
library. It is called @code{fileman}, and the source code resides in
@file{examples/fileman.c}. This sample application provides
completion of command names, line editing features, and access to the
history list.
@page
@smallexample
/* fileman.c -- A tiny application which demonstrates how to use the
GNU Readline library. This application interactively allows users
to manipulate files and their modes. */
#ifdef HAVE_CONFIG_H
# include
#endif
#include
#ifdef HAVE_SYS_FILE_H
# include
#endif
#include
#ifdef HAVE_UNISTD_H
# include
#endif
#include
#include
#include
#if defined (HAVE_STRING_H)
# include
#else /* !HAVE_STRING_H */
# include
#endif /* !HAVE_STRING_H */
#ifdef HAVE_STDLIB_H
# include
#endif
#include
#include
#include
extern char *xmalloc PARAMS((size_t));
/* The names of functions that actually do the manipulation. */
int com_list PARAMS((char *));
int com_view PARAMS((char *));
int com_rename PARAMS((char *));
int com_stat PARAMS((char *));
int com_pwd PARAMS((char *));
int com_delete PARAMS((char *));
int com_help PARAMS((char *));
int com_cd PARAMS((char *));
int com_quit PARAMS((char *));
/* A structure which contains information on the commands this program
can understand. */
typedef struct @{
char *name; /* User printable name of the function. */
rl_icpfunc_t *func; /* Function to call to do the job. */
char *doc; /* Documentation for this function. */
@} COMMAND;
COMMAND commands[] = @{
@{ "cd", com_cd, "Change to directory DIR" @},
@{ "delete", com_delete, "Delete FILE" @},
@{ "help", com_help, "Display this text" @},
@{ "?", com_help, "Synonym for `help'" @},
@{ "list", com_list, "List files in DIR" @},
@{ "ls", com_list, "Synonym for `list'" @},
@{ "pwd", com_pwd, "Print the current working directory" @},
@{ "quit", com_quit, "Quit using Fileman" @},
@{ "rename", com_rename, "Rename FILE to NEWNAME" @},
@{ "stat", com_stat, "Print out statistics on FILE" @},
@{ "view", com_view, "View the contents of FILE" @},
@{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
@};
/* Forward declarations. */
char *stripwhite ();
COMMAND *find_command ();
/* The name of this program, as taken from argv[0]. */
char *progname;
/* When non-zero, this global means the user is done using this program. */
int done;
char *
dupstr (s)
char *s;
@{
char *r;
r = xmalloc (strlen (s) + 1);
strcpy (r, s);
return (r);
@}
main (argc, argv)
int argc;
char **argv;
@{
char *line, *s;
progname = argv[0];
initialize_readline (); /* Bind our completer. */
/* Loop reading and executing lines until the user quits. */
for ( ; done == 0; )
@{
line = readline ("FileMan: ");
if (!line)
break;
/* Remove leading and trailing whitespace from the line.
Then, if there is anything left, add it to the history list
and execute it. */
s = stripwhite (line);
if (*s)
@{
add_history (s);
execute_line (s);
@}
free (line);
@}
exit (0);
@}
/* Execute a command line. */
int
execute_line (line)
char *line;
@{
register int i;
COMMAND *command;
char *word;
/* Isolate the command word. */
i = 0;
while (line[i] && whitespace (line[i]))
i++;
word = line + i;
while (line[i] && !whitespace (line[i]))
i++;
if (line[i])
line[i++] = '\0';
command = find_command (word);
if (!command)
@{
fprintf (stderr, "%s: No such command for FileMan.\n", word);
return (-1);
@}
/* Get argument to command, if any. */
while (whitespace (line[i]))
i++;
word = line + i;
/* Call the function. */
return ((*(command->func)) (word));
@}
/* Look up NAME as the name of a command, and return a pointer to that
command. Return a NULL pointer if NAME isn't a command name. */
COMMAND *
find_command (name)
char *name;
@{
register int i;
for (i = 0; commands[i].name; i++)
if (strcmp (name, commands[i].name) == 0)
return (&commands[i]);
return ((COMMAND *)NULL);
@}
/* Strip whitespace from the start and end of STRING. Return a pointer
into STRING. */
char *
stripwhite (string)
char *string;
@{
register char *s, *t;
for (s = string; whitespace (*s); s++)
;
if (*s == 0)
return (s);
t = s + strlen (s) - 1;
while (t > s && whitespace (*t))
t--;
*++t = '\0';
return s;
@}
/* **************************************************************** */
/* */
/* Interface to Readline Completion */
/* */
/* **************************************************************** */
char *command_generator PARAMS((const char *, int));
char **fileman_completion PARAMS((const char *, int, int));
/* Tell the GNU Readline library how to complete. We want to try to complete
on command names if this is the first word in the line, or on filenames
if not. */
initialize_readline ()
@{
/* Allow conditional parsing of the ~/.inputrc file. */
rl_readline_name = "FileMan";
/* Tell the completer that we want a crack first. */
rl_attempted_completion_function = fileman_completion;
@}
/* Attempt to complete on the contents of TEXT. START and END bound the
region of rl_line_buffer that contains the word to complete. TEXT is
the word to complete. We can use the entire contents of rl_line_buffer
in case we want to do some simple parsing. Return the array of matches,
or NULL if there aren't any. */
char **
fileman_completion (text, start, end)
const char *text;
int start, end;
@{
char **matches;
matches = (char **)NULL;
/* If this word is at the start of the line, then it is a command
to complete. Otherwise it is the name of a file in the current
directory. */
if (start == 0)
matches = rl_completion_matches (text, command_generator);
return (matches);
@}
/* Generator function for command completion. STATE lets us know whether
to start from scratch; without any state (i.e. STATE == 0), then we
start at the top of the list. */
char *
command_generator (text, state)
const char *text;
int state;
@{
static int list_index, len;
char *name;
/* If this is a new word to complete, initialize now. This includes
saving the length of TEXT for efficiency, and initializing the index
variable to 0. */
if (!state)
@{
list_index = 0;
len = strlen (text);
@}
/* Return the next name which partially matches from the command list. */
while (name = commands[list_index].name)
@{
list_index++;
if (strncmp (name, text, len) == 0)
return (dupstr(name));
@}
/* If no names matched, then return NULL. */
return ((char *)NULL);
@}
/* **************************************************************** */
/* */
/* FileMan Commands */
/* */
/* **************************************************************** */
/* String to pass to system (). This is for the LIST, VIEW and RENAME
commands. */
static char syscom[1024];
/* List the file(s) named in arg. */
com_list (arg)
char *arg;
@{
if (!arg)
arg = "";
sprintf (syscom, "ls -FClg %s", arg);
return (system (syscom));
@}
com_view (arg)
char *arg;
@{
if (!valid_argument ("view", arg))
return 1;
#if defined (__MSDOS__)
/* more.com doesn't grok slashes in pathnames */
sprintf (syscom, "less %s", arg);
#else
sprintf (syscom, "more %s", arg);
#endif
return (system (syscom));
@}
com_rename (arg)
char *arg;
@{
too_dangerous ("rename");
return (1);
@}
com_stat (arg)
char *arg;
@{
struct stat finfo;
if (!valid_argument ("stat", arg))
return (1);
if (stat (arg, &finfo) == -1)
@{
perror (arg);
return (1);
@}
printf ("Statistics for `%s':\n", arg);
printf ("%s has %d link%s, and is %d byte%s in length.\n",
arg,
finfo.st_nlink,
(finfo.st_nlink == 1) ? "" : "s",
finfo.st_size,
(finfo.st_size == 1) ? "" : "s");
printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
printf (" Last access at: %s", ctime (&finfo.st_atime));
printf (" Last modified at: %s", ctime (&finfo.st_mtime));
return (0);
@}
com_delete (arg)
char *arg;
@{
too_dangerous ("delete");
return (1);
@}
/* Print out help for ARG, or for all of the commands if ARG is
not present. */
com_help (arg)
char *arg;
@{
register int i;
int printed = 0;
for (i = 0; commands[i].name; i++)
@{
if (!*arg || (strcmp (arg, commands[i].name) == 0))
@{
printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
printed++;
@}
@}
if (!printed)
@{
printf ("No commands match `%s'. Possibilties are:\n", arg);
for (i = 0; commands[i].name; i++)
@{
/* Print in six columns. */
if (printed == 6)
@{
printed = 0;
printf ("\n");
@}
printf ("%s\t", commands[i].name);
printed++;
@}
if (printed)
printf ("\n");
@}
return (0);
@}
/* Change to the directory ARG. */
com_cd (arg)
char *arg;
@{
if (chdir (arg) == -1)
@{
perror (arg);
return 1;
@}
com_pwd ("");
return (0);
@}
/* Print out the current working directory. */
com_pwd (ignore)
char *ignore;
@{
char dir[1024], *s;
s = getcwd (dir, sizeof(dir) - 1);
if (s == 0)
@{
printf ("Error getting pwd: %s\n", dir);
return 1;
@}
printf ("Current directory is %s\n", dir);
return 0;
@}
/* The user wishes to quit using this program. Just set DONE non-zero. */
com_quit (arg)
char *arg;
@{
done = 1;
return (0);
@}
/* Function which tells you that you can't do this. */
too_dangerous (caller)
char *caller;
@{
fprintf (stderr,
"%s: Too dangerous for me to distribute. Write it yourself.\n",
caller);
@}
/* Return non-zero if ARG is a valid argument for CALLER, else print
an error message and return zero. */
int
valid_argument (caller, arg)
char *caller, *arg;
@{
if (!arg || !*arg)
@{
fprintf (stderr, "%s: Argument required.\n", caller);
return (0);
@}
return (1);
@}
@end smallexample
readline-6.3/doc/rluser.texi 0000664 0000436 0000024 00000240237 12274460014 014734 0 ustar chet staff @comment %**start of header (This is for running Texinfo on a region.)
@setfilename rluser.info
@comment %**end of header (This is for running Texinfo on a region.)
@ignore
This file documents the end user interface to the GNU command line
editing features. It is to be an appendix to manuals for programs which
use these features. There is a document entitled "readline.texinfo"
which contains both end-user and programmer documentation for the
GNU Readline Library.
Copyright (C) 1988--2014 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
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).
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
GNU Copyright statement is available to the distributee, 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.
@end ignore
@comment If you are including this manual as an appendix, then set the
@comment variable readline-appendix.
@ifclear BashFeatures
@defcodeindex bt
@end ifclear
@node Command Line Editing
@chapter Command Line Editing
This chapter describes the basic features of the @sc{gnu}
command line editing interface.
@ifset BashFeatures
Command line editing is provided by the Readline library, which is
used by several different programs, including Bash.
Command line editing is enabled by default when using an interactive shell,
unless the @option{--noediting} option is supplied at shell invocation.
Line editing is also used when using the @option{-e} option to the
@code{read} builtin command (@pxref{Bash Builtins}).
By default, the line editing commands are similar to those of Emacs.
A vi-style line editing interface is also available.
Line editing can be enabled at any time using the @option{-o emacs} or
@option{-o vi} options to the @code{set} builtin command
(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or
@option{+o vi} options to @code{set}.
@end ifset
@menu
* Introduction and Notation:: Notation used in this text.
* Readline Interaction:: The minimum set of commands for editing a line.
* Readline Init File:: Customizing Readline from a user's view.
* Bindable Readline Commands:: A description of most of the Readline commands
available for binding
* Readline vi Mode:: A short description of how to make Readline
behave like the vi editor.
@ifset BashFeatures
* Programmable Completion:: How to specify the possible completions for
a specific command.
* Programmable Completion Builtins:: Builtin commands to specify how to
complete arguments for a particular command.
* A Programmable Completion Example:: An example shell function for
generating possible completions.
@end ifset
@end menu
@node Introduction and Notation
@section Introduction to Line Editing
The following paragraphs describe the notation used to represent
keystrokes.
The text @kbd{C-k} is read as `Control-K' and describes the character
produced when the @key{k} key is pressed while the Control key
is depressed.
The text @kbd{M-k} is read as `Meta-K' and describes the character
produced when the Meta key (if you have one) is depressed, and the @key{k}
key is pressed.
The Meta key is labeled @key{ALT} on many keyboards.
On keyboards with two keys labeled @key{ALT} (usually to either side of
the space bar), the @key{ALT} on the left side is generally set to
work as a Meta key.
The @key{ALT} key on the right may also be configured to work as a
Meta key or may be configured as some other modifier, such as a
Compose key for typing accented characters.
If you do not have a Meta or @key{ALT} key, or another key working as
a Meta key, the identical keystroke can be generated by typing @key{ESC}
@emph{first}, and then typing @key{k}.
Either process is known as @dfn{metafying} the @key{k} key.
The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the
character produced by @dfn{metafying} @kbd{C-k}.
In addition, several keys have their own names. Specifically,
@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
stand for themselves when seen in this text, or in an init file
(@pxref{Readline Init File}).
If your keyboard lacks a @key{LFD} key, typing @key{C-j} will
produce the desired character.
The @key{RET} key may be labeled @key{Return} or @key{Enter} on
some keyboards.
@node Readline Interaction
@section Readline Interaction
@cindex interaction, readline
Often during an interactive session you type in a long line of text,
only to notice that the first word on the line is misspelled. The
Readline library gives you a set of commands for manipulating the text
as you type it in, allowing you to just fix your typo, and not forcing
you to retype the majority of the line. Using these editing commands,
you move the cursor to the place that needs correction, and delete or
insert the text of the corrections. Then, when you are satisfied with
the line, you simply press @key{RET}. You do not have to be at the
end of the line to press @key{RET}; the entire line is accepted
regardless of the location of the cursor within the line.
@menu
* Readline Bare Essentials:: The least you need to know about Readline.
* Readline Movement Commands:: Moving about the input line.
* Readline Killing Commands:: How to delete text, and how to get it back!
* Readline Arguments:: Giving numeric arguments to commands.
* Searching:: Searching through previous lines.
@end menu
@node Readline Bare Essentials
@subsection Readline Bare Essentials
@cindex notation, readline
@cindex command editing
@cindex editing command lines
In order to enter characters into the line, simply type them. The typed
character appears where the cursor was, and then the cursor moves one
space to the right. If you mistype a character, you can use your
erase character to back up and delete the mistyped character.
Sometimes you may mistype a character, and
not notice the error until you have typed several other characters. In
that case, you can type @kbd{C-b} to move the cursor to the left, and then
correct your mistake. Afterwards, you can move the cursor to the right
with @kbd{C-f}.
When you add text in the middle of a line, you will notice that characters
to the right of the cursor are `pushed over' to make room for the text
that you have inserted. Likewise, when you delete text behind the cursor,
characters to the right of the cursor are `pulled back' to fill in the
blank space created by the removal of the text. A list of the bare
essentials for editing the text of an input line follows.
@table @asis
@item @kbd{C-b}
Move back one character.
@item @kbd{C-f}
Move forward one character.
@item @key{DEL} or @key{Backspace}
Delete the character to the left of the cursor.
@item @kbd{C-d}
Delete the character underneath the cursor.
@item @w{Printing characters}
Insert the character into the line at the cursor.
@item @kbd{C-_} or @kbd{C-x C-u}
Undo the last editing command. You can undo all the way back to an
empty line.
@end table
@noindent
(Depending on your configuration, the @key{Backspace} key be set to
delete the character to the left of the cursor and the @key{DEL} key set
to delete the character underneath the cursor, like @kbd{C-d}, rather
than the character to the left of the cursor.)
@node Readline Movement Commands
@subsection Readline Movement Commands
The above table describes the most basic keystrokes that you need
in order to do editing of the input line. For your convenience, many
other commands have been added in addition to @kbd{C-b}, @kbd{C-f},
@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly
about the line.
@table @kbd
@item C-a
Move to the start of the line.
@item C-e
Move to the end of the line.
@item M-f
Move forward a word, where a word is composed of letters and digits.
@item M-b
Move backward a word.
@item C-l
Clear the screen, reprinting the current line at the top.
@end table
Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves
forward a word. It is a loose convention that control keystrokes
operate on characters while meta keystrokes operate on words.
@node Readline Killing Commands
@subsection Readline Killing Commands
@cindex killing text
@cindex yanking text
@dfn{Killing} text means to delete the text from the line, but to save
it away for later use, usually by @dfn{yanking} (re-inserting)
it back into the line.
(`Cut' and `paste' are more recent jargon for `kill' and `yank'.)
If the description for a command says that it `kills' text, then you can
be sure that you can get the text back in a different (or the same)
place later.
When you use a kill command, the text is saved in a @dfn{kill-ring}.
Any number of consecutive kills save all of the killed text together, so
that when you yank it back, you get it all. The kill
ring is not line specific; the text that you killed on a previously
typed line is available to be yanked back later, when you are typing
another line.
@cindex kill ring
Here is the list of commands for killing text.
@table @kbd
@item C-k
Kill the text from the current cursor position to the end of the line.
@item M-d
Kill from the cursor to the end of the current word, or, if between
words, to the end of the next word.
Word boundaries are the same as those used by @kbd{M-f}.
@item M-@key{DEL}
Kill from the cursor the start of the current word, or, if between
words, to the start of the previous word.
Word boundaries are the same as those used by @kbd{M-b}.
@item C-w
Kill from the cursor to the previous whitespace. This is different than
@kbd{M-@key{DEL}} because the word boundaries differ.
@end table
Here is how to @dfn{yank} the text back into the line. Yanking
means to copy the most-recently-killed text from the kill buffer.
@table @kbd
@item C-y
Yank the most recently killed text back into the buffer at the cursor.
@item M-y
Rotate the kill-ring, and yank the new top. You can only do this if
the prior command is @kbd{C-y} or @kbd{M-y}.
@end table
@node Readline Arguments
@subsection Readline Arguments
You can pass numeric arguments to Readline commands. Sometimes the
argument acts as a repeat count, other times it is the @i{sign} of the
argument that is significant. If you pass a negative argument to a
command which normally acts in a forward direction, that command will
act in a backward direction. For example, to kill text back to the
start of the line, you might type @samp{M-- C-k}.
The general way to pass numeric arguments to a command is to type meta
digits before the command. If the first `digit' typed is a minus
sign (@samp{-}), then the sign of the argument will be negative. Once
you have typed one meta digit to get the argument started, you can type
the remainder of the digits, and then the command. For example, to give
the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d},
which will delete the next ten characters on the input line.
@node Searching
@subsection Searching for Commands in the History
Readline provides commands for searching through the command history
@ifset BashFeatures
(@pxref{Bash History Facilities})
@end ifset
for lines containing a specified string.
There are two search modes: @dfn{incremental} and @dfn{non-incremental}.
Incremental searches begin before the user has finished typing the
search string.
As each character of the search string is typed, Readline displays
the next entry from the history matching the string typed so far.
An incremental search requires only as many characters as needed to
find the desired history entry.
To search backward in the history for a particular string, type
@kbd{C-r}. Typing @kbd{C-s} searches forward through the history.
The characters present in the value of the @code{isearch-terminators} variable
are used to terminate an incremental search.
If that variable has not been assigned a value, the @key{ESC} and
@kbd{C-J} characters will terminate an incremental search.
@kbd{C-g} will abort an incremental search and restore the original line.
When the search is terminated, the history entry containing the
search string becomes the current line.
To find other matching entries in the history list, type @kbd{C-r} or
@kbd{C-s} as appropriate.
This will search backward or forward in the history for the next
entry matching the search string typed so far.
Any other key sequence bound to a Readline command will terminate
the search and execute that command.
For instance, a @key{RET} will terminate the search and accept
the line, thereby executing the command from the history list.
A movement command will terminate the search, make the last line found
the current line, and begin editing.
Readline remembers the last incremental search string. If two
@kbd{C-r}s are typed without any intervening characters defining a new
search string, any remembered search string is used.
Non-incremental searches read the entire search string before starting
to search for matching history lines. The search string may be
typed by the user or be part of the contents of the current line.
@node Readline Init File
@section Readline Init File
@cindex initialization file, readline
Although the Readline library comes with a set of Emacs-like
keybindings installed by default, it is possible to use a different set
of keybindings.
Any user can customize programs that use Readline by putting
commands in an @dfn{inputrc} file, conventionally in his home directory.
The name of this
@ifset BashFeatures
file is taken from the value of the shell variable @env{INPUTRC}. If
@end ifset
@ifclear BashFeatures
file is taken from the value of the environment variable @env{INPUTRC}. If
@end ifclear
that variable is unset, the default is @file{~/.inputrc}. If that
file does not exist or cannot be read, the ultimate default is
@file{/etc/inputrc}.
When a program which uses the Readline library starts up, the
init file is read, and the key bindings are set.
In addition, the @code{C-x C-r} command re-reads this init file, thus
incorporating any changes that you might have made to it.
@menu
* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
* Sample Init File:: An example inputrc file.
@end menu
@node Readline Init File Syntax
@subsection Readline Init File Syntax
There are only a few basic constructs allowed in the
Readline init file. Blank lines are ignored.
Lines beginning with a @samp{#} are comments.
Lines beginning with a @samp{$} indicate conditional
constructs (@pxref{Conditional Init Constructs}). Other lines
denote variable settings and key bindings.
@table @asis
@item Variable Settings
You can modify the run-time behavior of Readline by
altering the values of variables in Readline
using the @code{set} command within the init file.
The syntax is simple:
@example
set @var{variable} @var{value}
@end example
@noindent
Here, for example, is how to
change from the default Emacs-like key binding to use
@code{vi} line editing commands:
@example
set editing-mode vi
@end example
Variable names and values, where appropriate, are recognized without regard
to case. Unrecognized variable names are ignored.
Boolean variables (those that can be set to on or off) are set to on if
the value is null or empty, @var{on} (case-insensitive), or 1. Any other
value results in the variable being set to off.
@ifset BashFeatures
The @w{@code{bind -V}} command lists the current Readline variable names
and values. @xref{Bash Builtins}.
@end ifset
A great deal of run-time behavior is changeable with the following
variables.
@cindex variables, readline
@table @code
@item bell-style
@vindex bell-style
Controls what happens when Readline wants to ring the terminal bell.
If set to @samp{none}, Readline never rings the bell. If set to
@samp{visible}, Readline uses a visible bell if one is available.
If set to @samp{audible} (the default), Readline attempts to ring
the terminal's bell.
@item bind-tty-special-chars
@vindex bind-tty-special-chars
If set to @samp{on}, Readline attempts to bind the control characters
treated specially by the kernel's terminal driver to their Readline
equivalents.
@item colored-stats
@vindex colored-stats
If set to @samp{on}, Readline displays possible completions using different
colors to indicate their file type.
The color definitions are taken from the value of the @env{LS_COLORS}
environment variable.
The default is @samp{off}.
@item comment-begin
@vindex comment-begin
The string to insert at the beginning of the line when the
@code{insert-comment} command is executed. The default value
is @code{"#"}.
@item completion-display-width
@vindex completion-display-width
The number of screen columns used to display possible matches
when performing completion.
The value is ignored if it is less than 0 or greater than the terminal
screen width.
A value of 0 will cause matches to be displayed one per line.
The default value is -1.
@item completion-ignore-case
@vindex completion-ignore-case
If set to @samp{on}, Readline performs filename matching and completion
in a case-insensitive fashion.
The default value is @samp{off}.
@item completion-map-case
@vindex completion-map-case
If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
performing case-insensitive filename matching and completion.
@item completion-prefix-display-length
@vindex completion-prefix-display-length
The length in characters of the common prefix of a list of possible
completions that is displayed without modification. When set to a
value greater than zero, common prefixes longer than this value are
replaced with an ellipsis when displaying possible completions.
@item completion-query-items
@vindex completion-query-items
The number of possible completions that determines when the user is
asked whether the list of possibilities should be displayed.
If the number of possible completions is greater than this value,
Readline will ask the user whether or not he wishes to view
them; otherwise, they are simply listed.
This variable must be set to an integer value greater than or equal to 0.
A negative value means Readline should never ask.
The default limit is @code{100}.
@item convert-meta
@vindex convert-meta
If set to @samp{on}, Readline will convert characters with the
eighth bit set to an @sc{ascii} key sequence by stripping the eighth
bit and prefixing an @key{ESC} character, converting them to a
meta-prefixed key sequence. The default value is @samp{on}.
@item disable-completion
@vindex disable-completion
If set to @samp{On}, Readline will inhibit word completion.
Completion characters will be inserted into the line as if they had
been mapped to @code{self-insert}. The default is @samp{off}.
@item editing-mode
@vindex editing-mode
The @code{editing-mode} variable controls which default set of
key bindings is used. By default, Readline starts up in Emacs editing
mode, where the keystrokes are most similar to Emacs. This variable can be
set to either @samp{emacs} or @samp{vi}.
@item echo-control-characters
When set to @samp{on}, on operating systems that indicate they support it,
readline echoes a character corresponding to a signal generated from the
keyboard. The default is @samp{on}.
@item enable-keypad
@vindex enable-keypad
When set to @samp{on}, Readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys. The default is @samp{off}.
@item enable-meta-key
When set to @samp{on}, Readline will try to enable any meta modifier
key the terminal claims to support when it is called. On many terminals,
the meta key is used to send eight-bit characters.
The default is @samp{on}.
@item expand-tilde
@vindex expand-tilde
If set to @samp{on}, tilde expansion is performed when Readline
attempts word completion. The default is @samp{off}.
@item history-preserve-point
@vindex history-preserve-point
If set to @samp{on}, the history code attempts to place the point (the
current cursor position) at the
same location on each history line retrieved with @code{previous-history}
or @code{next-history}. The default is @samp{off}.
@item history-size
@vindex history-size
Set the maximum number of history entries saved in the history list.
If set to zero, any existing history entries are deleted and no new entries
are saved.
If set to a value less than zero, the number of history entries is not
limited.
By default, the number of history entries is not limited.
@item horizontal-scroll-mode
@vindex horizontal-scroll-mode
This variable can be set to either @samp{on} or @samp{off}. Setting it
to @samp{on} means that the text of the lines being edited will scroll
horizontally on a single screen line when they are longer than the width
of the screen, instead of wrapping onto a new screen line. By default,
this variable is set to @samp{off}.
@item input-meta
@vindex input-meta
@vindex meta-flag
If set to @samp{on}, Readline will enable eight-bit input (it
will not clear the eighth bit in the characters it reads),
regardless of what the terminal claims it can support. The
default value is @samp{off}. The name @code{meta-flag} is a
synonym for this variable.
@item isearch-terminators
@vindex isearch-terminators
The string of characters that should terminate an incremental search without
subsequently executing the character as a command (@pxref{Searching}).
If this variable has not been given a value, the characters @key{ESC} and
@kbd{C-J} will terminate an incremental search.
@item keymap
@vindex keymap
Sets Readline's idea of the current keymap for key binding commands.
Acceptable @code{keymap} names are
@code{emacs},
@code{emacs-standard},
@code{emacs-meta},
@code{emacs-ctlx},
@code{vi},
@code{vi-move},
@code{vi-command}, and
@code{vi-insert}.
@code{vi} is equivalent to @code{vi-command}; @code{emacs} is
equivalent to @code{emacs-standard}. The default value is @code{emacs}.
The value of the @code{editing-mode} variable also affects the
default keymap.
@item keyseq-timeout
Specifies the duration Readline will wait for a character when reading an
ambiguous key sequence (one that can form a complete key sequence using
the input read so far, or can take additional input to complete a longer
key sequence).
If no input is received within the timeout, Readline will use the shorter
but complete key sequence.
Readline uses this value to determine whether or not input is
available on the current input source (@code{rl_instream} by default).
The value is specified in milliseconds, so a value of 1000 means that
Readline will wait one second for additional input.
If this variable is set to a value less than or equal to zero, or to a
non-numeric value, Readline will wait until another key is pressed to
decide which key sequence to complete.
The default value is @code{500}.
@item mark-directories
If set to @samp{on}, completed directory names have a slash
appended. The default is @samp{on}.
@item mark-modified-lines
@vindex mark-modified-lines
This variable, when set to @samp{on}, causes Readline to display an
asterisk (@samp{*}) at the start of history lines which have been modified.
This variable is @samp{off} by default.
@item mark-symlinked-directories
@vindex mark-symlinked-directories
If set to @samp{on}, completed names which are symbolic links
to directories have a slash appended (subject to the value of
@code{mark-directories}).
The default is @samp{off}.
@item match-hidden-files
@vindex match-hidden-files
This variable, when set to @samp{on}, causes Readline to match files whose
names begin with a @samp{.} (hidden files) when performing filename
completion.
If set to @samp{off}, the leading @samp{.} must be
supplied by the user in the filename to be completed.
This variable is @samp{on} by default.
@item menu-complete-display-prefix
@vindex menu-complete-display-prefix
If set to @samp{on}, menu completion displays the common prefix of the
list of possible completions (which may be empty) before cycling through
the list. The default is @samp{off}.
@item output-meta
@vindex output-meta
If set to @samp{on}, Readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sequence. The default is @samp{off}.
@item page-completions
@vindex page-completions
If set to @samp{on}, Readline uses an internal @code{more}-like pager
to display a screenful of possible completions at a time.
This variable is @samp{on} by default.
@item print-completions-horizontally
If set to @samp{on}, Readline will display completions with matches
sorted horizontally in alphabetical order, rather than down the screen.
The default is @samp{off}.
@item revert-all-at-newline
@vindex revert-all-at-newline
If set to @samp{on}, Readline will undo all changes to history lines
before returning when @code{accept-line} is executed. By default,
history lines may be modified and retain individual undo lists across
calls to @code{readline}. The default is @samp{off}.
@item show-all-if-ambiguous
@vindex show-all-if-ambiguous
This alters the default behavior of the completion functions. If
set to @samp{on},
words which have more than one possible completion cause the
matches to be listed immediately instead of ringing the bell.
The default value is @samp{off}.
@item show-all-if-unmodified
@vindex show-all-if-unmodified
This alters the default behavior of the completion functions in
a fashion similar to @var{show-all-if-ambiguous}.
If set to @samp{on},
words which have more than one possible completion without any
possible partial completion (the possible completions don't share
a common prefix) cause the matches to be listed immediately instead
of ringing the bell.
The default value is @samp{off}.
@item show-mode-in-prompt
@vindex show-mode-in-prompt
If set to @samp{on}, add a character to the beginning of the prompt
indicating the editing mode: emacs (@samp{@@}), vi command (@samp{:}),
or vi insertion (@samp{+}).
The default value is @samp{off}.
@item skip-completed-text
@vindex skip-completed-text
If set to @samp{on}, this alters the default completion behavior when
inserting a single match into the line. It's only active when
performing completion in the middle of a word. If enabled, readline
does not insert characters from the completion that match characters
after point in the word being completed, so portions of the word
following the cursor are not duplicated.
For instance, if this is enabled, attempting completion when the cursor
is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
rather than @samp{Makefilefile}, assuming there is a single possible
completion.
The default value is @samp{off}.
@item visible-stats
@vindex visible-stats
If set to @samp{on}, a character denoting a file's type
is appended to the filename when listing possible
completions. The default is @samp{off}.
@end table
@item Key Bindings
The syntax for controlling key bindings in the init file is
simple. First you need to find the name of the command that you
want to change. The following sections contain tables of the command
name, the default keybinding, if any, and a short description of what
the command does.
Once you know the name of the command, simply place on a line
in the init file the name of the key
you wish to bind the command to, a colon, and then the name of the
command.
There can be no space between the key name and the colon -- that will be
interpreted as part of the key name.
The name of the key can be expressed in different ways, depending on
what you find most comfortable.
In addition to command names, readline allows keys to be bound
to a string that is inserted when the key is pressed (a @var{macro}).
@ifset BashFeatures
The @w{@code{bind -p}} command displays Readline function names and
bindings in a format that can put directly into an initialization file.
@xref{Bash Builtins}.
@end ifset
@table @asis
@item @w{@var{keyname}: @var{function-name} or @var{macro}}
@var{keyname} is the name of a key spelled out in English. For example:
@example
Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"
@end example
In the above example, @kbd{C-u} is bound to the function
@code{universal-argument},
@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
@kbd{C-o} is bound to run the macro
expressed on the right hand side (that is, to insert the text
@samp{> output} into the line).
A number of symbolic character names are recognized while
processing this key binding syntax:
@var{DEL},
@var{ESC},
@var{ESCAPE},
@var{LFD},
@var{NEWLINE},
@var{RET},
@var{RETURN},
@var{RUBOUT},
@var{SPACE},
@var{SPC},
and
@var{TAB}.
@item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
@var{keyseq} differs from @var{keyname} above in that strings
denoting an entire key sequence can be specified, by placing
the key sequence in double quotes. Some @sc{gnu} Emacs style key
escapes can be used, as in the following example, but the
special character names are not recognized.
@example
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"
@end example
In the above example, @kbd{C-u} is again bound to the function
@code{universal-argument} (just as it was in the first example),
@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file},
and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
the text @samp{Function Key 1}.
@end table
The following @sc{gnu} Emacs style escape sequences are available when
specifying key sequences:
@table @code
@item @kbd{\C-}
control prefix
@item @kbd{\M-}
meta prefix
@item @kbd{\e}
an escape character
@item @kbd{\\}
backslash
@item @kbd{\"}
@key{"}, a double quotation mark
@item @kbd{\'}
@key{'}, a single quote or apostrophe
@end table
In addition to the @sc{gnu} Emacs style escape sequences, a second
set of backslash escapes is available:
@table @code
@item \a
alert (bell)
@item \b
backspace
@item \d
delete
@item \f
form feed
@item \n
newline
@item \r
carriage return
@item \t
horizontal tab
@item \v
vertical tab
@item \@var{nnn}
the eight-bit character whose value is the octal value @var{nnn}
(one to three digits)
@item \x@var{HH}
the eight-bit character whose value is the hexadecimal value @var{HH}
(one or two hex digits)
@end table
When entering the text of a macro, single or double quotes must
be used to indicate a macro definition.
Unquoted text is assumed to be a function name.
In the macro body, the backslash escapes described above are expanded.
Backslash will quote any other character in the macro text,
including @samp{"} and @samp{'}.
For example, the following binding will make @samp{@kbd{C-x} \}
insert a single @samp{\} into the line:
@example
"\C-x\\": "\\"
@end example
@end table
@node Conditional Init Constructs
@subsection Conditional Init Constructs
Readline implements a facility similar in spirit to the conditional
compilation features of the C preprocessor which allows key
bindings and variable settings to be performed as the result
of tests. There are four parser directives used.
@table @code
@item $if
The @code{$if} construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
Readline. The text of the test extends to the end of the line;
no characters are required to isolate it.
@table @code
@item mode
The @code{mode=} form of the @code{$if} directive is used to test
whether Readline is in @code{emacs} or @code{vi} mode.
This may be used in conjunction
with the @samp{set keymap} command, for instance, to set bindings in
the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
Readline is starting out in @code{emacs} mode.
@item term
The @code{term=} form may be used to include terminal-specific
key bindings, perhaps to bind the key sequences output by the
terminal's function keys. The word on the right side of the
@samp{=} is tested against both the full name of the terminal and
the portion of the terminal name before the first @samp{-}. This
allows @code{sun} to match both @code{sun} and @code{sun-cmd},
for instance.
@item application
The @var{application} construct is used to include
application-specific settings. Each program using the Readline
library sets the @var{application name}, and you can test for
a particular value.
This could be used to bind key sequences to functions useful for
a specific program. For instance, the following command adds a
key sequence that quotes the current or previous word in Bash:
@example
$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif
@end example
@end table
@item $endif
This command, as seen in the previous example, terminates an
@code{$if} command.
@item $else
Commands in this branch of the @code{$if} directive are executed if
the test fails.
@item $include
This directive takes a single filename as an argument and reads commands
and bindings from that file.
For example, the following directive reads from @file{/etc/inputrc}:
@example
$include /etc/inputrc
@end example
@end table
@node Sample Init File
@subsection Sample Init File
Here is an example of an @var{inputrc} file. This illustrates key
binding, variable assignment, and conditional syntax.
@example
@page
# This file controls the behaviour of line input editing for
# programs that use the GNU Readline library. Existing
# programs include FTP, Bash, and GDB.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# First, include any system-wide bindings and variable
# assignments from /etc/Inputrc
$include /etc/Inputrc
#
# Set various bindings for emacs mode.
set editing-mode emacs
$if mode=emacs
Meta-Control-h: backward-kill-word Text after the function name is ignored
#
# Arrow keys in keypad mode
#
#"\M-OD": backward-char
#"\M-OC": forward-char
#"\M-OA": previous-history
#"\M-OB": next-history
#
# Arrow keys in ANSI mode
#
"\M-[D": backward-char
"\M-[C": forward-char
"\M-[A": previous-history
"\M-[B": next-history
#
# Arrow keys in 8 bit keypad mode
#
#"\M-\C-OD": backward-char
#"\M-\C-OC": forward-char
#"\M-\C-OA": previous-history
#"\M-\C-OB": next-history
#
# Arrow keys in 8 bit ANSI mode
#
#"\M-\C-[D": backward-char
#"\M-\C-[C": forward-char
#"\M-\C-[A": previous-history
#"\M-\C-[B": next-history
C-q: quoted-insert
$endif
# An old-style binding. This happens to be the default.
TAB: complete
# Macros that are convenient for shell interaction
$if Bash
# edit the path
"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
# prepare to type a quoted word --
# insert open and close double quotes
# and move to just after the open quote
"\C-x\"": "\"\"\C-b"
# insert a backslash (testing backslash escapes
# in sequences and macros)
"\C-x\\": "\\"
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
# Add a binding to refresh the line, which is unbound
"\C-xr": redraw-current-line
# Edit variable on current line.
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
$endif
# use a visible bell if one is available
set bell-style visible
# don't strip characters to 7 bits when reading
set input-meta on
# allow iso-latin1 characters to be inserted rather
# than converted to prefix-meta sequences
set convert-meta off
# display characters with the eighth bit set directly
# rather than as meta-prefixed characters
set output-meta on
# if there are more than 150 possible completions for
# a word, ask the user if he wants to see all of them
set completion-query-items 150
# For FTP
$if Ftp
"\C-xg": "get \M-?"
"\C-xt": "put \M-?"
"\M-.": yank-last-arg
$endif
@end example
@node Bindable Readline Commands
@section Bindable Readline Commands
@menu
* Commands For Moving:: Moving about the line.
* Commands For History:: Getting at previous lines.
* Commands For Text:: Commands for changing text.
* Commands For Killing:: Commands for killing and yanking.
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
* Commands For Completion:: Getting Readline to do the typing for you.
* Keyboard Macros:: Saving and re-executing typed characters
* Miscellaneous Commands:: Other miscellaneous commands.
@end menu
This section describes Readline commands that may be bound to key
sequences.
@ifset BashFeatures
You can list your key bindings by executing
@w{@code{bind -P}} or, for a more terse format, suitable for an
@var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.)
@end ifset
Command names without an accompanying key sequence are unbound by default.
In the following descriptions, @dfn{point} refers to the current cursor
position, and @dfn{mark} refers to a cursor position saved by the
@code{set-mark} command.
The text between the point and mark is referred to as the @dfn{region}.
@node Commands For Moving
@subsection Commands For Moving
@ftable @code
@item beginning-of-line (C-a)
Move to the start of the current line.
@item end-of-line (C-e)
Move to the end of the line.
@item forward-char (C-f)
Move forward a character.
@item backward-char (C-b)
Move back a character.
@item forward-word (M-f)
Move forward to the end of the next word.
Words are composed of letters and digits.
@item backward-word (M-b)
Move back to the start of the current or previous word.
Words are composed of letters and digits.
@ifset BashFeatures
@item shell-forward-word ()
Move forward to the end of the next word.
Words are delimited by non-quoted shell metacharacters.
@item shell-backward-word ()
Move back to the start of the current or previous word.
Words are delimited by non-quoted shell metacharacters.
@end ifset
@item clear-screen (C-l)
Clear the screen and redraw the current line,
leaving the current line at the top of the screen.
@item redraw-current-line ()
Refresh the current line. By default, this is unbound.
@end ftable
@node Commands For History
@subsection Commands For Manipulating The History
@ftable @code
@item accept-line (Newline or Return)
@ifset BashFeatures
Accept the line regardless of where the cursor is.
If this line is
non-empty, add it to the history list according to the setting of
the @env{HISTCONTROL} and @env{HISTIGNORE} variables.
If this line is a modified history line, then restore the history line
to its original state.
@end ifset
@ifclear BashFeatures
Accept the line regardless of where the cursor is.
If this line is
non-empty, it may be added to the history list for future recall with
@code{add_history()}.
If this line is a modified history line, the history line is restored
to its original state.
@end ifclear
@item previous-history (C-p)
Move `back' through the history list, fetching the previous command.
@item next-history (C-n)
Move `forward' through the history list, fetching the next command.
@item beginning-of-history (M-<)
Move to the first line in the history.
@item end-of-history (M->)
Move to the end of the input history, i.e., the line currently
being entered.
@item reverse-search-history (C-r)
Search backward starting at the current line and moving `up' through
the history as necessary. This is an incremental search.
@item forward-search-history (C-s)
Search forward starting at the current line and moving `down' through
the the history as necessary. This is an incremental search.
@item non-incremental-reverse-search-history (M-p)
Search backward starting at the current line and moving `up'
through the history as necessary using a non-incremental search
for a string supplied by the user.
@item non-incremental-forward-search-history (M-n)
Search forward starting at the current line and moving `down'
through the the history as necessary using a non-incremental search
for a string supplied by the user.
@item history-search-forward ()
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string must match at the beginning of a history line.
This is a non-incremental search.
By default, this command is unbound.
@item history-search-backward ()
Search backward through the history for the string of characters
between the start of the current line and the point.
The search string must match at the beginning of a history line.
This is a non-incremental search.
By default, this command is unbound.
@item history-substr-search-forward ()
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string may match anywhere in a history line.
This is a non-incremental search.
By default, this command is unbound.
@item history-substr-search-backward ()
Search backward through the history for the string of characters
between the start of the current line and the point.
The search string may match anywhere in a history line.
This is a non-incremental search.
By default, this command is unbound.
@item yank-nth-arg (M-C-y)
Insert the first argument to the previous command (usually
the second word on the previous line) at point.
With an argument @var{n},
insert the @var{n}th word from the previous command (the words
in the previous command begin with word 0). A negative argument
inserts the @var{n}th word from the end of the previous command.
Once the argument @var{n} is computed, the argument is extracted
as if the @samp{!@var{n}} history expansion had been specified.
@item yank-last-arg (M-. or M-_)
Insert last argument to the previous command (the last word of the
previous history entry).
With a numeric argument, behave exactly like @code{yank-nth-arg}.
Successive calls to @code{yank-last-arg} move back through the history
list, inserting the last word (or the word specified by the argument to
the first call) of each line in turn.
Any numeric argument supplied to these successive calls determines
the direction to move through the history. A negative argument switches
the direction through the history (back or forward).
The history expansion facilities are used to extract the last argument,
as if the @samp{!$} history expansion had been specified.
@end ftable
@node Commands For Text
@subsection Commands For Changing Text
@ftable @code
@item @i{end-of-file} (usually C-d)
The character indicating end-of-file as set, for example, by
@code{stty}. If this character is read when there are no characters
on the line, and point is at the beginning of the line, Readline
interprets it as the end of input and returns @sc{eof}.
@item delete-char (C-d)
Delete the character at point. If this function is bound to the
same character as the tty @sc{eof} character, as @kbd{C-d}
commonly is, see above for the effects.
@item backward-delete-char (Rubout)
Delete the character behind the cursor. A numeric argument means
to kill the characters instead of deleting them.
@item forward-backward-delete-char ()
Delete the character under the cursor, unless the cursor is at the
end of the line, in which case the character behind the cursor is
deleted. By default, this is not bound to a key.
@item quoted-insert (C-q or C-v)
Add the next character typed to the line verbatim. This is
how to insert key sequences like @kbd{C-q}, for example.
@ifclear BashFeatures
@item tab-insert (M-@key{TAB})
Insert a tab character.
@end ifclear
@item self-insert (a, b, A, 1, !, @dots{})
Insert yourself.
@item transpose-chars (C-t)
Drag the character before the cursor forward over
the character at the cursor, moving the
cursor forward as well. If the insertion point
is at the end of the line, then this
transposes the last two characters of the line.
Negative arguments have no effect.
@item transpose-words (M-t)
Drag the word before point past the word after point,
moving point past that word as well.
If the insertion point is at the end of the line, this transposes
the last two words on the line.
@item upcase-word (M-u)
Uppercase the current (or following) word. With a negative argument,
uppercase the previous word, but do not move the cursor.
@item downcase-word (M-l)
Lowercase the current (or following) word. With a negative argument,
lowercase the previous word, but do not move the cursor.
@item capitalize-word (M-c)
Capitalize the current (or following) word. With a negative argument,
capitalize the previous word, but do not move the cursor.
@item overwrite-mode ()
Toggle overwrite mode. With an explicit positive numeric argument,
switches to overwrite mode. With an explicit non-positive numeric
argument, switches to insert mode. This command affects only
@code{emacs} mode; @code{vi} mode does overwrite differently.
Each call to @code{readline()} starts in insert mode.
In overwrite mode, characters bound to @code{self-insert} replace
the text at point rather than pushing the text to the right.
Characters bound to @code{backward-delete-char} replace the character
before point with a space.
By default, this command is unbound.
@end ftable
@node Commands For Killing
@subsection Killing And Yanking
@ftable @code
@item kill-line (C-k)
Kill the text from point to the end of the line.
@item backward-kill-line (C-x Rubout)
Kill backward to the beginning of the line.
@item unix-line-discard (C-u)
Kill backward from the cursor to the beginning of the current line.
@item kill-whole-line ()
Kill all characters on the current line, no matter where point is.
By default, this is unbound.
@item kill-word (M-d)
Kill from point to the end of the current word, or if between
words, to the end of the next word.
Word boundaries are the same as @code{forward-word}.
@item backward-kill-word (M-@key{DEL})
Kill the word behind point.
Word boundaries are the same as @code{backward-word}.
@ifset BashFeatures
@item shell-kill-word ()
Kill from point to the end of the current word, or if between
words, to the end of the next word.
Word boundaries are the same as @code{shell-forward-word}.
@item shell-backward-kill-word ()
Kill the word behind point.
Word boundaries are the same as @code{shell-backward-word}.
@end ifset
@item unix-word-rubout (C-w)
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
@item unix-filename-rubout ()
Kill the word behind point, using white space and the slash character
as the word boundaries.
The killed text is saved on the kill-ring.
@item delete-horizontal-space ()
Delete all spaces and tabs around point. By default, this is unbound.
@item kill-region ()
Kill the text in the current region.
By default, this command is unbound.
@item copy-region-as-kill ()
Copy the text in the region to the kill buffer, so it can be yanked
right away. By default, this command is unbound.
@item copy-backward-word ()
Copy the word before point to the kill buffer.
The word boundaries are the same as @code{backward-word}.
By default, this command is unbound.
@item copy-forward-word ()
Copy the word following point to the kill buffer.
The word boundaries are the same as @code{forward-word}.
By default, this command is unbound.
@item yank (C-y)
Yank the top of the kill ring into the buffer at point.
@item yank-pop (M-y)
Rotate the kill-ring, and yank the new top. You can only do this if
the prior command is @code{yank} or @code{yank-pop}.
@end ftable
@node Numeric Arguments
@subsection Specifying Numeric Arguments
@ftable @code
@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--})
Add this digit to the argument already accumulating, or start a new
argument. @kbd{M--} starts a negative argument.
@item universal-argument ()
This is another way to specify an argument.
If this command is followed by one or more digits, optionally with a
leading minus sign, those digits define the argument.
If the command is followed by digits, executing @code{universal-argument}
again ends the numeric argument, but is otherwise ignored.
As a special case, if this command is immediately followed by a
character that is neither a digit or minus sign, the argument count
for the next command is multiplied by four.
The argument count is initially one, so executing this function the
first time makes the argument count four, a second time makes the
argument count sixteen, and so on.
By default, this is not bound to a key.
@end ftable
@node Commands For Completion
@subsection Letting Readline Type For You
@ftable @code
@item complete (@key{TAB})
Attempt to perform completion on the text before point.
The actual completion performed is application-specific.
@ifset BashFeatures
Bash attempts completion treating the text as a variable (if the
text begins with @samp{$}), username (if the text begins with
@samp{~}), hostname (if the text begins with @samp{@@}), or
command (including aliases and functions) in turn. If none
of these produces a match, filename completion is attempted.
@end ifset
@ifclear BashFeatures
The default is filename completion.
@end ifclear
@item possible-completions (M-?)
List the possible completions of the text before point.
When displaying completions, Readline sets the number of columns used
for display to the value of @code{completion-display-width}, the value of
the environment variable @env{COLUMNS}, or the screen width, in that order.
@item insert-completions (M-*)
Insert all completions of the text before point that would have
been generated by @code{possible-completions}.
@item menu-complete ()
Similar to @code{complete}, but replaces the word to be completed
with a single match from the list of possible completions.
Repeated execution of @code{menu-complete} steps through the list
of possible completions, inserting each match in turn.
At the end of the list of completions, the bell is rung
(subject to the setting of @code{bell-style})
and the original text is restored.
An argument of @var{n} moves @var{n} positions forward in the list
of matches; a negative argument may be used to move backward
through the list.
This command is intended to be bound to @key{TAB}, but is unbound
by default.
@item menu-complete-backward ()
Identical to @code{menu-complete}, but moves backward through the list
of possible completions, as if @code{menu-complete} had been given a
negative argument.
@item delete-char-or-list ()
Deletes the character under the cursor if not at the beginning or
end of the line (like @code{delete-char}).
If at the end of the line, behaves identically to
@code{possible-completions}.
This command is unbound by default.
@ifset BashFeatures
@item complete-filename (M-/)
Attempt filename completion on the text before point.
@item possible-filename-completions (C-x /)
List the possible completions of the text before point,
treating it as a filename.
@item complete-username (M-~)
Attempt completion on the text before point, treating
it as a username.
@item possible-username-completions (C-x ~)
List the possible completions of the text before point,
treating it as a username.
@item complete-variable (M-$)
Attempt completion on the text before point, treating
it as a shell variable.
@item possible-variable-completions (C-x $)
List the possible completions of the text before point,
treating it as a shell variable.
@item complete-hostname (M-@@)
Attempt completion on the text before point, treating
it as a hostname.
@item possible-hostname-completions (C-x @@)
List the possible completions of the text before point,
treating it as a hostname.
@item complete-command (M-!)
Attempt completion on the text before point, treating
it as a command name. Command completion attempts to
match the text against aliases, reserved words, shell
functions, shell builtins, and finally executable filenames,
in that order.
@item possible-command-completions (C-x !)
List the possible completions of the text before point,
treating it as a command name.
@item dynamic-complete-history (M-@key{TAB})
Attempt completion on the text before point, comparing
the text against lines from the history list for possible
completion matches.
@item dabbrev-expand ()
Attempt menu completion on the text before point, comparing
the text against lines from the history list for possible
completion matches.
@item complete-into-braces (M-@{)
Perform filename completion and insert the list of possible completions
enclosed within braces so the list is available to the shell
(@pxref{Brace Expansion}).
@end ifset
@end ftable
@node Keyboard Macros
@subsection Keyboard Macros
@ftable @code
@item start-kbd-macro (C-x ()
Begin saving the characters typed into the current keyboard macro.
@item end-kbd-macro (C-x ))
Stop saving the characters typed into the current keyboard macro
and save the definition.
@item call-last-kbd-macro (C-x e)
Re-execute the last keyboard macro defined, by making the characters
in the macro appear as if typed at the keyboard.
@item print-last-kbd-macro ()
Print the last keboard macro defined in a format suitable for the
@var{inputrc} file.
@end ftable
@node Miscellaneous Commands
@subsection Some Miscellaneous Commands
@ftable @code
@item re-read-init-file (C-x C-r)
Read in the contents of the @var{inputrc} file, and incorporate
any bindings or variable assignments found there.
@item abort (C-g)
Abort the current editing command and
ring the terminal's bell (subject to the setting of
@code{bell-style}).
@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
If the metafied character @var{x} is lowercase, run the command
that is bound to the corresponding uppercase character.
@item prefix-meta (@key{ESC})
Metafy the next character typed. This is for keyboards
without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing
@kbd{M-f}.
@item undo (C-_ or C-x C-u)
Incremental undo, separately remembered for each line.
@item revert-line (M-r)
Undo all changes made to this line. This is like executing the @code{undo}
command enough times to get back to the beginning.
@ifset BashFeatures
@item tilde-expand (M-&)
@end ifset
@ifclear BashFeatures
@item tilde-expand (M-~)
@end ifclear
Perform tilde expansion on the current word.
@item set-mark (C-@@)
Set the mark to the point. If a
numeric argument is supplied, the mark is set to that position.
@item exchange-point-and-mark (C-x C-x)
Swap the point with the mark. The current cursor position is set to
the saved position, and the old cursor position is saved as the mark.
@item character-search (C-])
A character is read and point is moved to the next occurrence of that
character. A negative count searches for previous occurrences.
@item character-search-backward (M-C-])
A character is read and point is moved to the previous occurrence
of that character. A negative count searches for subsequent
occurrences.
@item skip-csi-sequence ()
Read enough characters to consume a multi-key sequence such as those
defined for keys like Home and End. Such sequences begin with a
Control Sequence Indicator (CSI), usually ESC-[. If this sequence is
bound to "\e[", keys producing such sequences will have no effect
unless explicitly bound to a readline command, instead of inserting
stray characters into the editing buffer. This is unbound by default,
but usually bound to ESC-[.
@item insert-comment (M-#)
Without a numeric argument, the value of the @code{comment-begin}
variable is inserted at the beginning of the current line.
If a numeric argument is supplied, this command acts as a toggle: if
the characters at the beginning of the line do not match the value
of @code{comment-begin}, the value is inserted, otherwise
the characters in @code{comment-begin} are deleted from the beginning of
the line.
In either case, the line is accepted as if a newline had been typed.
@ifset BashFeatures
The default value of @code{comment-begin} causes this command
to make the current line a shell comment.
If a numeric argument causes the comment character to be removed, the line
will be executed by the shell.
@end ifset
@item dump-functions ()
Print all of the functions and their key bindings to the
Readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an @var{inputrc} file. This command is unbound by default.
@item dump-variables ()
Print all of the settable variables and their values to the
Readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an @var{inputrc} file. This command is unbound by default.
@item dump-macros ()
Print all of the Readline key sequences bound to macros and the
strings they output. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an @var{inputrc} file. This command is unbound by default.
@ifset BashFeatures
@item glob-complete-word (M-g)
The word before point is treated as a pattern for pathname expansion,
with an asterisk implicitly appended. This pattern is used to
generate a list of matching file names for possible completions.
@item glob-expand-word (C-x *)
The word before point is treated as a pattern for pathname expansion,
and the list of matching file names is inserted, replacing the word.
If a numeric argument is supplied, a @samp{*} is appended before
pathname expansion.
@item glob-list-expansions (C-x g)
The list of expansions that would have been generated by
@code{glob-expand-word} is displayed, and the line is redrawn.
If a numeric argument is supplied, a @samp{*} is appended before
pathname expansion.
@item display-shell-version (C-x C-v)
Display version information about the current instance of Bash.
@item shell-expand-line (M-C-e)
Expand the line as the shell does.
This performs alias and history expansion as well as all of the shell
word expansions (@pxref{Shell Expansions}).
@item history-expand-line (M-^)
Perform history expansion on the current line.
@item magic-space ()
Perform history expansion on the current line and insert a space
(@pxref{History Interaction}).
@item alias-expand-line ()
Perform alias expansion on the current line (@pxref{Aliases}).
@item history-and-alias-expand-line ()
Perform history and alias expansion on the current line.
@item insert-last-argument (M-. or M-_)
A synonym for @code{yank-last-arg}.
@item operate-and-get-next (C-o)
Accept the current line for execution and fetch the next line
relative to the current line from the history for editing. Any
argument is ignored.
@item edit-and-execute-command (C-xC-e)
Invoke an editor on the current command line, and execute the result as shell
commands.
Bash attempts to invoke
@code{$VISUAL}, @code{$EDITOR}, and @code{emacs}
as the editor, in that order.
@end ifset
@ifclear BashFeatures
@item emacs-editing-mode (C-e)
When in @code{vi} command mode, this causes a switch to @code{emacs}
editing mode.
@item vi-editing-mode (M-C-j)
When in @code{emacs} editing mode, this causes a switch to @code{vi}
editing mode.
@end ifclear
@end ftable
@node Readline vi Mode
@section Readline vi Mode
While the Readline library does not have a full set of @code{vi}
editing functions, it does contain enough to allow simple editing
of the line. The Readline @code{vi} mode behaves as specified in
the @sc{posix} standard.
@ifset BashFeatures
In order to switch interactively between @code{emacs} and @code{vi}
editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
commands (@pxref{The Set Builtin}).
@end ifset
@ifclear BashFeatures
In order to switch interactively between @code{emacs} and @code{vi}
editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode
when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode).
@end ifclear
The Readline default is @code{emacs} mode.
When you enter a line in @code{vi} mode, you are already placed in
`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
switches you into `command' mode, where you can edit the text of the
line with the standard @code{vi} movement keys, move to previous
history lines with @samp{k} and subsequent lines with @samp{j}, and
so forth.
@ifset BashFeatures
@node Programmable Completion
@section Programmable Completion
@cindex programmable completion
When word completion is attempted for an argument to a command for
which a completion specification (a @var{compspec}) has been defined
using the @code{complete} builtin (@pxref{Programmable Completion Builtins}),
the programmable completion facilities are invoked.
First, the command name is identified.
If a compspec has been defined for that command, the
compspec is used to generate the list of possible completions for the word.
If the command word is the empty string (completion attempted at the
beginning of an empty line), any compspec defined with
the @option{-E} option to @code{complete} is used.
If the command word is a full pathname, a compspec for the full
pathname is searched for first.
If no compspec is found for the full pathname, an attempt is made to
find a compspec for the portion following the final slash.
If those searches do not result in a compspec, any compspec defined with
the @option{-D} option to @code{complete} is used as the default.
Once a compspec has been found, it is used to generate the list of
matching words.
If a compspec is not found, the default Bash completion
described above (@pxref{Commands For Completion}) is performed.
First, the actions specified by the compspec are used.
Only matches which are prefixed by the word being completed are
returned.
When the @option{-f} or @option{-d} option is used for filename or
directory name completion, the shell variable @env{FIGNORE} is
used to filter the matches.
@xref{Bash Variables}, for a description of @env{FIGNORE}.
Any completions specified by a filename expansion pattern to the
@option{-G} option are generated next.
The words generated by the pattern need not match the word being completed.
The @env{GLOBIGNORE} shell variable is not used to filter the matches,
but the @env{FIGNORE} shell variable is used.
Next, the string specified as the argument to the @option{-W} option
is considered.
The string is first split using the characters in the @env{IFS}
special variable as delimiters.
Shell quoting is honored.
Each word is then expanded using
brace expansion, tilde expansion, parameter and variable expansion,
command substitution, and arithmetic expansion,
as described above (@pxref{Shell Expansions}).
The results are split using the rules described above
(@pxref{Word Splitting}).
The results of the expansion are prefix-matched against the word being
completed, and the matching words become the possible completions.
After these matches have been generated, any shell function or command
specified with the @option{-F} and @option{-C} options is invoked.
When the command or function is invoked, the @env{COMP_LINE},
@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
assigned values as described above (@pxref{Bash Variables}).
If a shell function is being invoked, the @env{COMP_WORDS} and
@env{COMP_CWORD} variables are also set.
When the function or command is invoked, the first argument ($1) is the
name of the command whose arguments are being completed, the
second argument ($2) is the word being completed, and the third argument
($3) is the word preceding the word being completed on the current command
line.
No filtering of the generated completions against the word being completed
is performed; the function or command has complete freedom in generating
the matches.
Any function specified with @option{-F} is invoked first.
The function may use any of the shell facilities, including the
@code{compgen} and @code{compopt} builtins described below
(@pxref{Programmable Completion Builtins}), to generate the matches.
It must put the possible completions in the @env{COMPREPLY} array
variable, one per array element.
Next, any command specified with the @option{-C} option is invoked
in an environment equivalent to command substitution.
It should print a list of completions, one per line, to
the standard output.
Backslash may be used to escape a newline, if necessary.
After all of the possible completions are generated, any filter
specified with the @option{-X} option is applied to the list.
The filter is a pattern as used for pathname expansion; a @samp{&}
in the pattern is replaced with the text of the word being completed.
A literal @samp{&} may be escaped with a backslash; the backslash
is removed before attempting a match.
Any completion that matches the pattern will be removed from the list.
A leading @samp{!} negates the pattern; in this case any completion
not matching the pattern will be removed.
Finally, any prefix and suffix specified with the @option{-P} and @option{-S}
options are added to each member of the completion list, and the result is
returned to the Readline completion code as the list of possible
completions.
If the previously-applied actions do not generate any matches, and the
@option{-o dirnames} option was supplied to @code{complete} when the
compspec was defined, directory name completion is attempted.
If the @option{-o plusdirs} option was supplied to @code{complete} when
the compspec was defined, directory name completion is attempted and any
matches are added to the results of the other actions.
By default, if a compspec is found, whatever it generates is returned to
the completion code as the full set of possible completions.
The default Bash completions are not attempted, and the Readline default
of filename completion is disabled.
If the @option{-o bashdefault} option was supplied to @code{complete} when
the compspec was defined, the default Bash completions are attempted
if the compspec generates no matches.
If the @option{-o default} option was supplied to @code{complete} when the
compspec was defined, Readline's default completion will be performed
if the compspec (and, if attempted, the default Bash completions)
generate no matches.
When a compspec indicates that directory name completion is desired,
the programmable completion functions force Readline to append a slash
to completed names which are symbolic links to directories, subject to
the value of the @var{mark-directories} Readline variable, regardless
of the setting of the @var{mark-symlinked-directories} Readline variable.
There is some support for dynamically modifying completions. This is
most useful when used in combination with a default completion specified
with @option{-D}. It's possible for shell functions executed as completion
handlers to indicate that completion should be retried by returning an
exit status of 124. If a shell function returns 124, and changes
the compspec associated with the command on which completion is being
attempted (supplied as the first argument when the function is executed),
programmable completion restarts from the beginning, with an
attempt to find a new compspec for that command. This allows a set of
completions to be built dynamically as completion is attempted, rather than
being loaded all at once.
For instance, assuming that there is a library of compspecs, each kept in a
file corresponding to the name of the command, the following default
completion function would load completions dynamically:
@example
_completion_loader()
@{
. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
@}
complete -D -F _completion_loader -o bashdefault -o default
@end example
@node Programmable Completion Builtins
@section Programmable Completion Builtins
@cindex completion builtins
Three builtin commands are available to manipulate the programmable completion
facilities: one to specify how the arguments to a particular command are to
be completed, and two to modify the completion as it is happening.
@table @code
@item compgen
@btindex compgen
@example
@code{compgen [@var{option}] [@var{word}]}
@end example
Generate possible completion matches for @var{word} according to
the @var{option}s, which may be any option accepted by the
@code{complete}
builtin with the exception of @option{-p} and @option{-r}, and write
the matches to the standard output.
When using the @option{-F} or @option{-C} options, the various shell variables
set by the programmable completion facilities, while available, will not
have useful values.
The matches will be generated in the same way as if the programmable
completion code had generated them directly from a completion specification
with the same flags.
If @var{word} is specified, only those completions matching @var{word}
will be displayed.
The return value is true unless an invalid option is supplied, or no
matches were generated.
@item complete
@btindex complete
@example
@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
[-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
@code{complete -pr [-DE] [@var{name} @dots{}]}
@end example
Specify how arguments to each @var{name} should be completed.
If the @option{-p} option is supplied, or if no options are supplied, existing
completion specifications are printed in a way that allows them to be
reused as input.
The @option{-r} option removes a completion specification for
each @var{name}, or, if no @var{name}s are supplied, all
completion specifications.
The @option{-D} option indicates that the remaining options and actions should
apply to the ``default'' command completion; that is, completion attempted
on a command for which no completion has previously been defined.
The @option{-E} option indicates that the remaining options and actions should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
The process of applying these completion specifications when word completion
is attempted is described above (@pxref{Programmable Completion}). The
@option{-D} option takes precedence over @option{-E}.
Other options, if specified, have the following meanings.
The arguments to the @option{-G}, @option{-W}, and @option{-X} options
(and, if necessary, the @option{-P} and @option{-S} options)
should be quoted to protect them from expansion before the
@code{complete} builtin is invoked.
@table @code
@item -o @var{comp-option}
The @var{comp-option} controls several aspects of the compspec's behavior
beyond the simple generation of completions.
@var{comp-option} may be one of:
@table @code
@item bashdefault
Perform the rest of the default Bash completions if the compspec
generates no matches.
@item default
Use Readline's default filename completion if the compspec generates
no matches.
@item dirnames
Perform directory name completion if the compspec generates no matches.
@item filenames
Tell Readline that the compspec generates filenames, so it can perform any
filename-specific processing (like adding a slash to directory names
quoting special characters, or suppressing trailing spaces).
This option is intended to be used with shell functions specified
with @option{-F}.
@item noquote
Tell Readline not to quote the completed words if they are filenames
(quoting filenames is the default).
@item nospace
Tell Readline not to append a space (the default) to words completed at
the end of the line.
@item plusdirs
After any matches defined by the compspec are generated,
directory name completion is attempted and any
matches are added to the results of the other actions.
@end table
@item -A @var{action}
The @var{action} may be one of the following to generate a list of possible
completions:
@table @code
@item alias
Alias names. May also be specified as @option{-a}.
@item arrayvar
Array variable names.
@item binding
Readline key binding names (@pxref{Bindable Readline Commands}).
@item builtin
Names of shell builtin commands. May also be specified as @option{-b}.
@item command
Command names. May also be specified as @option{-c}.
@item directory
Directory names. May also be specified as @option{-d}.
@item disabled
Names of disabled shell builtins.
@item enabled
Names of enabled shell builtins.
@item export
Names of exported shell variables. May also be specified as @option{-e}.
@item file
File names. May also be specified as @option{-f}.
@item function
Names of shell functions.
@item group
Group names. May also be specified as @option{-g}.
@item helptopic
Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
@item hostname
Hostnames, as taken from the file specified by the
@env{HOSTFILE} shell variable (@pxref{Bash Variables}).
@item job
Job names, if job control is active. May also be specified as @option{-j}.
@item keyword
Shell reserved words. May also be specified as @option{-k}.
@item running
Names of running jobs, if job control is active.
@item service
Service names. May also be specified as @option{-s}.
@item setopt
Valid arguments for the @option{-o} option to the @code{set} builtin
(@pxref{The Set Builtin}).
@item shopt
Shell option names as accepted by the @code{shopt} builtin
(@pxref{Bash Builtins}).
@item signal
Signal names.
@item stopped
Names of stopped jobs, if job control is active.
@item user
User names. May also be specified as @option{-u}.
@item variable
Names of all shell variables. May also be specified as @option{-v}.
@end table
@item -C @var{command}
@var{command} is executed in a subshell environment, and its output is
used as the possible completions.
@item -F @var{function}
The shell function @var{function} is executed in the current shell
environment.
When it is executed, $1 is the name of the command whose arguments are
being completed, $2 is the word being completed, and $3 is the word
preceding the word being completed, as described above
(@pxref{Programmable Completion}).
When it finishes, the possible completions are retrieved from the value
of the @env{COMPREPLY} array variable.
@item -G @var{globpat}
The filename expansion pattern @var{globpat} is expanded to generate
the possible completions.
@item -P @var{prefix}
@var{prefix} is added at the beginning of each possible completion
after all other options have been applied.
@item -S @var{suffix}
@var{suffix} is appended to each possible completion
after all other options have been applied.
@item -W @var{wordlist}
The @var{wordlist} is split using the characters in the
@env{IFS} special variable as delimiters, and each resultant word
is expanded.
The possible completions are the members of the resultant list which
match the word being completed.
@item -X @var{filterpat}
@var{filterpat} is a pattern as used for filename expansion.
It is applied to the list of possible completions generated by the
preceding options and arguments, and each completion matching
@var{filterpat} is removed from the list.
A leading @samp{!} in @var{filterpat} negates the pattern; in this
case, any completion not matching @var{filterpat} is removed.
@end table
The return value is true unless an invalid option is supplied, an option
other than @option{-p} or @option{-r} is supplied without a @var{name}
argument, an attempt is made to remove a completion specification for
a @var{name} for which no specification exists, or
an error occurs adding a completion specification.
@item compopt
@btindex compopt
@example
@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
@end example
Modify completion options for each @var{name} according to the
@var{option}s, or for the currently-executing completion if no @var{name}s
are supplied.
If no @var{option}s are given, display the completion options for each
@var{name} or the current completion.
The possible values of @var{option} are those valid for the @code{complete}
builtin described above.
The @option{-D} option indicates that the remaining options should
apply to the ``default'' command completion; that is, completion attempted
on a command for which no completion has previously been defined.
The @option{-E} option indicates that the remaining options should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
The @option{-D} option takes precedence over @option{-E}.
The return value is true unless an invalid option is supplied, an attempt
is made to modify the options for a @var{name} for which no completion
specification exists, or an output error occurs.
@end table
@node A Programmable Completion Example
@section A Programmable Completion Example
The most common way to obtain additional completion functionality beyond
the default actions @code{complete} and @code{compgen} provide is to use
a shell function and bind it to a particular command using @code{complete -F}.
The following function provides completions for the @code{cd} builtin.
It is a reasonably good example of what shell functions must do when
used for completion. This function uses the word passsed as @code{$2}
to determine the directory name to complete. You can also use the
@code{COMP_WORDS} array variable; the current word is indexed by the
@code{COMP_CWORD} variable.
The function relies on the @code{complete} and @code{compgen} builtins
to do much of the work, adding only the things that the Bash @code{cd}
does beyond accepting basic directory names:
tilde expansion (@pxref{Tilde Expansion}),
searching directories in @var{$CDPATH}, which is described above
(@pxref{Bourne Shell Builtins}),
and basic support for the @code{cdable_vars} shell option
(@pxref{The Shopt Builtin}).
@code{_comp_cd} modifies the value of @var{IFS} so that it contains only
a newline to accommodate file names containing spaces and tabs --
@code{compgen} prints the possible completions it generates one per line.
Possible completions go into the @var{COMPREPLY} array variable, one
completion per array element. The programmable completion system retrieves
the completions from there when the function returns.
@example
# A completion function for the cd builtin
# based on the cd completion function from the bash_completion package
_comp_cd()
@{
local IFS=$' \t\n' # normalize IFS
local cur _skipdot _cdpath
local i j k
# Tilde expansion, with side effect of expanding tilde to full pathname
case "$2" in
\~*) eval cur="$2" ;;
*) cur=$2 ;;
esac
# no cdpath or absolute pathname -- straight directory completion
if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
# compgen prints paths one per line; could also use while loop
IFS=$'\n'
COMPREPLY=( $(compgen -d -- "$cur") )
IFS=$' \t\n'
# CDPATH+directories in the current directory if not in CDPATH
else
IFS=$'\n'
_skipdot=false
# preprocess CDPATH to convert null directory names to .
_cdpath=$@{CDPATH/#:/.:@}
_cdpath=$@{_cdpath//::/:.:@}
_cdpath=$@{_cdpath/%:/:.@}
for i in $@{_cdpath//:/$'\n'@}; do
if [[ $i -ef . ]]; then _skipdot=true; fi
k="$@{#COMPREPLY[@@]@}"
for j in $( compgen -d -- "$i/$cur" ); do
COMPREPLY[k++]=$@{j#$i/@} # cut off directory
done
done
$_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
IFS=$' \t\n'
fi
# variable names if appropriate shell option set and no completions
if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
COMPREPLY=( $(compgen -v -- "$cur") )
fi
return 0
@}
@end example
We install the completion function using the @option{-F} option to
@code{complete}:
@example
# Tell readline to quote appropriate and append slashes to directories;
# use the bash default completion for other arguments
complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
@end example
@noindent
Since we'd like Bash and Readline to take care of some
of the other details for us, we use several other options to tell Bash
and Readline what to do. The @option{-o filenames} option tells Readline
that the possible completions should be treated as filenames, and quoted
appropriately. That option will also cause Readline to append a slash to
filenames it can determine are directories (which is why we might want to
extend @code{_comp_cd} to append a slash if we're using directories found
via @var{CDPATH}: Readline can't tell those completions are directories).
The @option{-o nospace} option tells Readline to not append a space
character to the directory name, in case we want to append to it.
The @option{-o bashdefault} option brings in the rest of the "Bash default"
completions -- possible completion that Bash adds to the default Readline
set. These include things like command name completion, variable completion
for words beginning with @samp{@{}, completions containing pathname
expansion patterns (@pxref{Filename Expansion}), and so on.
Once installed using @code{complete}, @code{_comp_cd} will be called every
time we attempt word completion for a @code{cd} command.
Many more examples -- an extensive collection of completions for most of
the common GNU, Unix, and Linux commands -- are available as part of the
bash_completion project. This is installed by default on many GNU/Linux
distributions. Originally written by Ian Macdonald, the project now lives
at @url{http://bash-completion.alioth.debian.org/}. There are ports for
other systems such as Solaris and Mac OS X.
An older version of the bash_completion package is distributed with bash
in the @file{examples/complete} subdirectory.
@end ifset
readline-6.3/doc/rluserman.texi 0000664 0000436 0000024 00000003776 12262617665 015452 0 ustar chet staff \input texinfo @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename rluserman.info
@settitle GNU Readline Library
@include version.texi
@comment %**end of header (This is for running Texinfo on a region.)
@copying
This manual describes the end user interface of the GNU Readline Library
(version @value{VERSION}, @value{UPDATED}), a library which aids in the
consistency of user interface across discrete programs which provide
a command line interface.
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@dircategory Libraries
@direntry
* RLuserman: (rluserman). The GNU readline library User's Manual.
@end direntry
@titlepage
@title GNU Readline Library User Interface
@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}.
@subtitle @value{UPDATED-MONTH}
@author Chet Ramey, Case Western Reserve University
@author Brian Fox, Free Software Foundation
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU Readline Library
This document describes the end user interface of the GNU Readline Library,
a utility which aids in the consistency of user interface across discrete
programs which provide a command line interface.
The Readline home page is @url{http://www.gnu.org/software/readline/}.
@menu
* Command Line Editing:: GNU Readline User's Manual.
* GNU Free Documentation License:: License for copying this manual.
@end menu
@end ifnottex
@include rluser.texi
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
@bye
readline-6.3/doc/history.texi 0000664 0000436 0000024 00000004332 12262620162 015112 0 ustar chet staff \input texinfo @c -*-texinfo-*-
@c %**start of header (This is for running Texinfo on a region.)
@setfilename history.info
@settitle GNU History Library
@include version.texi
@c %**end of header (This is for running Texinfo on a region.)
@copying
This document describes the GNU History library
(version @value{VERSION}, @value{UPDATED}),
a programming tool that provides a consistent user interface for
recalling lines of previously typed input.
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@dircategory Libraries
@direntry
* History: (history). The GNU history library API.
@end direntry
@titlepage
@title GNU History Library
@subtitle Edition @value{EDITION}, for @code{History Library} Version @value{VERSION}.
@subtitle @value{UPDATED-MONTH}
@author Chet Ramey, Case Western Reserve University
@author Brian Fox, Free Software Foundation
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU History Library
This document describes the GNU History library, a programming tool that
provides a consistent user interface for recalling lines of previously
typed input.
@menu
* Using History Interactively:: GNU History User's Manual.
* Programming with GNU History:: GNU History Programmer's Manual.
* GNU Free Documentation License:: License for copying this manual.
* Concept Index:: Index of concepts described in this manual.
* Function and Variable Index:: Index of externally visible functions
and variables.
@end menu
@end ifnottex
@syncodeindex fn vr
@include hsuser.texi
@include hstech.texi
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
@node Concept Index
@appendix Concept Index
@printindex cp
@node Function and Variable Index
@appendix Function and Variable Index
@printindex vr
@bye
readline-6.3/doc/hstech.texi 0000664 0000436 0000024 00000050477 12262620144 014702 0 ustar chet staff @ignore
This file documents the user interface to the GNU History library.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
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 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).
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
GNU Copyright statement is available to the distributee, 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.
@end ignore
@node Programming with GNU History
@chapter Programming with GNU History
This chapter describes how to interface programs that you write
with the @sc{gnu} History Library.
It should be considered a technical guide.
For information on the interactive use of @sc{gnu} History, @pxref{Using
History Interactively}.
@menu
* Introduction to History:: What is the GNU History library for?
* History Storage:: How information is stored.
* History Functions:: Functions that you can use.
* History Variables:: Variables that control behaviour.
* History Programming Example:: Example of using the GNU History Library.
@end menu
@node Introduction to History
@section Introduction to History
Many programs read input from the user a line at a time. The @sc{gnu}
History library is able to keep track of those lines, associate arbitrary
data with each line, and utilize information from previous lines in
composing new ones.
The programmer using the History library has available functions
for remembering lines on a history list, associating arbitrary data
with a line, removing lines from the list, searching through the list
for a line containing an arbitrary text string, and referencing any line
in the list directly. In addition, a history @dfn{expansion} function
is available which provides for a consistent user interface across
different programs.
The user using programs written with the History library has the
benefit of a consistent user interface with a set of well-known
commands for manipulating the text of previous lines and using that text
in new commands. The basic history manipulation commands are similar to
the history substitution provided by @code{csh}.
If the programmer desires, he can use the Readline library, which
includes some history manipulation by default, and has the added
advantage of command line editing.
Before declaring any functions using any functionality the History
library provides in other code, an application writer should include
the file @code{} in any file that uses the
History library's features. It supplies extern declarations for all
of the library's public functions and variables, and declares all of
the public data structures.
@node History Storage
@section History Storage
The history list is an array of history entries. A history entry is
declared as follows:
@example
typedef void *histdata_t;
typedef struct _hist_entry @{
char *line;
char *timestamp;
histdata_t data;
@} HIST_ENTRY;
@end example
The history list itself might therefore be declared as
@example
HIST_ENTRY **the_history_list;
@end example
The state of the History library is encapsulated into a single structure:
@example
/*
* A structure used to pass around the current state of the history.
*/
typedef struct _hist_state @{
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
@} HISTORY_STATE;
@end example
If the flags member includes @code{HS_STIFLED}, the history has been
stifled.
@node History Functions
@section History Functions
This section describes the calling sequence for the various functions
exported by the @sc{gnu} History library.
@menu
* Initializing History and State Management:: Functions to call when you
want to use history in a
program.
* History List Management:: Functions used to manage the list
of history entries.
* Information About the History List:: Functions returning information about
the history list.
* Moving Around the History List:: Functions used to change the position
in the history list.
* Searching the History List:: Functions to search the history list
for entries containing a string.
* Managing the History File:: Functions that read and write a file
containing the history list.
* History Expansion:: Functions to perform csh-like history
expansion.
@end menu
@node Initializing History and State Management
@subsection Initializing History and State Management
This section describes functions used to initialize and manage
the state of the History library when you want to use the history
functions in your program.
@deftypefun void using_history (void)
Begin a session in which the history functions might be used. This
initializes the interactive variables.
@end deftypefun
@deftypefun {HISTORY_STATE *} history_get_history_state (void)
Return a structure describing the current state of the input history.
@end deftypefun
@deftypefun void history_set_history_state (HISTORY_STATE *state)
Set the state of the history list according to @var{state}.
@end deftypefun
@node History List Management
@subsection History List Management
These functions manage individual entries on the history list, or set
parameters managing the list itself.
@deftypefun void add_history (const char *string)
Place @var{string} at the end of the history list. The associated data
field (if any) is set to @code{NULL}.
@end deftypefun
@deftypefun void add_history_time (const char *string)
Change the time stamp associated with the most recent history entry to
@var{string}.
@end deftypefun
@deftypefun {HIST_ENTRY *} remove_history (int which)
Remove history entry at offset @var{which} from the history. The
removed element is returned so you can free the line, data,
and containing structure.
@end deftypefun
@deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent)
Free the history entry @var{histent} and any history library private
data associated with it. Returns the application-specific data
so the caller can dispose of it.
@end deftypefun
@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data)
Make the history entry at offset @var{which} have @var{line} and @var{data}.
This returns the old entry so the caller can dispose of any
application-specific data. In the case
of an invalid @var{which}, a @code{NULL} pointer is returned.
@end deftypefun
@deftypefun void clear_history (void)
Clear the history list by deleting all the entries.
@end deftypefun
@deftypefun void stifle_history (int max)
Stifle the history list, remembering only the last @var{max} entries.
@end deftypefun
@deftypefun int unstifle_history (void)
Stop stifling the history. This returns the previously-set
maximum number of history entries (as set by @code{stifle_history()}).
The value is positive if the history was
stifled, negative if it wasn't.
@end deftypefun
@deftypefun int history_is_stifled (void)
Returns non-zero if the history is stifled, zero if it is not.
@end deftypefun
@node Information About the History List
@subsection Information About the History List
These functions return information about the entire history list or
individual list entries.
@deftypefun {HIST_ENTRY **} history_list (void)
Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the
current input history. Element 0 of this list is the beginning of time.
If there is no history, return @code{NULL}.
@end deftypefun
@deftypefun int where_history (void)
Returns the offset of the current history element.
@end deftypefun
@deftypefun {HIST_ENTRY *} current_history (void)
Return the history entry at the current position, as determined by
@code{where_history()}. If there is no entry there, return a @code{NULL}
pointer.
@end deftypefun
@deftypefun {HIST_ENTRY *} history_get (int offset)
Return the history entry at position @var{offset}, starting from
@code{history_base} (@pxref{History Variables}).
If there is no entry there, or if @var{offset}
is greater than the history length, return a @code{NULL} pointer.
@end deftypefun
@deftypefun time_t history_get_time (HIST_ENTRY *entry)
Return the time stamp associated with the history entry @var{entry}.
@end deftypefun
@deftypefun int history_total_bytes (void)
Return the number of bytes that the primary history entries are using.
This function returns the sum of the lengths of all the lines in the
history.
@end deftypefun
@node Moving Around the History List
@subsection Moving Around the History List
These functions allow the current index into the history list to be
set or changed.
@deftypefun int history_set_pos (int pos)
Set the current history offset to @var{pos}, an absolute index
into the list.
Returns 1 on success, 0 if @var{pos} is less than zero or greater
than the number of history entries.
@end deftypefun
@deftypefun {HIST_ENTRY *} previous_history (void)
Back up the current history offset to the previous history entry, and
return a pointer to that entry. If there is no previous entry, return
a @code{NULL} pointer.
@end deftypefun
@deftypefun {HIST_ENTRY *} next_history (void)
Move the current history offset forward to the next history entry, and
return the a pointer to that entry. If there is no next entry, return
a @code{NULL} pointer.
@end deftypefun
@node Searching the History List
@subsection Searching the History List
@cindex History Searching
These functions allow searching of the history list for entries containing
a specific string. Searching may be performed both forward and backward
from the current history position. The search may be @dfn{anchored},
meaning that the string must match at the beginning of the history entry.
@cindex anchored search
@deftypefun int history_search (const char *string, int direction)
Search the history for @var{string}, starting at the current history offset.
If @var{direction} is less than 0, then the search is through
previous entries, otherwise through subsequent entries.
If @var{string} is found, then
the current history index is set to that history entry, and the value
returned is the offset in the line of the entry where
@var{string} was found. Otherwise, nothing is changed, and a -1 is
returned.
@end deftypefun
@deftypefun int history_search_prefix (const char *string, int direction)
Search the history for @var{string}, starting at the current history
offset. The search is anchored: matching lines must begin with
@var{string}. If @var{direction} is less than 0, then the search is
through previous entries, otherwise through subsequent entries.
If @var{string} is found, then the
current history index is set to that entry, and the return value is 0.
Otherwise, nothing is changed, and a -1 is returned.
@end deftypefun
@deftypefun int history_search_pos (const char *string, int direction, int pos)
Search for @var{string} in the history list, starting at @var{pos}, an
absolute index into the list. If @var{direction} is negative, the search
proceeds backward from @var{pos}, otherwise forward. Returns the absolute
index of the history element where @var{string} was found, or -1 otherwise.
@end deftypefun
@node Managing the History File
@subsection Managing the History File
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
@deftypefun int read_history (const char *filename)
Add the contents of @var{filename} to the history list, a line at a time.
If @var{filename} is @code{NULL}, then read from @file{~/.history}.
Returns 0 if successful, or @code{errno} if not.
@end deftypefun
@deftypefun int read_history_range (const char *filename, int from, int to)
Read a range of lines from @var{filename}, adding them to the history list.
Start reading at line @var{from} and end at @var{to}.
If @var{from} is zero, start at the beginning. If @var{to} is less than
@var{from}, then read until the end of the file. If @var{filename} is
@code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
or @code{errno} if not.
@end deftypefun
@deftypefun int write_history (const char *filename)
Write the current history to @var{filename}, overwriting @var{filename}
if necessary.
If @var{filename} is @code{NULL}, then write the history list to
@file{~/.history}.
Returns 0 on success, or @code{errno} on a read or write error.
@end deftypefun
@deftypefun int append_history (int nelements, const char *filename)
Append the last @var{nelements} of the history list to @var{filename}.
If @var{filename} is @code{NULL}, then append to @file{~/.history}.
Returns 0 on success, or @code{errno} on a read or write error.
@end deftypefun
@deftypefun int history_truncate_file (const char *filename, int nlines)
Truncate the history file @var{filename}, leaving only the last
@var{nlines} lines.
If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
Returns 0 on success, or @code{errno} on failure.
@end deftypefun
@node History Expansion
@subsection History Expansion
These functions implement history expansion.
@deftypefun int history_expand (char *string, char **output)
Expand @var{string}, placing the result into @var{output}, a pointer
to a string (@pxref{History Interaction}). Returns:
@table @code
@item 0
If no expansions took place (or, if the only change in
the text was the removal of escape characters preceding the history expansion
character);
@item 1
if expansions did take place;
@item -1
if there was an error in expansion;
@item 2
if the returned line should be displayed, but not executed,
as with the @code{:p} modifier (@pxref{Modifiers}).
@end table
If an error occurred in expansion, then @var{output} contains a descriptive
error message.
@end deftypefun
@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar)
Returns the text of the history event beginning at @var{string} +
@var{*cindex}. @var{*cindex} is modified to point to after the event
specifier. At function entry, @var{cindex} points to the index into
@var{string} where the history event specification begins. @var{qchar}
is a character that is allowed to end the event specification in addition
to the ``normal'' terminating characters.
@end deftypefun
@deftypefun {char **} history_tokenize (const char *string)
Return an array of tokens parsed out of @var{string}, much as the
shell might. The tokens are split on the characters in the
@var{history_word_delimiters} variable,
and shell quoting conventions are obeyed.
@end deftypefun
@deftypefun {char *} history_arg_extract (int first, int last, const char *string)
Extract a string segment consisting of the @var{first} through @var{last}
arguments present in @var{string}. Arguments are split using
@code{history_tokenize}.
@end deftypefun
@node History Variables
@section History Variables
This section describes the externally-visible variables exported by
the @sc{gnu} History Library.
@deftypevar int history_base
The logical offset of the first entry in the history list.
@end deftypevar
@deftypevar int history_length
The number of entries currently stored in the history list.
@end deftypevar
@deftypevar int history_max_entries
The maximum number of history entries. This must be changed using
@code{stifle_history()}.
@end deftypevar
@deftypevar int history_write_timestamps
If non-zero, timestamps are written to the history file, so they can be
preserved between sessions. The default value is 0, meaning that
timestamps are not saved.
The current timestamp format uses the value of @var{history_comment_char}
to delimit timestamp entries in the history file. If that variable does
not have a value (the default), timestamps will not be written.
@end deftypevar
@deftypevar char history_expansion_char
The character that introduces a history event. The default is @samp{!}.
Setting this to 0 inhibits history expansion.
@end deftypevar
@deftypevar char history_subst_char
The character that invokes word substitution if found at the start of
a line. The default is @samp{^}.
@end deftypevar
@deftypevar char history_comment_char
During tokenization, if this character is seen as the first character
of a word, then it and all subsequent characters up to a newline are
ignored, suppressing history expansion for the remainder of the line.
This is disabled by default.
@end deftypevar
@deftypevar {char *} history_word_delimiters
The characters that separate tokens for @code{history_tokenize()}.
The default value is @code{" \t\n()<>;&|"}.
@end deftypevar
@deftypevar {char *} history_search_delimiter_chars
The list of additional characters which can delimit a history search
string, in addition to space, TAB, @samp{:} and @samp{?} in the case of
a substring search. The default is empty.
@end deftypevar
@deftypevar {char *} history_no_expand_chars
The list of characters which inhibit history expansion if found immediately
following @var{history_expansion_char}. The default is space, tab, newline,
carriage return, and @samp{=}.
@end deftypevar
@deftypevar int history_quotes_inhibit_expansion
If non-zero, single-quoted words are not scanned for the history expansion
character. The default value is 0.
@end deftypevar
@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function
This should be set to the address of a function that takes two arguments:
a @code{char *} (@var{string})
and an @code{int} index into that string (@var{i}).
It should return a non-zero value if the history expansion starting at
@var{string[i]} should not be performed; zero if the expansion should
be done.
It is intended for use by applications like Bash that use the history
expansion character for additional purposes.
By default, this variable is set to @code{NULL}.
@end deftypevar
@node History Programming Example
@section History Programming Example
The following program demonstrates simple use of the @sc{gnu} History Library.
@smallexample
#include
#include
main (argc, argv)
int argc;
char **argv;
@{
char line[1024], *t;
int len, done = 0;
line[0] = 0;
using_history ();
while (!done)
@{
printf ("history$ ");
fflush (stdout);
t = fgets (line, sizeof (line) - 1, stdin);
if (t && *t)
@{
len = strlen (t);
if (t[len - 1] == '\n')
t[len - 1] = '\0';
@}
if (!t)
strcpy (line, "quit");
if (line[0])
@{
char *expansion;
int result;
result = history_expand (line, &expansion);
if (result)
fprintf (stderr, "%s\n", expansion);
if (result < 0 || result == 2)
@{
free (expansion);
continue;
@}
add_history (expansion);
strncpy (line, expansion, sizeof (line) - 1);
free (expansion);
@}
if (strcmp (line, "quit") == 0)
done = 1;
else if (strcmp (line, "save") == 0)
write_history ("history_file");
else if (strcmp (line, "read") == 0)
read_history ("history_file");
else if (strcmp (line, "list") == 0)
@{
register HIST_ENTRY **the_list;
register int i;
the_list = history_list ();
if (the_list)
for (i = 0; the_list[i]; i++)
printf ("%d: %s\n", i + history_base, the_list[i]->line);
@}
else if (strncmp (line, "delete", 6) == 0)
@{
int which;
if ((sscanf (line + 6, "%d", &which)) == 1)
@{
HIST_ENTRY *entry = remove_history (which);
if (!entry)
fprintf (stderr, "No such entry %d\n", which);
else
@{
free (entry->line);
free (entry);
@}
@}
else
@{
fprintf (stderr, "non-numeric arg given to `delete'\n");
@}
@}
@}
@}
@end smallexample
readline-6.3/doc/hsuser.texi 0000644 0000436 0000024 00000040221 12262620152 014714 0 ustar chet staff @ignore
This file documents the user interface to the GNU History library.
Copyright (C) 1988--2014 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
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 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).
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
GNU Copyright statement is available to the distributee, 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.
@end ignore
@node Using History Interactively
@chapter Using History Interactively
@ifclear BashFeatures
@defcodeindex bt
@end ifclear
@ifset BashFeatures
This chapter describes how to use the @sc{gnu} History Library
interactively, from a user's standpoint.
It should be considered a user's guide.
For information on using the @sc{gnu} History Library in other programs,
see the @sc{gnu} Readline Library Manual.
@end ifset
@ifclear BashFeatures
This chapter describes how to use the @sc{gnu} History Library interactively,
from a user's standpoint. It should be considered a user's guide. For
information on using the @sc{gnu} History Library in your own programs,
@pxref{Programming with GNU History}.
@end ifclear
@ifset BashFeatures
@menu
* Bash History Facilities:: How Bash lets you manipulate your command
history.
* Bash History Builtins:: The Bash builtin commands that manipulate
the command history.
* History Interaction:: What it feels like using History as a user.
@end menu
@end ifset
@ifclear BashFeatures
@menu
* History Interaction:: What it feels like using History as a user.
@end menu
@end ifclear
@ifset BashFeatures
@node Bash History Facilities
@section Bash History Facilities
@cindex command history
@cindex history list
When the @option{-o history} option to the @code{set} builtin
is enabled (@pxref{The Set Builtin}),
the shell provides access to the @dfn{command history},
the list of commands previously typed.
The value of the @env{HISTSIZE} shell variable is used as the
number of commands to save in a history list.
The text of the last @env{$HISTSIZE}
commands (default 500) is saved.
The shell stores each command in the history list prior to
parameter and variable expansion
but after history expansion is performed, subject to the
values of the shell variables
@env{HISTIGNORE} and @env{HISTCONTROL}.
When the shell starts up, the history is initialized from the
file named by the @env{HISTFILE} variable (default @file{~/.bash_history}).
The file named by the value of @env{HISTFILE} is truncated, if
necessary, to contain no more than the number of lines specified by
the value of the @env{HISTFILESIZE} variable.
When a shell with history enabled exits, the last
@env{$HISTSIZE} lines are copied from the history list to the file
named by @env{$HISTFILE}.
If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
the lines are appended to the history file,
otherwise the history file is overwritten.
If @env{HISTFILE}
is unset, or if the history file is unwritable, the history is not saved.
After saving the history, the history file is truncated
to contain no more than @env{$HISTFILESIZE} lines.
If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or
a numeric value less than zero, the history file is not truncated.
If the @env{HISTTIMEFORMAT} is set, the time stamp information
associated with each history entry is written to the history file,
marked with the history comment character.
When the history file is read, lines beginning with the history
comment character followed immediately by a digit are interpreted
as timestamps for the previous history line.
The builtin command @code{fc} may be used to list or edit and re-execute
a portion of the history list.
The @code{history} builtin may be used to display or modify the history
list and manipulate the history file.
When using command-line editing, search commands
are available in each editing mode that provide access to the
history list (@pxref{Commands For History}).
The shell allows control over which commands are saved on the history
list. The @env{HISTCONTROL} and @env{HISTIGNORE}
variables may be set to cause the shell to save only a subset of the
commands entered.
The @code{cmdhist}
shell option, if enabled, causes the shell to attempt to save each
line of a multi-line command in the same history entry, adding
semicolons where necessary to preserve syntactic correctness.
The @code{lithist}
shell option causes the shell to save the command with embedded newlines
instead of semicolons.
The @code{shopt} builtin is used to set these options.
@xref{Bash Builtins}, for a description of @code{shopt}.
@node Bash History Builtins
@section Bash History Builtins
@cindex history builtins
Bash provides two builtin commands which manipulate the
history list and history file.
@table @code
@item fc
@btindex fc
@example
@code{fc [-e @var{ename}] [-lnr] [@var{first}] [@var{last}]}
@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
@end example
The first form selects a range of commands from @var{first} to
@var{last} from the history list and displays or edits and re-executes
them.
Both @var{first} and
@var{last} may be specified as a string (to locate the most recent
command beginning with that string) or as a number (an index into the
history list, where a negative number is used as an offset from the
current command number). If @var{last} is not specified it is set to
@var{first}. If @var{first} is not specified it is set to the previous
command for editing and @minus{}16 for listing. If the @option{-l} flag is
given, the commands are listed on standard output. The @option{-n} flag
suppresses the command numbers when listing. The @option{-r} flag
reverses the order of the listing. Otherwise, the editor given by
@var{ename} is invoked on a file containing those commands. If
@var{ename} is not given, the value of the following variable expansion
is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
value of the @env{FCEDIT} variable if set, or the value of the
@env{EDITOR} variable if that is set, or @code{vi} if neither is set.
When editing is complete, the edited commands are echoed and executed.
In the second form, @var{command} is re-executed after each instance
of @var{pat} in the selected command is replaced by @var{rep}.
@var{command} is intepreted the same as @var{first} above.
A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
that typing @samp{r cc} runs the last command beginning with @code{cc}
and typing @samp{r} re-executes the last command (@pxref{Aliases}).
@item history
@btindex history
@example
history [@var{n}]
history -c
history -d @var{offset}
history [-anrw] [@var{filename}]
history -ps @var{arg}
@end example
With no options, display the history list with line numbers.
Lines prefixed with a @samp{*} have been modified.
An argument of @var{n} lists only the last @var{n} lines.
If the shell variable @env{HISTTIMEFORMAT} is set and not null,
it is used as a format string for @var{strftime} to display
the time stamp associated with each displayed history entry.
No intervening blank is printed between the formatted time stamp
and the history line.
Options, if supplied, have the following meanings:
@table @code
@item -c
Clear the history list. This may be combined
with the other options to replace the history list completely.
@item -d @var{offset}
Delete the history entry at position @var{offset}.
@var{offset} should be specified as it appears when the history is
displayed.
@item -a
Append the new
history lines (history lines entered since the beginning of the
current Bash session) to the history file.
@item -n
Append the history lines not already read from the history file
to the current history list. These are lines appended to the history
file since the beginning of the current Bash session.
@item -r
Read the history file and append its contents to
the history list.
@item -w
Write out the current history list to the history file.
@item -p
Perform history substitution on the @var{arg}s and display the result
on the standard output, without storing the results in the history list.
@item -s
The @var{arg}s are added to the end of
the history list as a single entry.
@end table
When any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options is
used, if @var{filename}
is given, then it is used as the history file. If not, then
the value of the @env{HISTFILE} variable is used.
@end table
@end ifset
@node History Interaction
@section History Expansion
@cindex history expansion
The History library provides a history expansion feature that is similar
to the history expansion provided by @code{csh}. This section
describes the syntax used to manipulate the history information.
History expansions introduce words from the history list into
the input stream, making it easy to repeat commands, insert the
arguments to a previous command into the current input line, or
fix errors in previous commands quickly.
History expansion takes place in two parts. The first is to determine
which line from the history list should be used during substitution.
The second is to select portions of that line for inclusion into the
current one. The line selected from the history is called the
@dfn{event}, and the portions of that line that are acted upon are
called @dfn{words}. Various @dfn{modifiers} are available to manipulate
the selected words. The line is broken into words in the same fashion
that Bash does, so that several words
surrounded by quotes are considered one word.
History expansions are introduced by the appearance of the
history expansion character, which is @samp{!} by default.
@ifset BashFeatures
Only @samp{\} and @samp{'} may be used to escape the history expansion
character.
@end ifset
@ifset BashFeatures
Several shell options settable with the @code{shopt}
builtin (@pxref{Bash Builtins}) may be used to tailor
the behavior of history expansion. If the
@code{histverify} shell option is enabled, and Readline
is being used, history substitutions are not immediately passed to
the shell parser.
Instead, the expanded line is reloaded into the Readline
editing buffer for further modification.
If Readline is being used, and the @code{histreedit}
shell option is enabled, a failed history expansion will be
reloaded into the Readline editing buffer for correction.
The @option{-p} option to the @code{history} builtin command
may be used to see what a history expansion will do before using it.
The @option{-s} option to the @code{history} builtin may be used to
add commands to the end of the history list without actually executing
them, so that they are available for subsequent recall.
This is most useful in conjunction with Readline.
The shell allows control of the various characters used by the
history expansion mechanism with the @code{histchars} variable,
as explained above (@pxref{Bash Variables}). The shell uses
the history comment character to mark history timestamps when
writing the history file.
@end ifset
@menu
* Event Designators:: How to specify which history line to use.
* Word Designators:: Specifying which words are of interest.
* Modifiers:: Modifying the results of substitution.
@end menu
@node Event Designators
@subsection Event Designators
@cindex event designators
An event designator is a reference to a command line entry in the
history list.
Unless the reference is absolute, events are relative to the current
position in the history list.
@cindex history events
@table @asis
@item @code{!}
@ifset BashFeatures
Start a history substitution, except when followed by a space, tab,
the end of the line, @samp{=} or @samp{(} (when the
@code{extglob} shell option is enabled using the @code{shopt} builtin).
@end ifset
@ifclear BashFeatures
Start a history substitution, except when followed by a space, tab,
the end of the line, or @samp{=}.
@end ifclear
@item @code{!@var{n}}
Refer to command line @var{n}.
@item @code{!-@var{n}}
Refer to the command @var{n} lines back.
@item @code{!!}
Refer to the previous command. This is a synonym for @samp{!-1}.
@item @code{!@var{string}}
Refer to the most recent command
preceding the current position in the history list
starting with @var{string}.
@item @code{!?@var{string}[?]}
Refer to the most recent command
preceding the current position in the history list
containing @var{string}.
The trailing
@samp{?} may be omitted if the @var{string} is followed immediately by
a newline.
@item @code{^@var{string1}^@var{string2}^}
Quick Substitution. Repeat the last command, replacing @var{string1}
with @var{string2}. Equivalent to
@code{!!:s/@var{string1}/@var{string2}/}.
@item @code{!#}
The entire command line typed so far.
@end table
@node Word Designators
@subsection Word Designators
Word designators are used to select desired words from the event.
A @samp{:} separates the event specification from the word designator. It
may be omitted if the word designator begins with a @samp{^}, @samp{$},
@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
of the line, with the first word being denoted by 0 (zero). Words are
inserted into the current line separated by single spaces.
@need 0.75
For example,
@table @code
@item !!
designates the preceding command. When you type this, the preceding
command is repeated in toto.
@item !!:$
designates the last argument of the preceding command. This may be
shortened to @code{!$}.
@item !fi:2
designates the second argument of the most recent command starting with
the letters @code{fi}.
@end table
@need 0.75
Here are the word designators:
@table @code
@item 0 (zero)
The @code{0}th word. For many applications, this is the command word.
@item @var{n}
The @var{n}th word.
@item ^
The first argument; that is, word 1.
@item $
The last argument.
@item %
The word matched by the most recent @samp{?@var{string}?} search.
@item @var{x}-@var{y}
A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
@item *
All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
It is not an error to use @samp{*} if there is just one word in the event;
the empty string is returned in that case.
@item @var{x}*
Abbreviates @samp{@var{x}-$}
@item @var{x}-
Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
@end table
If a word designator is supplied without an event specification, the
previous command is used as the event.
@node Modifiers
@subsection Modifiers
After the optional word designator, you can add a sequence of one or more
of the following modifiers, each preceded by a @samp{:}.
@table @code
@item h
Remove a trailing pathname component, leaving only the head.
@item t
Remove all leading pathname components, leaving the tail.
@item r
Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
the basename.
@item e
Remove all but the trailing suffix.
@item p
Print the new command but do not execute it.
@ifset BashFeatures
@item q
Quote the substituted words, escaping further substitutions.
@item x
Quote the substituted words as with @samp{q},
but break into words at spaces, tabs, and newlines.
@end ifset
@item s/@var{old}/@var{new}/
Substitute @var{new} for the first occurrence of @var{old} in the
event line. Any delimiter may be used in place of @samp{/}.
The delimiter may be quoted in @var{old} and @var{new}
with a single backslash. If @samp{&} appears in @var{new},
it is replaced by @var{old}. A single backslash will quote
the @samp{&}. The final delimiter is optional if it is the last
character on the input line.
@item &
Repeat the previous substitution.
@item g
@itemx a
Cause changes to be applied over the entire event line. Used in
conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
or with @samp{&}.
@item G
Apply the following @samp{s} modifier once to each word in the event.
@end table
readline-6.3/doc/readline.3 0000664 0000436 0000024 00000126424 12262621357 014403 0 ustar chet staff .\"
.\" MAN PAGE COMMENTS to
.\"
.\" Chet Ramey
.\" Information Network Services
.\" Case Western Reserve University
.\" chet.ramey@case.edu
.\"
.\" Last Change: Mon Jan 6 16:34:55 EST 2014
.\"
.TH READLINE 3 "2014 January 6" "GNU Readline 6.3"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
.\"
.de FN
\fI\|\\$1\|\fP
..
.SH NAME
readline \- get a line from a user with editing
.SH SYNOPSIS
.LP
.nf
.ft B
#include
#include
#include
.ft
.fi
.LP
.nf
\fIchar *\fP
.br
\fBreadline\fP (\fIconst char *prompt\fP);
.fi
.SH COPYRIGHT
.if n Readline is Copyright (C) 1989\-2011 Free Software Foundation, Inc.
.if t Readline is Copyright \(co 1989\-2011 Free Software Foundation, Inc.
.SH DESCRIPTION
.LP
.B readline
will read a line from the terminal
and return it, using
.B prompt
as a prompt. If
.B prompt
is \fBNULL\fP or the empty string, no prompt is issued.
The line returned is allocated with
.IR malloc (3);
the caller must free it when finished. The line returned
has the final newline removed, so only the text of the line
remains.
.LP
.B readline
offers editing capabilities while the user is entering the
line.
By default, the line editing commands
are similar to those of emacs.
A vi\-style line editing interface is also available.
.LP
This manual page describes only the most basic use of \fBreadline\fP.
Much more functionality is available; see
\fIThe GNU Readline Library\fP and \fIThe GNU History Library\fP
for additional information.
.SH RETURN VALUE
.LP
.B readline
returns the text of the line read. A blank line
returns the empty string. If
.B EOF
is encountered while reading a line, and the line is empty,
.B NULL
is returned. If an
.B EOF
is read with a non\-empty line, it is
treated as a newline.
.SH NOTATION
.LP
An Emacs-style notation is used to denote
keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
means Control\-N. Similarly,
.I meta
keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
without a
.I meta
key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
then the
.I x
key. This makes ESC the \fImeta prefix\fP.
The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
or press the Escape key
then hold the Control key while pressing the
.I x
key.)
.PP
Readline commands may be given numeric
.IR arguments ,
which normally act as a repeat count. Sometimes, however, it is the
sign of the argument that is significant. Passing a negative argument
to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
causes that command to act in a backward direction. Commands whose
behavior with arguments deviates from this are noted.
.PP
When a command is described as \fIkilling\fP text, the text
deleted is saved for possible future retrieval
(\fIyanking\fP). The killed text is saved in a
\fIkill ring\fP. Consecutive kills cause the text to be
accumulated into one unit, which can be yanked all at once.
Commands which do not kill text separate the chunks of text
on the kill ring.
.SH INITIALIZATION FILE
.LP
Readline is customized by putting commands in an initialization
file (the \fIinputrc\fP file).
The name of this file is taken from the value of the
.B INPUTRC
environment variable. If that variable is unset, the default is
.IR ~/.inputrc .
If that file does not exist or cannot be read, the ultimate default is
.IR /etc/inputrc .
When a program which uses the readline library starts up, the
init file is read, and the key bindings and variables are set.
There are only a few basic constructs allowed in the
readline init file. Blank lines are ignored.
Lines beginning with a \fB#\fP are comments.
Lines beginning with a \fB$\fP indicate conditional constructs.
Other lines denote key bindings and variable settings.
Each program using this library may add its own commands
and bindings.
.PP
For example, placing
.RS
.PP
M\-Control\-u: universal\-argument
.RE
or
.RS
C\-Meta\-u: universal\-argument
.RE
.sp
into the
.I inputrc
would make M\-C\-u execute the readline command
.IR universal\-argument .
.PP
The following symbolic character names are recognized while
processing key bindings:
.IR DEL ,
.IR ESC ,
.IR ESCAPE ,
.IR LFD ,
.IR NEWLINE ,
.IR RET ,
.IR RETURN ,
.IR RUBOUT ,
.IR SPACE ,
.IR SPC ,
and
.IR TAB .
.PP
In addition to command names, readline allows keys to be bound
to a string that is inserted when the key is pressed (a \fImacro\fP).
.PP
.SS Key Bindings
.PP
The syntax for controlling key bindings in the
.I inputrc
file is simple. All that is required is the name of the
command or the text of a macro and a key sequence to which
it should be bound. The name may be specified in one of two ways:
as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
prefixes, or as a key sequence.
The name and key sequence are separated by a colon. There can be no
whitespace between the name and the colon.
.PP
When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP,
.I keyname
is the name of a key spelled out in English. For example:
.sp
.RS
Control\-u: universal\-argument
.br
Meta\-Rubout: backward\-kill\-word
.br
Control\-o: "> output"
.RE
.LP
In the above example,
.I C\-u
is bound to the function
.BR universal\-argument ,
.I M-DEL
is bound to the function
.BR backward\-kill\-word ,
and
.I C\-o
is bound to run the macro
expressed on the right hand side (that is, to insert the text
.if t \f(CW> output\fP
.if n ``> output''
into the line).
.PP
In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
.B keyseq
differs from
.B keyname
above in that strings denoting
an entire key sequence may be specified by placing the sequence
within double quotes. Some GNU Emacs style key escapes can be
used, as in the following example, but the symbolic character names
are not recognized.
.sp
.RS
"\eC\-u": universal\-argument
.br
"\eC\-x\eC\-r": re\-read\-init\-file
.br
"\ee[11~": "Function Key 1"
.RE
.PP
In this example,
.I C-u
is again bound to the function
.BR universal\-argument .
.I "C-x C-r"
is bound to the function
.BR re\-read\-init\-file ,
and
.I "ESC [ 1 1 ~"
is bound to insert the text
.if t \f(CWFunction Key 1\fP.
.if n ``Function Key 1''.
.PP
The full set of GNU Emacs style escape sequences available when specifying
key sequences is
.RS
.PD 0
.TP
.B \eC\-
control prefix
.TP
.B \eM\-
meta prefix
.TP
.B \ee
an escape character
.TP
.B \e\e
backslash
.TP
.B \e"
literal ", a double quote
.TP
.B \e'
literal ', a single quote
.RE
.PD
.PP
In addition to the GNU Emacs style escape sequences, a second
set of backslash escapes is available:
.RS
.PD 0
.TP
.B \ea
alert (bell)
.TP
.B \eb
backspace
.TP
.B \ed
delete
.TP
.B \ef
form feed
.TP
.B \en
newline
.TP
.B \er
carriage return
.TP
.B \et
horizontal tab
.TP
.B \ev
vertical tab
.TP
.B \e\fInnn\fP
the eight-bit character whose value is the octal value \fInnn\fP
(one to three digits)
.TP
.B \ex\fIHH\fP
the eight-bit character whose value is the hexadecimal value \fIHH\fP
(one or two hex digits)
.RE
.PD
.PP
When entering the text of a macro, single or double quotes should
be used to indicate a macro definition. Unquoted text
is assumed to be a function name.
In the macro body, the backslash escapes described above are expanded.
Backslash will quote any other character in the macro text,
including " and '.
.PP
.B Bash
allows the current readline key bindings to be displayed or modified
with the
.B bind
builtin command. The editing mode may be switched during interactive
use by using the
.B \-o
option to the
.B set
builtin command. Other programs using this library provide
similar mechanisms. The
.I inputrc
file may be edited and re-read if a program does not provide
any other means to incorporate new bindings.
.SS Variables
.PP
Readline has variables that can be used to further customize its
behavior. A variable may be set in the
.I inputrc
file with a statement of the form
.RS
.PP
\fBset\fP \fIvariable\-name\fP \fIvalue\fP
.RE
.PP
Except where noted, readline variables can take the values
.B On
or
.B Off
(without regard to case).
Unrecognized variable names are ignored.
When a variable value is read, empty or null values, "on" (case-insensitive),
and "1" are equivalent to \fBOn\fP. All other values are equivalent to
\fBOff\fP.
The variables and their default values are:
.PP
.PD 0
.TP
.B bell\-style (audible)
Controls what happens when readline wants to ring the terminal bell.
If set to \fBnone\fP, readline never rings the bell. If set to
\fBvisible\fP, readline uses a visible bell if one is available.
If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
.TP
.B bind\-tty\-special\-chars (On)
If set to \fBOn\fP, readline attempts to bind the control characters
treated specially by the kernel's terminal driver to their readline
equivalents.
.TP
.B colored\-stats (Off)
If set to \fBOn\fP, readline displays possible completions using different
colors to indicate their file type.
The color definitions are taken from the value of the \fBLS_COLORS\fP
environment variable.
.TP
.B comment\-begin (``#'')
The string that is inserted in \fBvi\fP mode when the
.B insert\-comment
command is executed.
This command is bound to
.B M\-#
in emacs mode and to
.B #
in vi command mode.
.TP
.B completion\-display\-width (-1)
The number of screen columns used to display possible matches
when performing completion.
The value is ignored if it is less than 0 or greater than the terminal
screen width.
A value of 0 will cause matches to be displayed one per line.
The default value is -1.
.TP
.B completion\-ignore\-case (Off)
If set to \fBOn\fP, readline performs filename matching and completion
in a case\-insensitive fashion.
.TP
.B completion\-map\-case (Off)
If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline
treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
performing case\-insensitive filename matching and completion.
.TP
.B completion\-prefix\-display\-length (0)
The length in characters of the common prefix of a list of possible
completions that is displayed without modification. When set to a
value greater than zero, common prefixes longer than this value are
replaced with an ellipsis when displaying possible completions.
.TP
.B completion\-query\-items (100)
This determines when the user is queried about viewing
the number of possible completions
generated by the \fBpossible\-completions\fP command.
It may be set to any integer value greater than or equal to
zero. If the number of possible completions is greater than
or equal to the value of this variable, the user is asked whether
or not he wishes to view them; otherwise they are simply listed
on the terminal. A negative value causes readline to never ask.
.TP
.B convert\-meta (On)
If set to \fBOn\fP, readline will convert characters with the
eighth bit set to an ASCII key sequence
by stripping the eighth bit and prefixing it with an
escape character (in effect, using escape as the \fImeta prefix\fP).
.TP
.B disable\-completion (Off)
If set to \fBOn\fP, readline will inhibit word completion. Completion
characters will be inserted into the line as if they had been
mapped to \fBself-insert\fP.
.TP
.B editing\-mode (emacs)
Controls whether readline begins with a set of key bindings similar
to \fIEmacs\fP or \fIvi\fP.
.B editing\-mode
can be set to either
.B emacs
or
.BR vi .
.TP
.B echo\-control\-characters (On)
When set to \fBOn\fP, on operating systems that indicate they support it,
readline echoes a character corresponding to a signal generated from the
keyboard.
.TP
.B enable\-keypad (Off)
When set to \fBOn\fP, readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys.
.TP
.B enable\-meta\-key (On)
When set to \fBOn\fP, readline will try to enable any meta modifier
key the terminal claims to support when it is called. On many terminals,
the meta key is used to send eight-bit characters.
.TP
.B expand\-tilde (Off)
If set to \fBOn\fP, tilde expansion is performed when readline
attempts word completion.
.TP
.B history\-preserve\-point (Off)
If set to \fBOn\fP, the history code attempts to place point at the
same location on each history line retrieved with \fBprevious-history\fP
or \fBnext-history\fP.
.TP
.B history\-size (0)
Set the maximum number of history entries saved in the history list.
If set to zero, any existing history entries are deleted and no new entries
are saved.
If set to a value less than zero, the number of history entries is not
limited.
By default, the number of history entries is not limited.
.TP
.B horizontal\-scroll\-mode (Off)
When set to \fBOn\fP, makes readline use a single line for display,
scrolling the input horizontally on a single screen line when it
becomes longer than the screen width rather than wrapping to a new line.
.TP
.B input\-meta (Off)
If set to \fBOn\fP, readline will enable eight-bit input (that is,
it will not clear the eighth bit in the characters it reads),
regardless of what the terminal claims it can support. The name
.B meta\-flag
is a synonym for this variable.
.TP
.B isearch\-terminators (``C\-[ C\-J'')
The string of characters that should terminate an incremental
search without subsequently executing the character as a command.
If this variable has not been given a value, the characters
\fIESC\fP and \fIC\-J\fP will terminate an incremental search.
.TP
.B keymap (emacs)
Set the current readline keymap. The set of legal keymap names is
\fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
vi-command\fP, and
.IR vi-insert .
\fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is
equivalent to \fIemacs-standard\fP. The default value is
.IR emacs .
The value of
.B editing\-mode
also affects the default keymap.
.TP
.B keyseq\-timeout (500)
Specifies the duration \fIreadline\fP will wait for a character when reading an
ambiguous key sequence (one that can form a complete key sequence using
the input read so far, or can take additional input to complete a longer
key sequence).
If no input is received within the timeout, \fIreadline\fP will use the shorter
but complete key sequence.
The value is specified in milliseconds, so a value of 1000 means that
\fIreadline\fP will wait one second for additional input.
If this variable is set to a value less than or equal to zero, or to a
non-numeric value, \fIreadline\fP will wait until another key is pressed to
decide which key sequence to complete.
.TP
.B mark\-directories (On)
If set to \fBOn\fP, completed directory names have a slash
appended.
.TP
.B mark\-modified\-lines (Off)
If set to \fBOn\fP, history lines that have been modified are displayed
with a preceding asterisk (\fB*\fP).
.TP
.B mark\-symlinked\-directories (Off)
If set to \fBOn\fP, completed names which are symbolic links to directories
have a slash appended (subject to the value of
\fBmark\-directories\fP).
.TP
.B match\-hidden\-files (On)
This variable, when set to \fBOn\fP, causes readline to match files whose
names begin with a `.' (hidden files) when performing filename
completion.
If set to \fBOff\fP, the leading `.' must be
supplied by the user in the filename to be completed.
.TP
.B menu\-complete\-display\-prefix (Off)
If set to \fBOn\fP, menu completion displays the common prefix of the
list of possible completions (which may be empty) before cycling through
the list.
.TP
.B output\-meta (Off)
If set to \fBOn\fP, readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sequence.
.TP
.B page\-completions (On)
If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
to display a screenful of possible completions at a time.
.TP
.B print\-completions\-horizontally (Off)
If set to \fBOn\fP, readline will display completions with matches
sorted horizontally in alphabetical order, rather than down the screen.
.TP
.B revert\-all\-at\-newline (Off)
If set to \fBOn\fP, readline will undo all changes to history lines
before returning when \fBaccept\-line\fP is executed. By default,
history lines may be modified and retain individual undo lists across
calls to \fBreadline\fP.
.TP
.B show\-all\-if\-ambiguous (Off)
This alters the default behavior of the completion functions. If
set to
.BR On ,
words which have more than one possible completion cause the
matches to be listed immediately instead of ringing the bell.
.TP
.B show\-all\-if\-unmodified (Off)
This alters the default behavior of the completion functions in
a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
If set to
.BR On ,
words which have more than one possible completion without any
possible partial completion (the possible completions don't share
a common prefix) cause the matches to be listed immediately instead
of ringing the bell.
.TP
.B show\-mode\-in\-prompt (Off)
If set to \fBOn\fP, add a character to the beginning of the prompt
indicating the editing mode: emacs (@), vi command (:) or vi
insertion (+).
.TP
.B skip\-completed\-text (Off)
If set to \fBOn\fP, this alters the default completion behavior when
inserting a single match into the line. It's only active when
performing completion in the middle of a word. If enabled, readline
does not insert characters from the completion that match characters
after point in the word being completed, so portions of the word
following the cursor are not duplicated.
.TP
.B visible\-stats (Off)
If set to \fBOn\fP, a character denoting a file's type as reported
by \fIstat\fP(2) is appended to the filename when listing possible
completions.
.PD
.SS Conditional Constructs
.PP
Readline implements a facility similar in spirit to the conditional
compilation features of the C preprocessor which allows key
bindings and variable settings to be performed as the result
of tests. There are four parser directives used.
.IP \fB$if\fP
The
.B $if
construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
readline. The text of the test extends to the end of the line;
no characters are required to isolate it.
.RS
.IP \fBmode\fP
The \fBmode=\fP form of the \fB$if\fP directive is used to test
whether readline is in emacs or vi mode.
This may be used in conjunction
with the \fBset keymap\fP command, for instance, to set bindings in
the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if
readline is starting out in emacs mode.
.IP \fBterm\fP
The \fBterm=\fP form may be used to include terminal-specific
key bindings, perhaps to bind the key sequences output by the
terminal's function keys. The word on the right side of the
.B =
is tested against the full name of the terminal and the portion
of the terminal name before the first \fB\-\fP. This allows
.I sun
to match both
.I sun
and
.IR sun\-cmd ,
for instance.
.IP \fBapplication\fP
The \fBapplication\fP construct is used to include
application-specific settings. Each program using the readline
library sets the \fIapplication name\fP, and an initialization
file can test for a particular value.
This could be used to bind key sequences to functions useful for
a specific program. For instance, the following command adds a
key sequence that quotes the current or previous word in \fBbash\fP:
.sp 1
.RS
.nf
\fB$if\fP Bash
# Quote the current or previous word
"\eC-xq": "\eeb\e"\eef\e""
\fB$endif\fP
.fi
.RE
.RE
.IP \fB$endif\fP
This command, as seen in the previous example, terminates an
\fB$if\fP command.
.IP \fB$else\fP
Commands in this branch of the \fB$if\fP directive are executed if
the test fails.
.IP \fB$include\fP
This directive takes a single filename as an argument and reads commands
and bindings from that file. For example, the following directive
would read \fI/etc/inputrc\fP:
.sp 1
.RS
.nf
\fB$include\fP \^ \fI/etc/inputrc\fP
.fi
.RE
.SH SEARCHING
.PP
Readline provides commands for searching through the command history
for lines containing a specified string.
There are two search modes:
.I incremental
and
.IR non-incremental .
.PP
Incremental searches begin before the user has finished typing the
search string.
As each character of the search string is typed, readline displays
the next entry from the history matching the string typed so far.
An incremental search requires only as many characters as needed to
find the desired history entry.
To search backward in the history for a particular string, type
\fBC\-r\fP. Typing \fBC\-s\fP searches forward through the history.
The characters present in the value of the \fBisearch-terminators\fP
variable are used to terminate an incremental search.
If that variable has not been assigned a value the \fIEscape\fP and
\fBC\-J\fP characters will terminate an incremental search.
\fBC\-G\fP will abort an incremental search and restore the original
line.
When the search is terminated, the history entry containing the
search string becomes the current line.
.PP
To find other matching entries in the history list, type \fBC\-s\fP or
\fBC\-r\fP as appropriate.
This will search backward or forward in the history for the next
line matching the search string typed so far.
Any other key sequence bound to a readline command will terminate
the search and execute that command.
For instance, a newline will terminate the search and accept
the line, thereby executing the command from the history list.
A movement command will terminate the search, make the last line found
the current line, and begin editing.
.PP
Non-incremental searches read the entire search string before starting
to search for matching history lines. The search string may be
typed by the user or be part of the contents of the current line.
.SH EDITING COMMANDS
.PP
The following is a list of the names of the commands and the default
key sequences to which they are bound.
Command names without an accompanying key sequence are unbound by default.
.PP
In the following descriptions, \fIpoint\fP refers to the current cursor
position, and \fImark\fP refers to a cursor position saved by the
\fBset\-mark\fP command.
The text between the point and mark is referred to as the \fIregion\fP.
.SS Commands for Moving
.PP
.PD 0
.TP
.B beginning\-of\-line (C\-a)
Move to the start of the current line.
.TP
.B end\-of\-line (C\-e)
Move to the end of the line.
.TP
.B forward\-char (C\-f)
Move forward a character.
.TP
.B backward\-char (C\-b)
Move back a character.
.TP
.B forward\-word (M\-f)
Move forward to the end of the next word. Words are composed of
alphanumeric characters (letters and digits).
.TP
.B backward\-word (M\-b)
Move back to the start of the current or previous word. Words are
composed of alphanumeric characters (letters and digits).
.TP
.B clear\-screen (C\-l)
Clear the screen leaving the current line at the top of the screen.
With an argument, refresh the current line without clearing the
screen.
.TP
.B redraw\-current\-line
Refresh the current line.
.PD
.SS Commands for Manipulating the History
.PP
.PD 0
.TP
.B accept\-line (Newline, Return)
Accept the line regardless of where the cursor is.
If this line is
non-empty, it may be added to the history list for future recall with
\fBadd_history()\fP.
If the line is a modified history line, the history line is restored to its original state.
.TP
.B previous\-history (C\-p)
Fetch the previous command from the history list, moving back in
the list.
.TP
.B next\-history (C\-n)
Fetch the next command from the history list, moving forward in the
list.
.TP
.B beginning\-of\-history (M\-<)
Move to the first line in the history.
.TP
.B end\-of\-history (M\->)
Move to the end of the input history, i.e., the line currently being
entered.
.TP
.B reverse\-search\-history (C\-r)
Search backward starting at the current line and moving `up' through
the history as necessary. This is an incremental search.
.TP
.B forward\-search\-history (C\-s)
Search forward starting at the current line and moving `down' through
the history as necessary. This is an incremental search.
.TP
.B non\-incremental\-reverse\-search\-history (M\-p)
Search backward through the history starting at the current line
using a non-incremental search for a string supplied by the user.
.TP
.B non\-incremental\-forward\-search\-history (M\-n)
Search forward through the history using a non-incremental search
for a string supplied by the user.
.TP
.B history\-search\-backward
Search backward through the history for the string of characters
between the start of the current line and the current cursor
position (the \fIpoint\fP).
The search string must match at the beginning of a history line.
This is a non-incremental search.
.TP
.B history\-search\-forward
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string must match at the beginning of a history line.
This is a non-incremental search.
.TP
.B history\-substring\-search\-backward
Search backward through the history for the string of characters
between the start of the current line and the current cursor
position (the \fIpoint\fP).
The search string may match anywhere in a history line.
This is a non-incremental search.
.TP
.B history\-substring\-search\-forward
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string may match anywhere in a history line.
This is a non-incremental search.
.TP
.B yank\-nth\-arg (M\-C\-y)
Insert the first argument to the previous command (usually
the second word on the previous line) at point.
With an argument
.IR n ,
insert the \fIn\fPth word from the previous command (the words
in the previous command begin with word 0). A negative argument
inserts the \fIn\fPth word from the end of the previous command.
Once the argument \fIn\fP is computed, the argument is extracted
as if the "!\fIn\fP" history expansion had been specified.
.TP
.B
yank\-last\-arg (M\-.\^, M\-_\^)
Insert the last argument to the previous command (the last word of
the previous history entry).
With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
Successive calls to \fByank\-last\-arg\fP move back through the history
list, inserting the last word (or the word specified by the argument to
the first call) of each line in turn.
Any numeric argument supplied to these successive calls determines
the direction to move through the history. A negative argument switches
the direction through the history (back or forward).
The history expansion facilities are used to extract the last argument,
as if the "!$" history expansion had been specified.
.PD
.SS Commands for Changing Text
.PP
.PD 0
.TP
.B \fIend\-of\-file\fP (usually C\-d)
The character indicating end-of-file as set, for example, by
.if t \f(CWstty\fP.
.if n ``stty''.
If this character is read when there are no characters
on the line, and point is at the beginning of the line, Readline
interprets it as the end of input and returns
.SM
.BR EOF .
.TP
.B delete\-char (C\-d)
Delete the character at point.
If this function is bound to the
same character as the tty \fBEOF\fP character, as \fBC\-d\fP
commonly is, see above for the effects.
.TP
.B backward\-delete\-char (Rubout)
Delete the character behind the cursor. When given a numeric argument,
save the deleted text on the kill ring.
.TP
.B forward\-backward\-delete\-char
Delete the character under the cursor, unless the cursor is at the
end of the line, in which case the character behind the cursor is
deleted.
.TP
.B quoted\-insert (C\-q, C\-v)
Add the next character that you type to the line verbatim. This is
how to insert characters like \fBC\-q\fP, for example.
.TP
.B tab\-insert (M-TAB)
Insert a tab character.
.TP
.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
Insert the character typed.
.TP
.B transpose\-chars (C\-t)
Drag the character before point forward over the character at point,
moving point forward as well.
If point is at the end of the line, then this transposes
the two characters before point.
Negative arguments have no effect.
.TP
.B transpose\-words (M\-t)
Drag the word before point past the word after point,
moving point over that word as well.
If point is at the end of the line, this transposes
the last two words on the line.
.TP
.B upcase\-word (M\-u)
Uppercase the current (or following) word. With a negative argument,
uppercase the previous word, but do not move point.
.TP
.B downcase\-word (M\-l)
Lowercase the current (or following) word. With a negative argument,
lowercase the previous word, but do not move point.
.TP
.B capitalize\-word (M\-c)
Capitalize the current (or following) word. With a negative argument,
capitalize the previous word, but do not move point.
.TP
.B overwrite\-mode
Toggle overwrite mode. With an explicit positive numeric argument,
switches to overwrite mode. With an explicit non-positive numeric
argument, switches to insert mode. This command affects only
\fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
Each call to \fIreadline()\fP starts in insert mode.
In overwrite mode, characters bound to \fBself\-insert\fP replace
the text at point rather than pushing the text to the right.
Characters bound to \fBbackward\-delete\-char\fP replace the character
before point with a space. By default, this command is unbound.
.PD
.SS Killing and Yanking
.PP
.PD 0
.TP
.B kill\-line (C\-k)
Kill the text from point to the end of the line.
.TP
.B backward\-kill\-line (C\-x Rubout)
Kill backward to the beginning of the line.
.TP
.B unix\-line\-discard (C\-u)
Kill backward from point to the beginning of the line.
The killed text is saved on the kill-ring.
.\" There is no real difference between this and backward-kill-line
.TP
.B kill\-whole\-line
Kill all characters on the current line, no matter where point is.
.TP
.B kill\-word (M\-d)
Kill from point the end of the current word, or if between
words, to the end of the next word. Word boundaries are the same as
those used by \fBforward\-word\fP.
.TP
.B backward\-kill\-word (M\-Rubout)
Kill the word behind point.
Word boundaries are the same as those used by \fBbackward\-word\fP.
.TP
.B unix\-word\-rubout (C\-w)
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
.TP
.B unix\-filename\-rubout
Kill the word behind point, using white space and the slash character
as the word boundaries.
The killed text is saved on the kill-ring.
.TP
.B delete\-horizontal\-space (M\-\e)
Delete all spaces and tabs around point.
.TP
.B kill\-region
Kill the text between the point and \fImark\fP (saved cursor position).
This text is referred to as the \fIregion\fP.
.TP
.B copy\-region\-as\-kill
Copy the text in the region to the kill buffer.
.TP
.B copy\-backward\-word
Copy the word before point to the kill buffer.
The word boundaries are the same as \fBbackward\-word\fP.
.TP
.B copy\-forward\-word
Copy the word following point to the kill buffer.
The word boundaries are the same as \fBforward\-word\fP.
.TP
.B yank (C\-y)
Yank the top of the kill ring into the buffer at point.
.TP
.B yank\-pop (M\-y)
Rotate the kill ring, and yank the new top. Only works following
.B yank
or
.BR yank\-pop .
.PD
.SS Numeric Arguments
.PP
.PD 0
.TP
.B digit\-argument (M\-0, M\-1, ..., M\-\-)
Add this digit to the argument already accumulating, or start a new
argument. M\-\- starts a negative argument.
.TP
.B universal\-argument
This is another way to specify an argument.
If this command is followed by one or more digits, optionally with a
leading minus sign, those digits define the argument.
If the command is followed by digits, executing
.B universal\-argument
again ends the numeric argument, but is otherwise ignored.
As a special case, if this command is immediately followed by a
character that is neither a digit or minus sign, the argument count
for the next command is multiplied by four.
The argument count is initially one, so executing this function the
first time makes the argument count four, a second time makes the
argument count sixteen, and so on.
.PD
.SS Completing
.PP
.PD 0
.TP
.B complete (TAB)
Attempt to perform completion on the text before point.
The actual completion performed is application-specific.
.BR Bash ,
for instance, attempts completion treating the text as a variable
(if the text begins with \fB$\fP), username (if the text begins with
\fB~\fP), hostname (if the text begins with \fB@\fP), or
command (including aliases and functions) in turn. If none
of these produces a match, filename completion is attempted.
.BR Gdb ,
on the other hand,
allows completion of program functions and variables, and
only attempts filename completion under certain circumstances.
.TP
.B possible\-completions (M\-?)
List the possible completions of the text before point.
When displaying completions, readline sets the number of columns used
for display to the value of \fBcompletion-display-width\fP, the value of
the environment variable
.SM
.BR COLUMNS ,
or the screen width, in that order.
.TP
.B insert\-completions (M\-*)
Insert all completions of the text before point
that would have been generated by
\fBpossible\-completions\fP.
.TP
.B menu\-complete
Similar to \fBcomplete\fP, but replaces the word to be completed
with a single match from the list of possible completions.
Repeated execution of \fBmenu\-complete\fP steps through the list
of possible completions, inserting each match in turn.
At the end of the list of completions, the bell is rung
(subject to the setting of \fBbell\-style\fP)
and the original text is restored.
An argument of \fIn\fP moves \fIn\fP positions forward in the list
of matches; a negative argument may be used to move backward
through the list.
This command is intended to be bound to \fBTAB\fP, but is unbound
by default.
.TP
.B menu\-complete\-backward
Identical to \fBmenu\-complete\fP, but moves backward through the list
of possible completions, as if \fBmenu\-complete\fP had been given a
negative argument. This command is unbound by default.
.TP
.B delete\-char\-or\-list
Deletes the character under the cursor if not at the beginning or
end of the line (like \fBdelete-char\fP).
If at the end of the line, behaves identically to
\fBpossible-completions\fP.
.PD
.SS Keyboard Macros
.PP
.PD 0
.TP
.B start\-kbd\-macro (C\-x (\^)
Begin saving the characters typed into the current keyboard macro.
.TP
.B end\-kbd\-macro (C\-x )\^)
Stop saving the characters typed into the current keyboard macro
and store the definition.
.TP
.B call\-last\-kbd\-macro (C\-x e)
Re-execute the last keyboard macro defined, by making the characters
in the macro appear as if typed at the keyboard.
.B print\-last\-kbd\-macro ()
Print the last keyboard macro defined in a format suitable for the
\fIinputrc\fP file.
.PD
.SS Miscellaneous
.PP
.PD 0
.TP
.B re\-read\-init\-file (C\-x C\-r)
Read in the contents of the \fIinputrc\fP file, and incorporate
any bindings or variable assignments found there.
.TP
.B abort (C\-g)
Abort the current editing command and
ring the terminal's bell (subject to the setting of
.BR bell\-style ).
.TP
.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
If the metafied character \fIx\fP is lowercase, run the command
that is bound to the corresponding uppercase character.
.TP
.B prefix\-meta (ESC)
Metafy the next character typed.
.SM
.B ESC
.B f
is equivalent to
.BR Meta\-f .
.TP
.B undo (C\-_, C\-x C\-u)
Incremental undo, separately remembered for each line.
.TP
.B revert\-line (M\-r)
Undo all changes made to this line. This is like executing the
.B undo
command enough times to return the line to its initial state.
.TP
.B tilde\-expand (M\-&)
Perform tilde expansion on the current word.
.TP
.B set\-mark (C\-@, M\-)
Set the mark to the point. If a
numeric argument is supplied, the mark is set to that position.
.TP
.B exchange\-point\-and\-mark (C\-x C\-x)
Swap the point with the mark. The current cursor position is set to
the saved position, and the old cursor position is saved as the mark.
.TP
.B character\-search (C\-])
A character is read and point is moved to the next occurrence of that
character. A negative count searches for previous occurrences.
.TP
.B character\-search\-backward (M\-C\-])
A character is read and point is moved to the previous occurrence of that
character. A negative count searches for subsequent occurrences.
.TP
.B skip\-csi\-sequence
Read enough characters to consume a multi-key sequence such as those
defined for keys like Home and End. Such sequences begin with a
Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is
bound to "\e[", keys producing such sequences will have no effect
unless explicitly bound to a readline command, instead of inserting
stray characters into the editing buffer. This is unbound by default,
but usually bound to ESC\-[.
.TP
.B insert\-comment (M\-#)
Without a numeric argument, the value of the readline
.B comment\-begin
variable is inserted at the beginning of the current line.
If a numeric argument is supplied, this command acts as a toggle: if
the characters at the beginning of the line do not match the value
of \fBcomment\-begin\fP, the value is inserted, otherwise
the characters in \fBcomment-begin\fP are deleted from the beginning of
the line.
In either case, the line is accepted as if a newline had been typed.
The default value of
.B comment\-begin
makes the current line a shell comment.
If a numeric argument causes the comment character to be removed, the line
will be executed by the shell.
.TP
.B dump\-functions
Print all of the functions and their key bindings to the
readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
.B dump\-variables
Print all of the settable variables and their values to the
readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
.B dump\-macros
Print all of the readline key sequences bound to macros and the
strings they output. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
.B emacs\-editing\-mode (C\-e)
When in
.B vi
command mode, this causes a switch to
.B emacs
editing mode.
.TP
.B vi\-editing\-mode (M\-C\-j)
When in
.B emacs
editing mode, this causes a switch to
.B vi
editing mode.
.PD
.SH DEFAULT KEY BINDINGS
.LP
The following is a list of the default emacs and vi bindings.
Characters with the eighth bit set are written as M\-, and
are referred to as
.I metafied
characters.
The printable ASCII characters not mentioned in the list of emacs
standard bindings are bound to the
.B self\-insert
function, which just inserts the given character into the input line.
In vi insertion mode, all characters not specifically mentioned are
bound to
.BR self\-insert .
Characters assigned to signal generation by
.IR stty (1)
or the terminal driver, such as C-Z or C-C,
retain that function.
Upper and lower case metafied characters are bound to the same function in
the emacs mode meta keymap.
The remaining characters are unbound, which causes readline
to ring the bell (subject to the setting of the
.B bell\-style
variable).
.SS Emacs Mode
.RS +.6i
.nf
.ta 2.5i
.sp
Emacs Standard bindings
.sp
"C-@" set-mark
"C-A" beginning-of-line
"C-B" backward-char
"C-D" delete-char
"C-E" end-of-line
"C-F" forward-char
"C-G" abort
"C-H" backward-delete-char
"C-I" complete
"C-J" accept-line
"C-K" kill-line
"C-L" clear-screen
"C-M" accept-line
"C-N" next-history
"C-P" previous-history
"C-Q" quoted-insert
"C-R" reverse-search-history
"C-S" forward-search-history
"C-T" transpose-chars
"C-U" unix-line-discard
"C-V" quoted-insert
"C-W" unix-word-rubout
"C-Y" yank
"C-]" character-search
"C-_" undo
"\^ " to "/" self-insert
"0" to "9" self-insert
":" to "~" self-insert
"C-?" backward-delete-char
.PP
Emacs Meta bindings
.sp
"M-C-G" abort
"M-C-H" backward-kill-word
"M-C-I" tab-insert
"M-C-J" vi-editing-mode
"M-C-M" vi-editing-mode
"M-C-R" revert-line
"M-C-Y" yank-nth-arg
"M-C-[" complete
"M-C-]" character-search-backward
"M-space" set-mark
"M-#" insert-comment
"M-&" tilde-expand
"M-*" insert-completions
"M--" digit-argument
"M-." yank-last-arg
"M-0" digit-argument
"M-1" digit-argument
"M-2" digit-argument
"M-3" digit-argument
"M-4" digit-argument
"M-5" digit-argument
"M-6" digit-argument
"M-7" digit-argument
"M-8" digit-argument
"M-9" digit-argument
"M-<" beginning-of-history
"M-=" possible-completions
"M->" end-of-history
"M-?" possible-completions
"M-B" backward-word
"M-C" capitalize-word
"M-D" kill-word
"M-F" forward-word
"M-L" downcase-word
"M-N" non-incremental-forward-search-history
"M-P" non-incremental-reverse-search-history
"M-R" revert-line
"M-T" transpose-words
"M-U" upcase-word
"M-Y" yank-pop
"M-\e" delete-horizontal-space
"M-~" tilde-expand
"M-C-?" backward-kill-word
"M-_" yank-last-arg
.PP
Emacs Control-X bindings
.sp
"C-XC-G" abort
"C-XC-R" re-read-init-file
"C-XC-U" undo
"C-XC-X" exchange-point-and-mark
"C-X(" start-kbd-macro
"C-X)" end-kbd-macro
"C-XE" call-last-kbd-macro
"C-XC-?" backward-kill-line
.sp
.RE
.SS VI Mode bindings
.RS +.6i
.nf
.ta 2.5i
.sp
.PP
VI Insert Mode functions
.sp
"C-D" vi-eof-maybe
"C-H" backward-delete-char
"C-I" complete
"C-J" accept-line
"C-M" accept-line
"C-R" reverse-search-history
"C-S" forward-search-history
"C-T" transpose-chars
"C-U" unix-line-discard
"C-V" quoted-insert
"C-W" unix-word-rubout
"C-Y" yank
"C-[" vi-movement-mode
"C-_" undo
"\^ " to "~" self-insert
"C-?" backward-delete-char
.PP
VI Command Mode functions
.sp
"C-D" vi-eof-maybe
"C-E" emacs-editing-mode
"C-G" abort
"C-H" backward-char
"C-J" accept-line
"C-K" kill-line
"C-L" clear-screen
"C-M" accept-line
"C-N" next-history
"C-P" previous-history
"C-Q" quoted-insert
"C-R" reverse-search-history
"C-S" forward-search-history
"C-T" transpose-chars
"C-U" unix-line-discard
"C-V" quoted-insert
"C-W" unix-word-rubout
"C-Y" yank
"C-_" vi-undo
"\^ " forward-char
"#" insert-comment
"$" end-of-line
"%" vi-match
"&" vi-tilde-expand
"*" vi-complete
"+" next-history
"," vi-char-search
"-" previous-history
"." vi-redo
"/" vi-search
"0" beginning-of-line
"1" to "9" vi-arg-digit
";" vi-char-search
"=" vi-complete
"?" vi-search
"A" vi-append-eol
"B" vi-prev-word
"C" vi-change-to
"D" vi-delete-to
"E" vi-end-word
"F" vi-char-search
"G" vi-fetch-history
"I" vi-insert-beg
"N" vi-search-again
"P" vi-put
"R" vi-replace
"S" vi-subst
"T" vi-char-search
"U" revert-line
"W" vi-next-word
"X" backward-delete-char
"Y" vi-yank-to
"\e" vi-complete
"^" vi-first-print
"_" vi-yank-arg
"`" vi-goto-mark
"a" vi-append-mode
"b" vi-prev-word
"c" vi-change-to
"d" vi-delete-to
"e" vi-end-word
"f" vi-char-search
"h" backward-char
"i" vi-insertion-mode
"j" next-history
"k" prev-history
"l" forward-char
"m" vi-set-mark
"n" vi-search-again
"p" vi-put
"r" vi-change-char
"s" vi-subst
"t" vi-char-search
"u" vi-undo
"w" vi-next-word
"x" vi-delete
"y" vi-yank-to
"|" vi-column
"~" vi-change-case
.RE
.SH "SEE ALSO"
.PD 0
.TP
\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
.TP
\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
.TP
\fIbash\fP(1)
.PD
.SH FILES
.PD 0
.TP
.FN ~/.inputrc
Individual \fBreadline\fP initialization file
.PD
.SH AUTHORS
Brian Fox, Free Software Foundation
.br
bfox@gnu.org
.PP
Chet Ramey, Case Western Reserve University
.br
chet.ramey@case.edu
.SH BUG REPORTS
If you find a bug in
.B readline,
you should report it. But first, you should
make sure that it really is a bug, and that it appears in the latest
version of the
.B readline
library that you have.
.PP
Once you have determined that a bug actually exists, mail a
bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
If you have a fix, you are welcome to mail that
as well! Suggestions and `philosophical' bug reports may be mailed
to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
newsgroup
.BR gnu.bash.bug .
.PP
Comments and bug reports concerning
this manual page should be directed to
.IR chet.ramey@case.edu .
.SH BUGS
.PP
It's too big and too slow.
readline-6.3/doc/history.3 0000644 0000436 0000024 00000053422 12262621035 014305 0 ustar chet staff .\"
.\" MAN PAGE COMMENTS to
.\"
.\" Chet Ramey
.\" Information Network Services
.\" Case Western Reserve University
.\" chet.ramey@case.edu
.\"
.\" Last Change: Thu Thu Jun 27 10:34:44 EDT 2013
.\"
.TH HISTORY 3 "2013 June 27" "GNU History 6.3"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
.\"
.de FN
\fI\|\\$1\|\fP
..
.ds lp \fR\|(\fP
.ds rp \fR\|)\fP
.\" FnN return-value fun-name N arguments
.de Fn1
\fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp
.br
..
.de Fn2
.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp
.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp
.br
..
.de Fn3
.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp
.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp
.br
..
.de Vb
\fI\\$1\fP \fB\\$2\fP
.br
..
.SH NAME
history \- GNU History Library
.SH COPYRIGHT
.if t The GNU History Library is Copyright \(co 1989-2011 by the Free Software Foundation, Inc.
.if n The GNU History Library is Copyright (C) 1989-2011 by the Free Software Foundation, Inc.
.SH DESCRIPTION
Many programs read input from the user a line at a time. The GNU
History library is able to keep track of those lines, associate arbitrary
data with each line, and utilize information from previous lines in
composing new ones.
.PP
.SH "HISTORY EXPANSION"
.PP
The history library supports a history expansion feature that
is identical to the history expansion in
.BR bash.
This section describes what syntax features are available.
.PP
History expansions introduce words from the history list into
the input stream, making it easy to repeat commands, insert the
arguments to a previous command into the current input line, or
fix errors in previous commands quickly.
.PP
History expansion is usually performed immediately after a complete line
is read.
It takes place in two parts.
The first is to determine which line from the history list
to use during substitution.
The second is to select portions of that line for inclusion into
the current one.
The line selected from the history is the \fIevent\fP,
and the portions of that line that are acted upon are \fIwords\fP.
Various \fImodifiers\fP are available to manipulate the selected words.
The line is broken into words in the same fashion as \fBbash\fP
does when reading input,
so that several words that would otherwise be separated
are considered one word when surrounded by quotes (see the
description of \fBhistory_tokenize()\fP below).
History expansions are introduced by the appearance of the
history expansion character, which is \^\fB!\fP\^ by default.
Only backslash (\^\fB\e\fP\^) and single quotes can quote
the history expansion character.
.SS Event Designators
.PP
An event designator is a reference to a command line entry in the
history list.
Unless the reference is absolute, events are relative to the current
position in the history list.
.PP
.PD 0
.TP
.B !
Start a history substitution, except when followed by a
.BR blank ,
newline, = or (.
.TP
.B !\fIn\fR
Refer to command line
.IR n .
.TP
.B !\-\fIn\fR
Refer to the current command minus
.IR n .
.TP
.B !!
Refer to the previous command. This is a synonym for `!\-1'.
.TP
.B !\fIstring\fR
Refer to the most recent command
preceding the current position in the history list
starting with
.IR string .
.TP
.B !?\fIstring\fR\fB[?]\fR
Refer to the most recent command
preceding the current position in the history list
containing
.IR string .
The trailing \fB?\fP may be omitted if
.I string
is followed immediately by a newline.
.TP
.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
Quick substitution. Repeat the last command, replacing
.I string1
with
.IR string2 .
Equivalent to
``!!:s/\fIstring1\fP/\fIstring2\fP/''
(see \fBModifiers\fP below).
.TP
.B !#
The entire command line typed so far.
.PD
.SS Word Designators
.PP
Word designators are used to select desired words from the event.
A
.B :
separates the event specification from the word designator.
It may be omitted if the word designator begins with a
.BR ^ ,
.BR $ ,
.BR * ,
.BR \- ,
or
.BR % .
Words are numbered from the beginning of the line,
with the first word being denoted by 0 (zero).
Words are inserted into the current line separated by single spaces.
.PP
.PD 0
.TP
.B 0 (zero)
The zeroth word. For the shell, this is the command
word.
.TP
.I n
The \fIn\fRth word.
.TP
.B ^
The first argument. That is, word 1.
.TP
.B $
The last word. This is usually the last argument, but will expand to the
zeroth word if there is only one word in the line.
.TP
.B %
The word matched by the most recent `?\fIstring\fR?' search.
.TP
.I x\fB\-\fPy
A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
.TP
.B *
All of the words but the zeroth. This is a synonym
for `\fI1\-$\fP'. It is not an error to use
.B *
if there is just one
word in the event; the empty string is returned in that case.
.TP
.B x*
Abbreviates \fIx\-$\fP.
.TP
.B x\-
Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
.PD
.PP
If a word designator is supplied without an event specification, the
previous command is used as the event.
.SS Modifiers
.PP
After the optional word designator, there may appear a sequence of
one or more of the following modifiers, each preceded by a `:'.
.PP
.PD 0
.PP
.TP
.B h
Remove a trailing file name component, leaving only the head.
.TP
.B t
Remove all leading file name components, leaving the tail.
.TP
.B r
Remove a trailing suffix of the form \fI.xxx\fP, leaving the
basename.
.TP
.B e
Remove all but the trailing suffix.
.TP
.B p
Print the new command but do not execute it.
.TP
.B q
Quote the substituted words, escaping further substitutions.
.TP
.B x
Quote the substituted words as with
.BR q ,
but break into words at
.B blanks
and newlines.
.TP
.B s/\fIold\fP/\fInew\fP/
Substitute
.I new
for the first occurrence of
.I old
in the event line. Any delimiter can be used in place of /. The
final delimiter is optional if it is the last character of the
event line. The delimiter may be quoted in
.I old
and
.I new
with a single backslash. If & appears in
.IR new ,
it is replaced by
.IR old .
A single backslash will quote the &. If
.I old
is null, it is set to the last
.I old
substituted, or, if no previous history substitutions took place,
the last
.I string
in a
.B !?\fIstring\fR\fB[?]\fR
search.
.TP
.B &
Repeat the previous substitution.
.TP
.B g
Cause changes to be applied over the entire event line. This is
used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
or `\fB:&\fP'. If used with
`\fB:s\fP', any delimiter can be used
in place of /, and the final delimiter is optional
if it is the last character of the event line.
An \fBa\fP may be used as a synonym for \fBg\fP.
.TP
.B G
Apply the following `\fBs\fP' modifier once to each word in the event line.
.PD
.SH "PROGRAMMING WITH HISTORY FUNCTIONS"
This section describes how to use the History library in other programs.
.SS Introduction to History
.PP
The programmer using the History library has available functions
for remembering lines on a history list, associating arbitrary data
with a line, removing lines from the list, searching through the list
for a line containing an arbitrary text string, and referencing any line
in the list directly. In addition, a history \fIexpansion\fP function
is available which provides for a consistent user interface across
different programs.
.PP
The user using programs written with the History library has the
benefit of a consistent user interface with a set of well-known
commands for manipulating the text of previous lines and using that text
in new commands. The basic history manipulation commands are
identical to
the history substitution provided by \fBbash\fP.
.PP
If the programmer desires, he can use the Readline library, which
includes some history manipulation by default, and has the added
advantage of command line editing.
.PP
Before declaring any functions using any functionality the History
library provides in other code, an application writer should include
the file
.FN
in any file that uses the
History library's features. It supplies extern declarations for all
of the library's public functions and variables, and declares all of
the public data structures.
.SS History Storage
.PP
The history list is an array of history entries. A history entry is
declared as follows:
.PP
.Vb "typedef void *" histdata_t;
.PP
.nf
typedef struct _hist_entry {
char *line;
char *timestamp;
histdata_t data;
} HIST_ENTRY;
.fi
.PP
The history list itself might therefore be declared as
.PP
.Vb "HIST_ENTRY **" the_history_list;
.PP
The state of the History library is encapsulated into a single structure:
.PP
.nf
/*
* A structure used to pass around the current state of the history.
*/
typedef struct _hist_state {
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
} HISTORY_STATE;
.fi
.PP
If the flags member includes \fBHS_STIFLED\fP, the history has been
stifled.
.SH "History Functions"
.PP
This section describes the calling sequence for the various functions
exported by the GNU History library.
.SS Initializing History and State Management
This section describes functions used to initialize and manage
the state of the History library when you want to use the history
functions in your program.
.Fn1 void using_history void
Begin a session in which the history functions might be used. This
initializes the interactive variables.
.Fn1 "HISTORY_STATE *" history_get_history_state void
Return a structure describing the current state of the input history.
.Fn1 void history_set_history_state "HISTORY_STATE *state"
Set the state of the history list according to \fIstate\fP.
.SS History List Management
These functions manage individual entries on the history list, or set
parameters managing the list itself.
.Fn1 void add_history "const char *string"
Place \fIstring\fP at the end of the history list. The associated data
field (if any) is set to \fBNULL\fP.
.Fn1 void add_history_time "const char *string"
Change the time stamp associated with the most recent history entry to
\fIstring\fP.
.Fn1 "HIST_ENTRY *" remove_history "int which"
Remove history entry at offset \fIwhich\fP from the history. The
removed element is returned so you can free the line, data,
and containing structure.
.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
Free the history entry \fIhistent\fP and any history library private
data associated with it. Returns the application-specific data
so the caller can dispose of it.
.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data"
Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP.
This returns the old entry so the caller can dispose of any
application-specific data. In the case
of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned.
.Fn1 void clear_history "void"
Clear the history list by deleting all the entries.
.Fn1 void stifle_history "int max"
Stifle the history list, remembering only the last \fImax\fP entries.
.Fn1 int unstifle_history "void"
Stop stifling the history. This returns the previously-set
maximum number of history entries (as set by \fBstifle_history()\fP).
history was stifled. The value is positive if the history was
stifled, negative if it wasn't.
.Fn1 int history_is_stifled "void"
Returns non-zero if the history is stifled, zero if it is not.
.SS Information About the History List
These functions return information about the entire history list or
individual list entries.
.Fn1 "HIST_ENTRY **" history_list "void"
Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the
current input history. Element 0 of this list is the beginning of time.
If there is no history, return \fBNULL\fP.
.Fn1 int where_history "void"
Returns the offset of the current history element.
.Fn1 "HIST_ENTRY *" current_history "void"
Return the history entry at the current position, as determined by
\fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP
pointer.
.Fn1 "HIST_ENTRY *" history_get "int offset"
Return the history entry at position \fIoffset\fP, starting from
\fBhistory_base\fP.
If there is no entry there, or if \fIoffset\fP
is greater than the history length, return a \fBNULL\fP pointer.
.Fn1 "time_t" history_get_time "HIST_ENTRY *"
Return the time stamp associated with the history entry passed as the argument.
.Fn1 int history_total_bytes "void"
Return the number of bytes that the primary history entries are using.
This function returns the sum of the lengths of all the lines in the
history.
.SS Moving Around the History List
These functions allow the current index into the history list to be
set or changed.
.Fn1 int history_set_pos "int pos"
Set the current history offset to \fIpos\fP, an absolute index
into the list.
Returns 1 on success, 0 if \fIpos\fP is less than zero or greater
than the number of history entries.
.Fn1 "HIST_ENTRY *" previous_history "void"
Back up the current history offset to the previous history entry, and
return a pointer to that entry. If there is no previous entry, return
a \fBNULL\fP pointer.
.Fn1 "HIST_ENTRY *" next_history "void"
Move the current history offset forward to the next history entry, and
return the a pointer to that entry. If there is no next entry, return
a \fBNULL\fP pointer.
.SS Searching the History List
These functions allow searching of the history list for entries containing
a specific string. Searching may be performed both forward and backward
from the current history position. The search may be \fIanchored\fP,
meaning that the string must match at the beginning of the history entry.
.Fn2 int history_search "const char *string" "int direction"
Search the history for \fIstring\fP, starting at the current history offset.
If \fIdirection\fP is less than 0, then the search is through
previous entries, otherwise through subsequent entries.
If \fIstring\fP is found, then
the current history index is set to that history entry, and the value
returned is the offset in the line of the entry where
\fIstring\fP was found. Otherwise, nothing is changed, and a -1 is
returned.
.Fn2 int history_search_prefix "const char *string" "int direction"
Search the history for \fIstring\fP, starting at the current history
offset. The search is anchored: matching lines must begin with
\fIstring\fP. If \fIdirection\fP is less than 0, then the search is
through previous entries, otherwise through subsequent entries.
If \fIstring\fP is found, then the
current history index is set to that entry, and the return value is 0.
Otherwise, nothing is changed, and a -1 is returned.
.Fn3 int history_search_pos "const char *string" "int direction" "int pos"
Search for \fIstring\fP in the history list, starting at \fIpos\fP, an
absolute index into the list. If \fIdirection\fP is negative, the search
proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute
index of the history element where \fIstring\fP was found, or -1 otherwise.
.SS Managing the History File
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
.Fn1 int read_history "const char *filename"
Add the contents of \fIfilename\fP to the history list, a line at a time.
If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP.
Returns 0 if successful, or \fBerrno\fP if not.
.Fn3 int read_history_range "const char *filename" "int from" "int to"
Read a range of lines from \fIfilename\fP, adding them to the history list.
Start reading at line \fIfrom\fP and end at \fIto\fP.
If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than
\fIfrom\fP, then read until the end of the file. If \fIfilename\fP is
\fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful,
or \fBerrno\fP if not.
.Fn1 int write_history "const char *filename"
Write the current history to \fIfilename\fP, overwriting \fIfilename\fP
if necessary.
If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP.
Returns 0 on success, or \fBerrno\fP on a read or write error.
.Fn2 int append_history "int nelements" "const char *filename"
Append the last \fInelements\fP of the history list to \fIfilename\fP.
If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP.
Returns 0 on success, or \fBerrno\fP on a read or write error.
.Fn2 int history_truncate_file "const char *filename" "int nlines"
Truncate the history file \fIfilename\fP, leaving only the last
\fInlines\fP lines.
If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated.
Returns 0 on success, or \fBerrno\fP on failure.
.SS History Expansion
These functions implement history expansion.
.Fn2 int history_expand "char *string" "char **output"
Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer
to a string. Returns:
.RS
.PD 0
.TP
0
If no expansions took place (or, if the only change in
the text was the removal of escape characters preceding the history expansion
character);
.TP
1
if expansions did take place;
.TP
-1
if there was an error in expansion;
.TP
2
if the returned line should be displayed, but not executed,
as with the \fB:p\fP modifier.
.PD
.RE
If an error ocurred in expansion, then \fIoutput\fP contains a descriptive
error message.
.Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar"
Returns the text of the history event beginning at \fIstring\fP +
\fI*cindex\fP. \fI*cindex\fP is modified to point to after the event
specifier. At function entry, \fIcindex\fP points to the index into
\fIstring\fP where the history event specification begins. \fIqchar\fP
is a character that is allowed to end the event specification in addition
to the ``normal'' terminating characters.
.Fn1 "char **" history_tokenize "const char *string"
Return an array of tokens parsed out of \fIstring\fP, much as the
shell might.
The tokens are split on the characters in the
\fBhistory_word_delimiters\fP variable,
and shell quoting conventions are obeyed.
.Fn3 "char *" history_arg_extract "int first" "int last" "const char *string"
Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP
arguments present in \fIstring\fP. Arguments are split using
\fBhistory_tokenize()\fP.
.SS History Variables
This section describes the externally-visible variables exported by
the GNU History Library.
.Vb int history_base
The logical offset of the first entry in the history list.
.Vb int history_length
The number of entries currently stored in the history list.
.Vb int history_max_entries
The maximum number of history entries. This must be changed using
\fBstifle_history()\fP.
.Vb int history_wite_timestamps
If non-zero, timestamps are written to the history file, so they can be
preserved between sessions. The default value is 0, meaning that
timestamps are not saved.
The current timestamp format uses the value of \fIhistory_comment_char\fP
to delimit timestamp entries in the history file. If that variable does
not have a value (the default), timestamps will not be written.
.Vb char history_expansion_char
The character that introduces a history event. The default is \fB!\fP.
Setting this to 0 inhibits history expansion.
.Vb char history_subst_char
The character that invokes word substitution if found at the start of
a line. The default is \fB^\fP.
.Vb char history_comment_char
During tokenization, if this character is seen as the first character
of a word, then it and all subsequent characters up to a newline are
ignored, suppressing history expansion for the remainder of the line.
This is disabled by default.
.Vb "char *" history_word_delimiters
The characters that separate tokens for \fBhistory_tokenize()\fP.
The default value is \fB"\ \et\en()<>;&|"\fP.
.Vb "char *" history_no_expand_chars
The list of characters which inhibit history expansion if found immediately
following \fBhistory_expansion_char\fP. The default is space, tab, newline,
\fB\er\fP, and \fB=\fP.
.Vb "char *" history_search_delimiter_chars
The list of additional characters which can delimit a history search
string, in addition to space, tab, \fI:\fP and \fI?\fP in the case of
a substring search. The default is empty.
.Vb int history_quotes_inhibit_expansion
If non-zero, single-quoted words are not scanned for the history expansion
character. The default value is 0.
.Vb "rl_linebuf_func_t *" history_inhibit_expansion_function
This should be set to the address of a function that takes two arguments:
a \fBchar *\fP (\fIstring\fP)
and an \fBint\fP index into that string (\fIi\fP).
It should return a non-zero value if the history expansion starting at
\fIstring[i]\fP should not be performed; zero if the expansion should
be done.
It is intended for use by applications like \fBbash\fP that use the history
expansion character for additional purposes.
By default, this variable is set to \fBNULL\fP.
.SH FILES
.PD 0
.TP
.FN ~/.history
Default filename for reading and writing saved history
.PD
.SH "SEE ALSO"
.PD 0
.TP
\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
.TP
\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
.TP
\fIbash\fP(1)
.TP
\fIreadline\fP(3)
.PD
.SH AUTHORS
Brian Fox, Free Software Foundation
.br
bfox@gnu.org
.PP
Chet Ramey, Case Western Reserve University
.br
chet.ramey@case.edu
.SH BUG REPORTS
If you find a bug in the
.B history
library, you should report it. But first, you should
make sure that it really is a bug, and that it appears in the latest
version of the
.B history
library that you have.
.PP
Once you have determined that a bug actually exists, mail a
bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
If you have a fix, you are welcome to mail that
as well! Suggestions and `philosophical' bug reports may be mailed
to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
newsgroup
.BR gnu.bash.bug .
.PP
Comments and bug reports concerning
this manual page should be directed to
.IR chet.ramey@case.edu .
readline-6.3/doc/texi2dvi 0000775 0000436 0000000 00000055657 11050552143 014212 0 ustar chet wheel #! /bin/sh
# texi2dvi --- produce DVI (or PDF) files from Texinfo (or LaTeX) sources.
# $Id: texi2dvi,v 1.14 2003/02/05 00:42:33 karl Exp $
#
# Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001,
# 2002, 2003 Free Software Foundation, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
#
# Original author: Noah Friedman .
#
# Please send bug reports, etc. to bug-texinfo@gnu.org.
# If possible, please send a copy of the output of the script called with
# the `--debug' option when making a bug report.
# This string is expanded by rcs automatically when this file is checked out.
rcs_revision='$Revision: 1.14 $'
rcs_version=`set - $rcs_revision; echo $2`
program=`echo $0 | sed -e 's!.*/!!'`
version="texi2dvi (GNU Texinfo 4.5) $rcs_version
Copyright (C) 2003 Free Software Foundation, Inc.
There is NO warranty. You may redistribute this software
under the terms of the GNU General Public License.
For more information about these matters, see the files named COPYING."
usage="Usage: $program [OPTION]... FILE...
Run each Texinfo or LaTeX FILE through TeX in turn until all
cross-references are resolved, building all indices. The directory
containing each FILE is searched for included files. The suffix of FILE
is used to determine its language (LaTeX or Texinfo).
Makeinfo is used to perform Texinfo macro expansion before running TeX
when needed.
Operation modes:
-b, --batch no interaction
-c, --clean remove all auxiliary files
-D, --debug turn on shell debugging (set -x)
-h, --help display this help and exit successfully
-o, --output=OFILE leave output in OFILE (implies --clean);
Only one input FILE may be specified in this case
-q, --quiet no output unless errors (implies --batch)
-s, --silent same as --quiet
-v, --version display version information and exit successfully
-V, --verbose report on what is done
TeX tuning:
-@ use @input instead of \input; for preloaded Texinfo
-e, -E, --expand force macro expansion using makeinfo
-I DIR search DIR for Texinfo files
-l, --language=LANG specify the LANG of FILE (LaTeX or Texinfo)
-p, --pdf use pdftex or pdflatex for processing
-t, --texinfo=CMD insert CMD after @setfilename in copy of input file
multiple values accumulate
The values of the BIBTEX, LATEX (or PDFLATEX), MAKEINDEX, MAKEINFO,
TEX (or PDFTEX), and TEXINDEX environment variables are used to run
those commands, if they are set.
Email bug reports to ,
general questions and discussion to .
Texinfo home page: http://www.gnu.org/software/texinfo/"
# Initialize variables for option overriding and otherwise.
# Don't use `unset' since old bourne shells don't have this command.
# Instead, assign them an empty value.
batch=false # eval for batch mode
clean=
debug=
escape='\'
expand= # t for expansion via makeinfo
miincludes= # makeinfo include path
oformat=dvi
oname= # --output
quiet= # by default let the tools' message be displayed
set_language=
textra=
tmpdir=${TMPDIR:-/tmp}/t2d$$ # avoid collisions on 8.3 filesystems.
txincludes= # TEXINPUTS extensions, with trailing colon
txiprereq=19990129 # minimum texinfo.tex version to have macro expansion
verbose=false # echo for verbose mode
orig_pwd=`pwd`
# Systems which define $COMSPEC or $ComSpec use semicolons to separate
# directories in TEXINPUTS.
if test -n "$COMSPEC$ComSpec"; then
path_sep=";"
else
path_sep=":"
fi
# Pacify verbose cds.
CDPATH=${ZSH_VERSION+.}$path_sep
# In case someone crazy insists on using grep -E.
: ${EGREP=egrep}
# Save this so we can construct a new TEXINPUTS path for each file.
TEXINPUTS_orig="$TEXINPUTS"
# Unfortunately makeindex does not read TEXINPUTS.
INDEXSTYLE_orig="$INDEXSTYLE"
export TEXINPUTS INDEXSTYLE
# Push a token among the arguments that will be used to notice when we
# ended options/arguments parsing.
# Use "set dummy ...; shift" rather than 'set - ..." because on
# Solaris set - turns off set -x (but keeps set -e).
# Use ${1+"$@"} rather than "$@" because Digital Unix and Ultrix 4.3
# still expand "$@" to a single argument (the empty string) rather
# than nothing at all.
arg_sep="$$--$$"
set dummy ${1+"$@"} "$arg_sep"; shift
#
# Parse command line arguments.
while test x"$1" != x"$arg_sep"; do
# Handle --option=value by splitting apart and putting back on argv.
case "$1" in
--*=*)
opt=`echo "$1" | sed -e 's/=.*//'`
val=`echo "$1" | sed -e 's/[^=]*=//'`
shift
set dummy "$opt" "$val" ${1+"$@"}; shift
;;
esac
# This recognizes --quark as --quiet. So what.
case "$1" in
-@ ) escape=@;;
# Silently and without documentation accept -b and --b[atch] as synonyms.
-b | --b*) batch=eval;;
-q | -s | --q* | --s*) quiet=t; batch=eval;;
-c | --c*) clean=t;;
-D | --d*) debug=t;;
-e | -E | --e*) expand=t;;
-h | --h*) echo "$usage"; exit 0;;
-I | --I*)
shift
miincludes="$miincludes -I $1"
txincludes="$txincludes$1$path_sep"
;;
-l | --l*) shift; set_language=$1;;
-o | --o*)
shift
clean=t
case "$1" in
/* | ?:/*) oname=$1;;
*) oname="$orig_pwd/$1";;
esac;;
-p | --p*) oformat=pdf;;
-t | --t*) shift; textra="$textra\\
$1";;
-v | --vers*) echo "$version"; exit 0;;
-V | --verb*) verbose=echo;;
--) # What remains are not options.
shift
while test x"$1" != x"$arg_sep"; do
set dummy ${1+"$@"} "$1"; shift
shift
done
break;;
-*)
echo "$0: Unknown or ambiguous option \`$1'." >&2
echo "$0: Try \`--help' for more information." >&2
exit 1;;
*) set dummy ${1+"$@"} "$1"; shift;;
esac
shift
done
# Pop the token
shift
# Interpret remaining command line args as filenames.
case $# in
0)
echo "$0: Missing file arguments." >&2
echo "$0: Try \`--help' for more information." >&2
exit 2
;;
1) ;;
*)
if test -n "$oname"; then
echo "$0: Can't use option \`--output' with more than one argument." >&2
exit 2
fi
;;
esac
# Prepare the temporary directory. Remove it at exit, unless debugging.
if test -z "$debug"; then
trap "cd / && rm -rf $tmpdir" 0 1 2 15
fi
# Create the temporary directory with strict rights
(umask 077 && mkdir $tmpdir) || exit 1
# Prepare the tools we might need. This may be extra work in some
# cases, but improves the readibility of the script.
utildir=$tmpdir/utils
mkdir $utildir || exit 1
# A sed script that preprocesses Texinfo sources in order to keep the
# iftex sections only. We want to remove non TeX sections, and
# comment (with `@c texi2dvi') TeX sections so that makeinfo does not
# try to parse them. Nevertheless, while commenting TeX sections,
# don't comment @macro/@end macro so that makeinfo does propagate
# them. Unfortunately makeinfo --iftex --no-ifhtml --no-ifinfo
# doesn't work well enough (yet) to use that, so work around with sed.
comment_iftex_sed=$utildir/comment.sed
cat <$comment_iftex_sed
/^@tex/,/^@end tex/{
s/^/@c texi2dvi/
}
/^@iftex/,/^@end iftex/{
s/^/@c texi2dvi/
/^@c texi2dvi@macro/,/^@c texi2dvi@end macro/{
s/^@c texi2dvi//
}
}
/^@html/,/^@end html/{
s/^/@c (texi2dvi)/
}
/^@ifhtml/,/^@end ifhtml/{
s/^/@c (texi2dvi)/
}
/^@ifnottex/,/^@end ifnottex/{
s/^/@c (texi2dvi)/
}
/^@ifinfo/,/^@end ifinfo/{
/^@node/p
/^@menu/,/^@end menu/p
t
s/^/@c (texi2dvi)/
}
s/^@ifnotinfo/@c texi2dvi@ifnotinfo/
s/^@end ifnotinfo/@c texi2dvi@end ifnotinfo/
EOF
# Uncommenting is simple: Remove any leading `@c texi2dvi'.
uncomment_iftex_sed=$utildir/uncomment.sed
cat <$uncomment_iftex_sed
s/^@c texi2dvi//
EOF
# A shell script that computes the list of xref files.
# Takes the filename (without extension) of which we look for xref
# files as argument. The index files must be reported last.
get_xref_files=$utildir/get_xref.sh
cat <<\EOF >$get_xref_files
#! /bin/sh
# Get list of xref files (indexes, tables and lists).
# Find all files having root filename with a two-letter extension,
# saves the ones that are really Texinfo-related files. .?o? catches
# many files: .toc, .log, LaTeX tables and lists, FiXme's .lox, maybe more.
for this_file in "$1".?o? "$1".aux "$1".?? "$1".idx; do
# If file is empty, skip it.
test -s "$this_file" || continue
# If the file is not suitable to be an index or xref file, don't
# process it. The file can't be if its first character is not a
# backslash or single quote.
first_character=`sed -n '1s/^\(.\).*$/\1/p;q' $this_file`
if test "x$first_character" = "x\\" \
|| test "x$first_character" = "x'"; then
xref_files="$xref_files ./$this_file"
fi
done
echo "$xref_files"
EOF
chmod 500 $get_xref_files
# File descriptor usage:
# 0 standard input
# 1 standard output (--verbose messages)
# 2 standard error
# 3 some systems may open it to /dev/tty
# 4 used on the Kubota Titan
# 5 tools output (turned off by --quiet)
# Tools' output. If quiet, discard, else redirect to the message flow.
if test "$quiet" = t; then
exec 5>/dev/null
else
exec 5>&1
fi
# Enable tracing
test "$debug" = t && set -x
#
# TeXify files.
for command_line_filename in ${1+"$@"}; do
$verbose "Processing $command_line_filename ..."
# If the COMMAND_LINE_FILENAME is not absolute (e.g., --debug.tex),
# prepend `./' in order to avoid that the tools take it as an option.
echo "$command_line_filename" | $EGREP '^(/|[A-z]:/)' >/dev/null \
|| command_line_filename="./$command_line_filename"
# See if the file exists. If it doesn't we're in trouble since, even
# though the user may be able to reenter a valid filename at the tex
# prompt (assuming they're attending the terminal), this script won't
# be able to find the right xref files and so forth.
if test ! -r "$command_line_filename"; then
echo "$0: Could not read $command_line_filename, skipping." >&2
continue
fi
# Get the name of the current directory. We want the full path
# because in clean mode we are in tmp, in which case a relative
# path has no meaning.
filename_dir=`echo $command_line_filename | sed 's!/[^/]*$!!;s!^$!.!'`
filename_dir=`cd "$filename_dir" >/dev/null && pwd`
# Strip directory part but leave extension.
filename_ext=`basename "$command_line_filename"`
# Strip extension.
filename_noext=`echo "$filename_ext" | sed 's/\.[^.]*$//'`
ext=`echo "$filename_ext" | sed 's/^.*\.//'`
# _src. Use same basename since we want to generate aux files with
# the same basename as the manual. If --expand, then output the
# macro-expanded file to here, else copy the original file.
tmpdir_src=$tmpdir/src
filename_src=$tmpdir_src/$filename_noext.$ext
# _xtr. The file with the user's extra commands.
tmpdir_xtr=$tmpdir/xtr
filename_xtr=$tmpdir_xtr/$filename_noext.$ext
# _bak. Copies of the previous xref files (another round is run if
# they differ from the new one).
tmpdir_bak=$tmpdir/bak
# Make all those directories and give up if we can't succeed.
mkdir $tmpdir_src $tmpdir_xtr $tmpdir_bak || exit 1
# Source file might include additional sources.
# We want `.:$orig_pwd' before anything else. (We'll add `.:' later
# after all other directories have been turned into absolute paths.)
# `.' goes first to ensure that any old .aux, .cps,
# etc. files in ${directory} don't get used in preference to fresher
# files in `.'. Include orig_pwd in case we are in clean mode, where
# we've cd'd to a temp directory.
common="$orig_pwd$path_sep$filename_dir$path_sep$txincludes"
TEXINPUTS="$common$TEXINPUTS_orig"
INDEXSTYLE="$common$INDEXSTYLE_orig"
# Convert relative paths to absolute paths, so we can run in another
# directory (e.g., in --clean mode, or during the macro-support
# detection.)
#
# Empty path components are meaningful to tex. We rewrite them
# as `EMPTY' so they don't get lost when we split on $path_sep.
TEXINPUTS=`echo $TEXINPUTS |sed 's/^:/EMPTY:/;s/:$/:EMPTY/;s/::/:EMPTY:/g'`
INDEXSTYLE=`echo $INDEXSTYLE |sed 's/^:/EMPTY:/;s/:$/:EMPTY/;s/::/:EMPTY:/g'`
save_IFS=$IFS
IFS=$path_sep
set x $TEXINPUTS; shift
TEXINPUTS=.
for dir
do
case $dir in
EMPTY)
TEXINPUTS=$TEXINPUTS$path_sep
;;
[\\/]* | ?:[\\/]*) # Absolute paths don't need to be expansed.
TEXINPUTS=$TEXINPUTS$path_sep$dir
;;
*)
abs=`cd "$dir" && pwd` && TEXINPUTS=$TEXINPUTS$path_sep$abs
;;
esac
done
set x $INDEXSTYLE; shift
INDEXSTYLE=.
for dir
do
case $dir in
EMPTY)
INDEXSTYLE=$INDEXSTYLE$path_sep
;;
[\\/]* | ?:[\\/]*) # Absolute paths don't need to be expansed.
INDEXSTYLE=$INDEXSTYLE$path_sep$dir
;;
*)
abs=`cd "$dir" && pwd` && INDEXSTYLE=$INDEXSTYLE$path_sep$abs
;;
esac
done
IFS=$save_IFS
# If the user explicitly specified the language, use that.
# Otherwise, if the first line is \input texinfo, assume it's texinfo.
# Otherwise, guess from the file extension.
if test -n "$set_language"; then
language=$set_language
elif sed 1q "$command_line_filename" | grep 'input texinfo' >/dev/null; then
language=texinfo
else
language=
fi
# Get the type of the file (latex or texinfo) from the given language
# we just guessed, or from the file extension if not set yet.
case ${language:-$filename_ext} in
[lL]a[tT]e[xX] | *.ltx | *.tex)
# Assume a LaTeX file. LaTeX needs bibtex and uses latex for
# compilation. No makeinfo.
bibtex=${BIBTEX:-bibtex}
makeinfo= # no point in running makeinfo on latex source.
texindex=${MAKEINDEX:-makeindex}
if test $oformat = dvi; then
tex=${LATEX:-latex}
else
tex=${PDFLATEX:-pdflatex}
fi
;;
*)
# Assume a Texinfo file. Texinfo files need makeinfo, texindex and tex.
bibtex=
texindex=${TEXINDEX:-texindex}
if test $oformat = dvi; then
tex=${TEX:-tex}
else
tex=${PDFTEX:-pdftex}
fi
# Unless required by the user, makeinfo expansion is wanted only
# if texinfo.tex is too old.
if test "$expand" = t; then
makeinfo=${MAKEINFO:-makeinfo}
else
# Check if texinfo.tex performs macro expansion by looking for
# its version. The version is a date of the form YEAR-MO-DA.
# We don't need to use [0-9] to match the digits since anyway
# the comparison with $txiprereq, a number, will fail with non
# digits.
txiversion_tex=txiversion.tex
echo '\input texinfo.tex @bye' >$tmpdir/$txiversion_tex
# Run in the tmpdir to avoid leaving files.
eval `cd $tmpdir >/dev/null &&
$tex $txiversion_tex 2>/dev/null |
sed -n 's/^.*\[\(.*\)version \(....\)-\(..\)-\(..\).*$/txiformat=\1 txiversion="\2\3\4"/p'`
$verbose "texinfo.tex preloaded as \`$txiformat', version is \`$txiversion' ..."
if test "$txiprereq" -le "$txiversion" >/dev/null 2>&1; then
makeinfo=
else
makeinfo=${MAKEINFO:-makeinfo}
fi
# As long as we had to run TeX, offer the user this convenience
if test "$txiformat" = Texinfo; then
escape=@
fi
fi
;;
esac
# Expand macro commands in the original source file using Makeinfo.
# Always use `end' footnote style, since the `separate' style
# generates different output (arguably this is a bug in -E).
# Discard main info output, the user asked to run TeX, not makeinfo.
if test -n "$makeinfo"; then
$verbose "Macro-expanding $command_line_filename to $filename_src ..."
sed -f $comment_iftex_sed "$command_line_filename" \
| $makeinfo --footnote-style=end -I "$filename_dir" $miincludes \
-o /dev/null --macro-expand=- \
| sed -f $uncomment_iftex_sed >"$filename_src"
filename_input=$filename_src
fi
# If makeinfo failed (or was not even run), use the original file as input.
if test $? -ne 0 \
|| test ! -r "$filename_src"; then
$verbose "Reverting to $command_line_filename ..."
filename_input=$filename_dir/$filename_ext
fi
# Used most commonly for @finalout, @smallbook, etc.
if test -n "$textra"; then
$verbose "Inserting extra commands: $textra"
sed '/^@setfilename/a\
'"$textra" "$filename_input" >$filename_xtr
filename_input=$filename_xtr
fi
# If clean mode was specified, then move to the temporary directory.
if test "$clean" = t; then
$verbose "cd $tmpdir_src"
cd "$tmpdir_src" || exit 1
fi
while :; do # will break out of loop below
orig_xref_files=`$get_xref_files "$filename_noext"`
# Save copies of originals for later comparison.
if test -n "$orig_xref_files"; then
$verbose "Backing up xref files: `echo $orig_xref_files | sed 's|\./||g'`"
cp $orig_xref_files $tmpdir_bak
fi
# Run bibtex on current file.
# - If its input (AUX) exists.
# - If AUX contains both `\bibdata' and `\bibstyle'.
# - If some citations are missing (LOG contains `Citation').
# or the LOG complains of a missing .bbl
#
# We run bibtex first, because I can see reasons for the indexes
# to change after bibtex is run, but I see no reason for the
# converse.
#
# Don't try to be too smart. Running bibtex only if the bbl file
# exists and is older than the LaTeX file is wrong, since the
# document might include files that have changed. Because there
# can be several AUX (if there are \include's), but a single LOG,
# looking for missing citations in LOG is easier, though we take
# the risk to match false messages.
if test -n "$bibtex" \
&& test -r "$filename_noext.aux" \
&& test -r "$filename_noext.log" \
&& (grep '^\\bibdata[{]' "$filename_noext.aux" \
&& grep '^\\bibstyle[{]' "$filename_noext.aux" \
&& (grep 'Warning:.*Citation.*undefined' "$filename_noext.log" \
|| grep 'No file .*\.bbl\.' "$filename_noext.log")) \
>/dev/null 2>&1; \
then
$verbose "Running $bibtex $filename_noext ..."
if $bibtex "$filename_noext" >&5; then :; else
echo "$0: $bibtex exited with bad status, quitting." >&2
exit 1
fi
fi
# What we'll run texindex on -- exclude non-index files.
# Since we know index files are last, it is correct to remove everything
# before .aux and .?o?. But don't really do o
# -- don't match whitespace as .
# Otherwise, if orig_xref_files contains something like
# foo.xo foo.whatever
# the space after the o will get matched.
index_files=`echo "$orig_xref_files" \
| sed "s!.*\.aux!!g;
s!./$filename_noext\.[^ ]o[^ ]!!g;
s/^[ ]*//;s/[ ]*$//"`
# Run texindex (or makeindex) on current index files. If they
# already exist, and after running TeX a first time the index
# files don't change, then there's no reason to run TeX again.
# But we won't know that if the index files are out of date or
# nonexistent.
if test -n "$texindex" && test -n "$index_files"; then
$verbose "Running $texindex $index_files ..."
if $texindex $index_files 2>&5 1>&2; then :; else
echo "$0: $texindex exited with bad status, quitting." >&2
exit 1
fi
fi
# Finally, run TeX.
# Prevent $ESCAPE from being interpreted by the shell if it happens
# to be `/'.
$batch tex_args="\\${escape}nonstopmode\ \\${escape}input"
cmd="$tex $tex_args $filename_input"
$verbose "Running $cmd ..."
if $cmd >&5; then :; else
echo "$0: $tex exited with bad status, quitting." >&2
echo "$0: see $filename_noext.log for errors." >&2
test "$clean" = t \
&& cp "$filename_noext.log" "$orig_pwd"
exit 1
fi
# Decide if looping again is needed.
finished=t
# LaTeX (and the package changebar) report in the LOG file if it
# should be rerun. This is needed for files included from
# subdirs, since texi2dvi does not try to compare xref files in
# subdirs. Performing xref files test is still good since LaTeX
# does not report changes in xref files.
if grep "Rerun to get" "$filename_noext.log" >/dev/null 2>&1; then
finished=
fi
# Check if xref files changed.
new_xref_files=`$get_xref_files "$filename_noext"`
$verbose "Original xref files = `echo $orig_xref_files | sed 's|\./||g'`"
$verbose "New xref files = `echo $new_xref_files | sed 's|\./||g'`"
# If old and new lists don't at least have the same file list,
# then one file or another has definitely changed.
test "x$orig_xref_files" != "x$new_xref_files" && finished=
# File list is the same. We must compare each file until we find
# a difference.
if test -n "$finished"; then
for this_file in $new_xref_files; do
$verbose "Comparing xref file `echo $this_file | sed 's|\./||g'` ..."
# cmp -s returns nonzero exit status if files differ.
if cmp -s "$this_file" "$tmpdir_bak/$this_file"; then :; else
# We only need to keep comparing until we find one that
# differs, because we'll have to run texindex & tex again no
# matter how many more there might be.
finished=
$verbose "xref file `echo $this_file | sed 's|\./||g'` differed ..."
test "$debug" = t && diff -c "$tmpdir_bak/$this_file" "$this_file"
break
fi
done
fi
# If finished, exit the loop, else rerun the loop.
test -n "$finished" && break
done
# If we were in clean mode, compilation was in a tmp directory.
# Copy the DVI (or PDF) file into the directory where the compilation
# has been done. (The temp dir is about to get removed anyway.)
# We also return to the original directory so that
# - the next file is processed in correct conditions
# - the temporary file can be removed
if test -n "$clean"; then
if test -n "$oname"; then
dest=$oname
else
dest=$orig_pwd
fi
$verbose "Copying $oformat file from `pwd` to $dest"
cp -p "./$filename_noext.$oformat" "$dest"
cd / # in case $orig_pwd is on a different drive (for DOS)
cd $orig_pwd || exit 1
fi
# Remove temporary files.
if test "x$debug" = "x"; then
$verbose "Removing $tmpdir_src $tmpdir_xtr $tmpdir_bak ..."
cd /
rm -rf $tmpdir_src $tmpdir_xtr $tmpdir_bak
fi
done
$verbose "$0 done."
exit 0 # exit successfully, not however we ended the loop.
readline-6.3/doc/texi2html 0000755 0000436 0000000 00000424554 11050552171 014367 0 ustar chet wheel #! /usr/bin/perl
'di ';
'ig 00 ';
#+##############################################################################
#
# texi2html: Program to transform Texinfo documents to HTML
#
# Copyright (C) 1999, 2000 Free Software Foundation, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
#
#-##############################################################################
# This requires perl version 5 or higher
require 5.0;
#++##############################################################################
#
# NOTE FOR DEBUGGING THIS SCRIPT:
# You can run 'perl texi2html.pl' directly, provided you have
# the environment variable T2H_HOME set to the directory containing
# the texi2html.init file
#
#--##############################################################################
# CVS version:
# $Id: texi2html.pl,v 1.55 2000/07/27 14:39:41 obachman Exp $
# Homepage:
$T2H_HOMEPAGE = < (original author)
Karl Berry
Olaf Bachmann
and many others.
Maintained by: Olaf Bachmann
Send bugs and suggestions to
EOT
# Version: set in configure.in
$THISVERSION = '1.64';
$THISPROG = "texi2html $THISVERSION"; # program name and version
# The man page for this program is included at the end of this file and can be
# viewed using the command 'nroff -man texi2html'.
# Identity:
$T2H_TODAY = &pretty_date; # like "20 September 1993"
# the eval prevents this from breaking on system which do not have
# a proper getpwuid implemented
eval { ($T2H_USER = (getpwuid ($<))[6]) =~ s/,.*//;}; # Who am i
#+++############################################################################
# #
# Initialization #
# Pasted content of File $(srcdir)/texi2html.init: Default initializations #
# #
#---############################################################################
# leave this within comments, and keep the require statement
# This way, you can directly run texi2html.pl, if $ENV{T2H_HOME}/texi2html.init
# exists.
#
# -*-perl-*-
######################################################################
# File: texi2html.init
#
# Sets default values for command-line arguments and for various customizable
# procedures
#
# A copy of this file is pasted into the beginning of texi2html by
# 'make texi2html'
#
# Copy this file and make changes to it, if you like.
# Afterwards, either, load it with command-line option -init_file
#
# $Id: texi2html.init,v 1.34 2000/07/27 14:09:02 obachman Exp $
######################################################################
# stuff which can also be set by command-line options
#
#
# Note: values set here, overwrite values set by the command-line
# options before -init_file and might still be overwritten by
# command-line arguments following the -init_file option
#
# T2H_OPTIONS is a hash whose keys are the (long) names of valid
# command-line options and whose values are a hash with the following keys:
# type ==> one of !|=i|:i|=s|:s (see GetOpt::Long for more info)
# linkage ==> ref to scalar, array, or subroutine (see GetOpt::Long for more info)
# verbose ==> short description of option (displayed by -h)
# noHelp ==> if 1 -> for "not so important options": only print description on -h 1
# 2 -> for obsolete options: only print description on -h 2
$T2H_DEBUG = 0;
$T2H_OPTIONS -> {debug} =
{
type => '=i',
linkage => \$main::T2H_DEBUG,
verbose => 'output HTML with debuging information',
};
$T2H_DOCTYPE = '';
$T2H_OPTIONS -> {doctype} =
{
type => '=s',
linkage => \$main::T2H_DOCTYPE,
verbose => 'document type which is output in header of HTML files',
noHelp => 1
};
$T2H_CHECK = 0;
$T2H_OPTIONS -> {check} =
{
type => '!',
linkage => \$main::T2H_CHECK,
verbose => 'if set, only check files and output all things that may be Texinfo commands',
noHelp => 1
};
# -expand
# if set to "tex" (or, "info") expand @iftex and @tex (or, @ifinfo) sections
# else, neither expand @iftex, @tex, nor @ifinfo sections
$T2H_EXPAND = "info";
$T2H_OPTIONS -> {expand} =
{
type => '=s',
linkage => \$T2H_EXPAND,
verbose => 'Expand info|tex|none section of texinfo source',
};
# - glossary
#if set, uses section named `Footnotes' for glossary
$T2H_USE_GLOSSARY = 0;
T2H_OPTIONS -> {glossary} =
{
type => '!',
linkage => \$T2H_USE_GLOSSARY,
verbose => "if set, uses section named `Footnotes' for glossary",
noHelp => 1,
};
# -invisible
# $T2H_INVISIBLE_MARK is the text used to create invisible destination
# anchors for index links (you can for instance use the invisible.xbm
# file shipped with this program). This is a workaround for a known
# bug of many WWW browsers, including netscape.
# For me, it works fine without it -- on the contrary: if there, it
# inserts space between headers and start of text (obachman 3/99)
$T2H_INVISIBLE_MARK = '';
# $T2H_INVISIBLE_MARK = ' ';
$T2H_OPTIONS -> {invisible} =
{
type => '=s',
linkage => \$T2H_INVISIBLE_MARK,
verbose => 'use text in invisble anchot',
noHelp => 1,
};
# -iso
# if set, ISO8879 characters are used for special symbols (like copyright, etc)
$T2H_USE_ISO = 0;
$T2H_OPTIONS -> {iso} =
{
type => 'iso',
linkage => \$T2H_USE_ISO,
verbose => 'if set, ISO8879 characters are used for special symbols (like copyright, etc)',
noHelp => 1,
};
# -I
# list directories where @include files are searched for (besides the
# directory of the doc file) additional '-I' args add to this list
@T2H_INCLUDE_DIRS = (".");
$T2H_OPTIONS -> {I} =
{
type => '=s',
linkage => \@T2H_INCLUDE_DIRS,
verbose => 'append $s to the @include search path',
};
# -top_file
# uses file of this name for top-level file
# extension is manipulated appropriately, if necessary.
# If empty, .html is used
# Typically, you would set this to "index.html".
$T2H_TOP_FILE = '';
$T2H_OPTIONS -> {top_file} =
{
type => '=s',
linkage => \$T2H_TOP_FILE,
verbose => 'use $s as top file, instead of .html',
};
# -toc_file
# uses file of this name for table of contents file
# extension is manipulated appropriately, if necessary.
# If empty, _toc.html is used
$T2H_TOC_FILE = '';
$T2H_OPTIONS -> {toc_file} =
{
type => '=s',
linkage => \$T2H_TOC_FILE,
verbose => 'use $s as ToC file, instead of _toc.html',
};
# -frames
# if set, output two additional files which use HTML 4.0 "frames".
$T2H_FRAMES = 0;
$T2H_OPTIONS -> {frames} =
{
type => '!',
linkage => \$T2H_FRAMES,
verbose => 'output files which use HTML 4.0 frames (experimental)',
noHelp => 1,
};
# -menu | -nomenu
# if set, show the Texinfo menus
$T2H_SHOW_MENU = 1;
$T2H_OPTIONS -> {menu} =
{
type => '!',
linkage => \$T2H_SHOW_MENU,
verbose => 'ouput Texinfo menus',
};
# -number | -nonumber
# if set, number sections and show section names and numbers in references
# and menus
$T2H_NUMBER_SECTIONS = 1;
$T2H_OPTIONS -> {number} =
{
type => '!',
linkage => \$T2H_NUMBER_SECTIONS,
verbose => 'use numbered sections'
};
# if set, and T2H_NUMBER_SECTIONS is set, then use node names in menu
# entries, instead of section names
$T2H_NODE_NAME_IN_MENU = 0;
# if set and menu entry equals menu descr, then do not print menu descr.
# Likewise, if node name equals entry name, do not print entry name.
$T2H_AVOID_MENU_REDUNDANCY = 1;
# -split section|chapter|none
# if set to 'section' (resp. 'chapter') create one html file per (sub)section
# (resp. chapter) and separate pages for Top, ToC, Overview, Index,
# Glossary, About.
# otherwise, create monolithic html file which contains whole document
#$T2H_SPLIT = 'section';
$T2H_SPLIT = '';
$T2H_OPTIONS -> {split} =
{
type => '=s',
linkage => \$T2H_SPLIT,
verbose => 'split document on section|chapter else no splitting',
};
# -section_navigation|-no-section_navigation
# if set, then navigation panels are printed at the beginning of each section
# and, possibly at the end (depending on whether or not there were more than
# $T2H_WORDS_IN_PAGE words on page
# This is most useful if you do not want to have section navigation
# on -split chapter
$T2H_SECTION_NAVIGATION = 1;
$T2H_OPTIONS -> {sec_nav} =
{
type => '!',
linkage => \$T2H_SECTION_NAVIGATION,
verbose => 'output navigation panels for each section',
};
# -subdir
# if set put result files in this directory
# if not set result files are put into current directory
#$T2H_SUBDIR = 'html';
$T2H_SUBDIR = '';
$T2H_OPTIONS -> {subdir} =
{
type => '=s',
linkage => \$T2H_SUBDIR,
verbose => 'put HTML files in directory $s, instead of $cwd',
};
# -short_extn
# If this is set all HTML file will have extension ".htm" instead of
# ".html". This is helpful when shipping the document to PC systems.
$T2H_SHORTEXTN = 0;
$T2H_OPTIONS -> {short_ext} =
{
type => '!',
linkage => \$T2H_SHORTEXTN,
verbose => 'use "htm" extension for output HTML files',
};
# -prefix
# Set the output file prefix, prepended to all .html, .gif and .pl files.
# By default, this is the basename of the document
$T2H_PREFIX = '';
$T2H_OPTIONS -> {prefix} =
{
type => '=s',
linkage => \$T2H_PREFIX,
verbose => 'use as prefix for output files, instead of ',
};
# -o filename
# If set, generate monolithic document output html into $filename
$T2H_OUT = '';
$T2H_OPTIONS -> {out_file} =
{
type => '=s',
linkage => sub {$main::T2H_OUT = @_[1]; $T2H_SPLIT = '';},
verbose => 'if set, all HTML output goes into file $s',
};
# -short_ref
#if set cross-references are given without section numbers
$T2H_SHORT_REF = '';
$T2H_OPTIONS -> {short_ref} =
{
type => '!',
linkage => \$T2H_SHORT_REF,
verbose => 'if set, references are without section numbers',
};
# -idx_sum
# if value is set, then for each @prinindex $what
# $docu_name_$what.idx is created which contains lines of the form
# $key\t$ref sorted alphabetically (case matters)
$T2H_IDX_SUMMARY = 0;
$T2H_OPTIONS -> {idx_sum} =
{
type => '!',
linkage => \$T2H_IDX_SUMMARY,
verbose => 'if set, also output index summary',
noHelp => 1,
};
# -verbose
# if set, chatter about what we are doing
$T2H_VERBOSE = '';
$T2H_OPTIONS -> {Verbose} =
{
type => '!',
linkage => \$T2H_VERBOSE,
verbose => 'print progress info to stdout',
};
# -lang
# For page titles use $T2H_WORDS->{$T2H_LANG}->{...} as title.
# To add a new language, supply list of titles (see $T2H_WORDS below).
# and use ISO 639 language codes (see e.g. perl module Locale-Codes-1.02
# for definitions)
# Default's to 'en' if not set or no @documentlanguage is specified
$T2H_LANG = '';
$T2H_OPTIONS -> {lang} =
{
type => '=s',
linkage => sub {SetDocumentLanguage($_[1])},
verbose => 'use $s as document language (ISO 639 encoding)',
};
# -l2h
# if set, uses latex2html for generation of math content
$T2H_L2H = '';
$T2H_OPTIONS -> {l2h} =
{
type => '!',
linkage => \$T2H_L2H,
verbose => 'if set, uses latex2html for @math and @tex',
};
######################
# The following options are only relevant if $T2H_L2H is set
#
# -l2h_l2h
# name/location of latex2html progam
$T2H_L2H_L2H = "latex2html";
$T2H_OPTIONS -> {l2h_l2h} =
{
type => '=s',
linkage => \$T2H_L2H_L2H,
verbose => 'program to use for latex2html translation',
noHelp => 1,
};
# -l2h_skip
# if set, skips actual call to latex2html tries to reuse previously generated
# content, instead
$T2H_L2H_SKIP = '';
$T2H_OPTIONS -> {l2h_skip} =
{
type => '!',
linkage => \$T2H_L2H_SKIP,
verbose => 'if set, tries to reuse previously latex2html output',
noHelp => 1,
};
# -l2h_tmp
# if set, l2h uses this directory for temporarary files. The path
# leading to this directory may not contain a dot (i.e., a "."),
# otherwise, l2h will fail
$T2H_L2H_TMP = '';
$T2H_OPTIONS -> {l2h_tmp} =
{
type => '=s',
linkage => \$T2H_L2H_TMP,
verbose => 'if set, uses $s as temporary latex2html directory',
noHelp => 1,
};
# if set, cleans intermediate files (they all have the prefix $doc_l2h_)
# of l2h
$T2H_L2H_CLEAN = 1;
$T2H_OPTIONS -> {l2h_clean} =
{
type => '!',
linkage => \$T2H_L2H_CLEAN,
verbose => 'if set, do not keep intermediate latex2html files for later reuse',
noHelp => 1,
};
$T2H_OPTIONS -> {D} =
{
type => '=s',
linkage => sub {$main::value{@_[1]} = 1;},
verbose => 'equivalent to Texinfo "@set $s 1"',
noHelp => 1,
};
$T2H_OPTIONS -> {init_file} =
{
type => '=s',
linkage => \&LoadInitFile,
verbose => 'load init file $s'
};
##############################################################################
#
# The following can only be set in the init file
#
##############################################################################
# if set, center @image by default
# otherwise, do not center by default
$T2H_CENTER_IMAGE = 1;
# used as identation for block enclosing command @example, etc
# If not empty, must be enclosed in |
$T2H_EXAMPLE_INDENT_CELL = ' | ';
# same as above, only for @small
$T2H_SMALL_EXAMPLE_INDENT_CELL = ' | ';
# font size for @small
$T2H_SMALL_FONT_SIZE = '-1';
# if non-empty, and no @..heading appeared in Top node, then
# use this as header for top node/section, otherwise use value of
# @settitle or @shorttitle (in that order)
$T2H_TOP_HEADING = '';
# if set, use this chapter for 'Index' button, else
# use first chapter whose name matches 'index' (case insensitive)
$T2H_INDEX_CHAPTER = '';
# if set and $T2H_SPLIT is set, then split index pages at the next letter
# after they have more than that many entries
$T2H_SPLIT_INDEX = 100;
# if set (e.g., to index.html) replace hrefs to this file
# (i.e., to index.html) by ./
$T2H_HREF_DIR_INSTEAD_FILE = '';
########################################################################
# Language dependencies:
# To add a new language extend T2H_WORDS hash and create $T2H_<...>_WORDS hash
# To redefine one word, simply do:
# $T2H_WORDS->{}->{} = 'whatever' in your personal init file.
#
$T2H_WORDS_EN =
{
# titles of pages
'ToC_Title' => 'Table of Contents',
'Overview_Title' => 'Short Table of Contents',
'Index_Title' => 'Index',
'About_Title' => 'About this document',
'Footnotes_Title' => 'Footnotes',
'See' => 'See',
'see' => 'see',
'section' => 'section',
# If necessary, we could extend this as follows:
# # text for buttons
# 'Top_Button' => 'Top',
# 'ToC_Button' => 'Contents',
# 'Overview_Button' => 'Overview',
# 'Index_button' => 'Index',
# 'Back_Button' => 'Back',
# 'FastBack_Button' => 'FastBack',
# 'Prev_Button' => 'Prev',
# 'Up_Button' => 'Up',
# 'Next_Button' => 'Next',
# 'Forward_Button' =>'Forward',
# 'FastWorward_Button' => 'FastForward',
# 'First_Button' => 'First',
# 'Last_Button' => 'Last',
# 'About_Button' => 'About'
};
$T2H_WORD_DE =
{
'ToC_Title' => 'Inhaltsverzeichniss',
'Overview_Title' => 'Kurzes Inhaltsverzeichniss',
'Index_Title' => 'Index',
'About_Title' => 'Über dieses Dokument',
'Footnotes_Title' => 'Fußnoten',
'See' => 'Siehe',
'see' => 'siehe',
'section' => 'Abschnitt',
};
$T2H_WORD_NL =
{
'ToC_Title' => 'Inhoudsopgave',
'Overview_Title' => 'Korte inhoudsopgave',
'Index_Title' => 'Index', #Not sure ;-)
'About_Title' => 'No translation available!', #No translation available!
'Footnotes_Title' => 'No translation available!', #No translation available!
'See' => 'Zie',
'see' => 'zie',
'section' => 'sectie',
};
$T2H_WORD_ES =
{
'ToC_Title' => 'índice General',
'Overview_Title' => 'Resumen del Contenido',
'Index_Title' => 'Index', #Not sure ;-)
'About_Title' => 'No translation available!', #No translation available!
'Footnotes_Title' => 'Fußnoten',
'See' => 'Véase',
'see' => 'véase',
'section' => 'sección',
};
$T2H_WORD_NO =
{
'ToC_Title' => 'Innholdsfortegnelse',
'Overview_Title' => 'Kort innholdsfortegnelse',
'Index_Title' => 'Indeks', #Not sure ;-)
'About_Title' => 'No translation available!', #No translation available!
'Footnotes_Title' => 'No translation available!',
'See' => 'Se',
'see' => 'se',
'section' => 'avsnitt',
};
$T2H_WORD_PT =
{
'ToC_Title' => 'Sumário',
'Overview_Title' => 'Breve Sumário',
'Index_Title' => 'Índice', #Not sure ;-)
'About_Title' => 'No translation available!', #No translation available!
'Footnotes_Title' => 'No translation available!',
'See' => 'Veja',
'see' => 'veja',
'section' => 'Seção',
};
$T2H_WORDS =
{
'en' => $T2H_WORDS_EN,
'de' => $T2H_WORDS_DE,
'nl' => $T2H_WORDS_NL,
'es' => $T2H_WORDS_ES,
'no' => $T2H_WORDS_NO,
'pt' => $T2H_WORDS_PT
};
@MONTH_NAMES_EN =
(
'January', 'February', 'March', 'April', 'May',
'June', 'July', 'August', 'September', 'October',
'November', 'December'
);
@MONTH_NAMES_DE =
(
'Januar', 'Februar', 'März', 'April', 'Mai',
'Juni', 'Juli', 'August', 'September', 'Oktober',
'November', 'Dezember'
);
@MONTH_NAMES_NL =
(
'Januari', 'Februari', 'Maart', 'April', 'Mei',
'Juni', 'Juli', 'Augustus', 'September', 'Oktober',
'November', 'December'
);
@MONTH_NAMES_ES =
(
'enero', 'febrero', 'marzo', 'abril', 'mayo',
'junio', 'julio', 'agosto', 'septiembre', 'octubre',
'noviembre', 'diciembre'
);
@MONTH_NAMES_NO =
(
'januar', 'februar', 'mars', 'april', 'mai',
'juni', 'juli', 'august', 'september', 'oktober',
'november', 'desember'
);
@MONTH_NAMES_PT =
(
'Janeiro', 'Fevereiro', 'Março', 'Abril', 'Maio',
'Junho', 'Julho', 'Agosto', 'Setembro', 'Outubro',
'Novembro', 'Dezembro'
);
$MONTH_NAMES =
{
'en' => \@MONTH_NAMES_EN,
'de' => \@MONTH_NAMES_DE,
'es' => \@MONTH_NAMES_ES,
'nl' => \@MONTH_NAMES_NL,
'no' => \@MONTH_NAMES_NO,
'pt' => \@MONTH_NAMES_PT
};
########################################################################
# Control of Page layout:
# You can make changes of the Page layout at two levels:
# 1.) For small changes, it is often enough to change the value of
# some global string/hash/array variables
# 2.) For larger changes, reimplement one of the T2H_DEFAULT_* routines,
# give them another name, and assign them to the respective
# $T2H_ variable.
# As a general interface, the hashes T2H_HREF, T2H_NAME, T2H_NODE hold
# href, html-name, node-name of
# This -- current section (resp. html page)
# Top -- top page ($T2H_TOP_FILE)
# Contents -- Table of contents
# Overview -- Short table of contents
# Index -- Index page
# About -- page which explain "navigation buttons"
# First -- first node
# Last -- last node
#
# Whether or not the following hash values are set, depends on the context
# (all values are w.r.t. 'This' section)
# Next -- next node of texinfo
# Prev -- previous node of texinfo
# Up -- up node of texinfo
# Forward -- next node in reading order
# Back -- previous node in reading order
# FastForward -- if leave node, up and next, else next node
# FastBackward-- if leave node, up and prev, else prev node
#
# Furthermore, the following global variabels are set:
# $T2H_THISDOC{title} -- title as set by @setttile
# $T2H_THISDOC{fulltitle} -- full title as set by @title...
# $T2H_THISDOC{subtitle} -- subtitle as set by @subtitle
# $T2H_THISDOC{author} -- author as set by @author
#
# and pointer to arrays of lines which need to be printed by t2h_print_lines
# $T2H_OVERVIEW -- lines of short table of contents
# $T2H_TOC -- lines of table of contents
# $T2H_TOP -- lines of Top texinfo node
# $T2H_THIS_SECTION -- lines of 'This' section
#
# There are the following subs which control the layout:
#
$T2H_print_section = \&T2H_DEFAULT_print_section;
$T2H_print_Top_header = \&T2H_DEFAULT_print_Top_header;
$T2H_print_Top_footer = \&T2H_DEFAULT_print_Top_footer;
$T2H_print_Top = \&T2H_DEFAULT_print_Top;
$T2H_print_Toc = \&T2H_DEFAULT_print_Toc;
$T2H_print_Overview = \&T2H_DEFAULT_print_Overview;
$T2H_print_Footnotes = \&T2H_DEFAULT_print_Footnotes;
$T2H_print_About = \&T2H_DEFAULT_print_About;
$T2H_print_misc_header = \&T2H_DEFAULT_print_misc_header;
$T2H_print_misc_footer = \&T2H_DEFAULT_print_misc_footer;
$T2H_print_misc = \&T2H_DEFAULT_print_misc;
$T2H_print_chapter_header = \&T2H_DEFAULT_print_chapter_header;
$T2H_print_chapter_footer = \&T2H_DEFAULT_print_chapter_footer;
$T2H_print_page_head = \&T2H_DEFAULT_print_page_head;
$T2H_print_page_foot = \&T2H_DEFAULT_print_page_foot;
$T2H_print_head_navigation = \&T2H_DEFAULT_print_head_navigation;
$T2H_print_foot_navigation = \&T2H_DEFAULT_print_foot_navigation;
$T2H_button_icon_img = \&T2H_DEFAULT_button_icon_img;
$T2H_print_navigation = \&T2H_DEFAULT_print_navigation;
$T2H_about_body = \&T2H_DEFAULT_about_body;
$T2H_print_frame = \&T2H_DEFAULT_print_frame;
$T2H_print_toc_frame = \&T2H_DEFAULT_print_toc_frame;
########################################################################
# Layout for html for every sections
#
sub T2H_DEFAULT_print_section
{
my $fh = shift;
local $T2H_BUTTONS = \@T2H_SECTION_BUTTONS;
&$T2H_print_head_navigation($fh) if $T2H_SECTION_NAVIGATION;
my $nw = t2h_print_lines($fh);
if ($T2H_SPLIT eq 'section' && $T2H_SECTION_NAVIGATION)
{
&$T2H_print_foot_navigation($fh, $nw);
}
else
{
print $fh '
' . "\n";
}
}
###################################################################
# Layout of top-page I recommend that you use @ifnothtml, @ifhtml,
# @html within the Top texinfo node to specify content of top-level
# page.
#
# If you enclose everything in @ifnothtml, then title, subtitle,
# author and overview is printed
# T2H_HREF of Next, Prev, Up, Forward, Back are not defined
# if $T2H_SPLIT then Top page is in its own html file
sub T2H_DEFAULT_print_Top_header
{
&$T2H_print_page_head(@_) if $T2H_SPLIT;
t2h_print_label(@_); # this needs to be called, otherwise no label set
&$T2H_print_head_navigation(@_);
}
sub T2H_DEFAULT_print_Top_footer
{
&$T2H_print_foot_navigation(@_);
&$T2H_print_page_foot(@_) if $T2H_SPLIT;
}
sub T2H_DEFAULT_print_Top
{
my $fh = shift;
# for redefining navigation buttons use:
# local $T2H_BUTTONS = [...];
# as it is, 'Top', 'Contents', 'Index', 'About' are printed
local $T2H_BUTTONS = \@T2H_MISC_BUTTONS;
&$T2H_print_Top_header($fh);
if ($T2H_THIS_SECTION)
{
# if top-level node has content, then print it with extra header
print $fh "$T2H_NAME{Top}
"
unless ($T2H_HAS_TOP_HEADING);
t2h_print_lines($fh, $T2H_THIS_SECTION)
}
else
{
# top-level node is fully enclosed in @ifnothtml
# print fulltitle, subtitle, author, Overview
print $fh
"\n" .
join("
\n", split(/\n/, $T2H_THISDOC{fulltitle})) .
"
\n";
print $fh "$T2H_THISDOC{subtitle}
\n" if $T2H_THISDOC{subtitle};
print $fh "$T2H_THISDOC{author}\n" if $T2H_THISDOC{author};
print $fh <
Overview:
EOT
t2h_print_lines($fh, $T2H_OVERVIEW);
print $fh "
\n";
}
&$T2H_print_Top_footer($fh);
}
###################################################################
# Layout of Toc, Overview, and Footnotes pages
# By default, we use "normal" layout
# T2H_HREF of Next, Prev, Up, Forward, Back, etc are not defined
# use: local $T2H_BUTTONS = [...] to redefine navigation buttons
sub T2H_DEFAULT_print_Toc
{
return &$T2H_print_misc(@_);
}
sub T2H_DEFAULT_print_Overview
{
return &$T2H_print_misc(@_);
}
sub T2H_DEFAULT_print_Footnotes
{
return &$T2H_print_misc(@_);
}
sub T2H_DEFAULT_print_About
{
return &$T2H_print_misc(@_);
}
sub T2H_DEFAULT_print_misc_header
{
&$T2H_print_page_head(@_) if $T2H_SPLIT;
# this needs to be called, otherwise, no labels are set
t2h_print_label(@_);
&$T2H_print_head_navigation(@_);
}
sub T2H_DEFAULT_print_misc_footer
{
&$T2H_print_foot_navigation(@_);
&$T2H_print_page_foot(@_) if $T2H_SPLIT;
}
sub T2H_DEFAULT_print_misc
{
my $fh = shift;
local $T2H_BUTTONS = \@T2H_MISC_BUTTONS;
&$T2H_print_misc_header($fh);
print $fh "$T2H_NAME{This}
\n";
t2h_print_lines($fh);
&$T2H_print_misc_footer($fh);
}
###################################################################
# chapter_header and chapter_footer are only called if
# T2H_SPLIT eq 'chapter'
# chapter_header: after print_page_header, before print_section
# chapter_footer: after print_section of last section, before print_page_footer
#
# If you want to get rid of navigation stuff after each section,
# redefine print_section such that it does not call print_navigation,
# and put print_navigation into print_chapter_header
@T2H_CHAPTER_BUTTONS =
(
'FastBack', 'FastForward', ' ',
' ', ' ', ' ', ' ',
'Top', 'Contents', 'Index', 'About',
);
sub T2H_DEFAULT_print_chapter_header
{
# nothing to do there, by default
if (! $T2H_SECTION_NAVIGATION)
{
my $fh = shift;
local $T2H_BUTTONS = \@T2H_CHAPTER_BUTTONS;
&$T2H_print_navigation($fh);
print $fh "\n
\n";
}
}
sub T2H_DEFAULT_print_chapter_footer
{
local $T2H_BUTTONS = \@T2H_CHAPTER_BUTTONS;
&$T2H_print_navigation(@_);
}
###################################################################
$T2H_TODAY = &pretty_date; # like "20 September 1993"
sub pretty_date {
local($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst);
($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime(time);
$year += ($year < 70) ? 2000 : 1900;
# obachman: Let's do it as the Americans do
return($MONTH_NAMES->{$T2H_LANG}[$mon] . ", " . $mday . " " . $year);
}
###################################################################
# Layout of standard header and footer
#
# Set the default body text, inserted between
###$T2H_BODYTEXT = 'LANG="EN" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"';
$T2H_BODYTEXT = 'LANG="' . $T2H_LANG . '" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"';
# text inserted after
$T2H_AFTER_BODY_OPEN = '';
#text inserted before
$T2H_PRE_BODY_CLOSE = '';
# this is used in footer
$T2H_ADDRESS = "by $T2H_USER " if $T2H_USER;
$T2H_ADDRESS .= "on $T2H_TODAY";
# this is added inside after and some META NAME stuff
# can be used for <style> <script>, <meta> tags
$T2H_EXTRA_HEAD = '';
sub T2H_DEFAULT_print_page_head
{
my $fh = shift;
my $longtitle = "$T2H_THISDOC{title}: $T2H_NAME{This}";
print $fh <<EOT;
<HTML>
$T2H_DOCTYPE
<!-- Created on $T2H_TODAY by $THISPROG -->
<!--
$T2H_AUTHORS
-->
<HEAD>
<TITLE>$longtitle
$T2H_EXTRA_HEAD
$T2H_AFTER_BODY_OPEN
EOT
}
sub T2H_DEFAULT_print_page_foot
{
my $fh = shift;
print $fh <
This document was generated
$T2H_ADDRESS
using texi2html
$T2H_PRE_BODY_CLOSE